192 lines
10 KiB
Typst
192 lines
10 KiB
Typst
#import "@preview/showybox:2.0.1": showybox
|
|
#set enum(numbering: "1.a.i.")
|
|
#set heading(numbering: "1.1.")
|
|
|
|
#let hash_line(w:20pt, reverse:false, angle:0deg) = [
|
|
#let n = 15
|
|
#stack(
|
|
dir: ltr,
|
|
spacing: 1fr,
|
|
.. n*(rotate(if reverse{angle} else{-angle})[#rect(width:w,height:w/3, fill:red, radius:1pt)],),
|
|
)
|
|
]
|
|
|
|
#set page("us-letter",
|
|
margin: (y: 5%, x:10%),
|
|
)
|
|
|
|
|
|
#hash_line()
|
|
#align(center)[#text(size:2em, weight:"bold")[EET Boxes Setup Instruction]]
|
|
#hash_line()
|
|
|
|
#outline()
|
|
|
|
= Preparation
|
|
Each box is composed of a few components:
|
|
- The base board where the FPGA, microcontroller, and ethernet port are installed.
|
|
- The adapter board that plugs in the base board and provide the input and output power connectors.
|
|
- The case, composed of the bottom and top plastic parts and the front and back metal plates.
|
|
- The hardware: screws, spacers, spings.
|
|
- A label with the device Id and the version.
|
|
|
|
When fully setup, the box should have all the software and the complete case installed.
|
|
|
|
Before starting the setup, it is recomended to reset the boxe to wipe any remaining configuration.
|
|
To do so, provide power to the box by plugging in the ethernet cable and use a jumper cable to connect the 3.3V and ERASE pads on the base board for five seconds.
|
|
After removeing the jumper connection, power cycle the device.
|
|
|
|
= Flashing the FPGA
|
|
|
|
The FGPA is the largest square ship on the base board.
|
|
The port to flash the FGPA is the vertical receptacle located the closest to the FPGA.
|
|
Here are the steps to follow to flash the FPGA.
|
|
|
|
+ Power ON the box using the ethernet cable.
|
|
+ Connect the FPGA adapter cable to the FPGA port on the base board and to a USB port on the PC.
|
|
+ If using a virtual machine, go to `Device` #sym.arrow `USB` and tick the box next to `FPGA Programmer Cable`. If the Latice Diamond software was already running and still cannot see the cable, restart it.
|
|
+ Start the Latice Diamond software and open the `palidaq` project.
|
|
+ Go to `tools` #sym.arrow `Programmer`.
|
|
+ For the first time, change the file name to `fpga/src/impl1/palidaq_imp1.jed`.
|
|
+ For the first time, change the `Operation` to `FLASH Erase, Program, Verify, Secure`.
|
|
+ Save this configuration with `ctrl+s`.
|
|
+ On the right under `Cable Settings` select `Detect Cable` and verify that there is no error in the console. If you do have an error, make sure the box is receiving power.
|
|
+ Flash the firmware with the `Program` icon (down green arrow button above the operation line).
|
|
|
|
Congratulation, the FPGA is ready now.
|
|
|
|
= Flashing Base Firmware
|
|
|
|
The base firmware is common to all boxes.
|
|
To flash the base firmware to the Atmel microcontroller, follow these steps:
|
|
|
|
For flashing of the firmware, it is also required to set the GPNVM bits to 0x42.
|
|
+ In the `Device Programming` tool, select in the left sidebar `GPNVM Bits`.
|
|
+ If the value is anything other than 0x42, set the value to 0x42 and click `Program`.
|
|
|
|
+ Power ON the box using the ethernet cable.
|
|
+ Connect the Atmel adapter to the base board using the vertical port closest to the Atmel chip.
|
|
+ If using a virtual machine, enable the USB device as for the FPGA.
|
|
+ Open the Microchip software.
|
|
+ Select `Tools` #sym.arrow `Device Programming`.
|
|
+ In the Device dropdown select your device based on the final characters etched on the Atmel chip:
|
|
+ ATSAMV71Q19B for the Q19
|
|
+ ATSAME70Q20B for the Q20
|
|
+ ATMSAME70Q21B for the Q21
|
|
+ Select `SWD` in the interface dropdown. Make sure the cable from the adapter to the board is connected to the SWD port.
|
|
+ Press `Apply`.
|
|
+ Press `Read` next to the `Device Signature` box and make sure the device ID updated.
|
|
+ Select `Memories` in the left sidebar.
|
|
+ Ensure the selected file is `application.elf` either in the `Debug` or `Debug_V71Q19B` folder.
|
|
+ Press `Programm`
|
|
|
|
|
|
To set the security bits that disable recovery of the firmware, select `Security` in the left sidebar of the `Devide Programming` menu and press `Set`.
|
|
|
|
= Registering Device
|
|
|
|
The firmware of the box contains the information for the conecting to the server.
|
|
To get these information, you first need to register the new box in Palitronica system.
|
|
The frontend #footnote[https://steetdev001.z27.web.core.windows.net/] lists all boxes across all tenants and can be used for some operations but we will mainly use it to register a new box.
|
|
|
|
In order to register a new device, you need some information including the `MCU Serial` and the `MAC Address` of the box.
|
|
These two info are not directly readable on the box and require to use a script on the machine.
|
|
|
|
+ After flashing the FPGA and the base firmware, connect the ethernet cable of the box to a PoE switch on the same network as the PC.
|
|
+ Get into the virtual environment of the script with `source .venv/bin/activate`.
|
|
+ Run `python3 udp_server.py`.
|
|
+ After a few seconds, the script should output the `MCU Serial` and `MAC Address` of the box.
|
|
|
|
Now in the frontend, follow these steps:
|
|
|
|
+ On the sidebar, select `Inventory`
|
|
+ On the top right corner, select `Dev2 Lab` in teh dropdown menu.
|
|
+ Verify that no box with the same `Device Id` already exists in the inventiory.
|
|
+ Click the #sym.plus icon in the top right corner.
|
|
+ Fill the informations as follows:
|
|
|
|
#figure(
|
|
grid(
|
|
columns: 4,
|
|
gutter: 10pt,
|
|
stroke: 1pt + gray,
|
|
align: left + horizon,
|
|
inset: 0.5em,
|
|
[ *`Sensor Id`*\ On the label.], [*`MCU Serial`*\ From the Script], [*`HW Version`*\ On the label], [*`MCU Model No.`*
|
|
\ 1.00],
|
|
[*`Tenant`*\ Dev2 Lab], [*`Aggregator`*\ `sf-pc48`], [*`MAC address`*\ From the Script], [*`Chip`*\ Model of the Atmel chip],
|
|
[*`CAN Interface`*\ Likely False], [*`Power Connector`*\ Connectors of the daughter board], [*`Deployement Status`*\ Personal Us],
|
|
),
|
|
caption: "Information for registering a new device and where to find them."
|
|
)
|
|
|
|
+ Click `ADD`
|
|
|
|
Once the device is added to the frontend, you can find the connection string in the IoT Hub #footnote[https://portal.azure.com/#browse/Microsoft.Devices%2FIotHubs]
|
|
|
|
+ Select iothub-eet-dev-001 in the list.
|
|
+ Under `Device Management` #sym.arrow `Devices` select the new device you registered.
|
|
+ In the ` Primary connection string` select the part after `SharedAccessKey=`. Make sure to exclude the first "=" sign after `SharedAccessKey` but include the last "=" at the end of the connection string.
|
|
|
|
= Flashing RTOS Firmware
|
|
|
|
To flash the firmware, you first need to update the configuration file that stores the informarion specific to this box and then flash the rebuilt firmware to the box.
|
|
|
|
|
|
#showybox(
|
|
[But how do I get the connection string from my laptop to the computer?],
|
|
[You can use the `ntfy` utility on the computer to get the connection string.
|
|
To do so, start by listening on the constring topic on the computer with:\
|
|
`ntfy sub https://ntfy.aljeit.fr/constring`\
|
|
Then you can send the connection string (or any other message) to the server using the command:\
|
|
`curl -d "message" https://ntfy.aljeit.fr/constring`]
|
|
)
|
|
#footnote[See @ntfy for more info about the ntfy setup.]
|
|
|
|
+ Update the file in `base-firmware-new\application\src\aa_set_device_parameter_here.h`.
|
|
+ Change the `SAS_KEY` value to the connection string from the IoT Hub.
|
|
+ Change the `AZURE_DEVICE_ID` field to the Id of the box from the label.
|
|
+ If needed, change the `MCU_DEVICE_ID` field to the last three characters of the Atmel chip serial.
|
|
+ Save the configuration with `ctrl+s`.
|
|
+ Rebuild the firmware with `Build` #sym.arrow `Build Solution (F7)`.
|
|
+ Verify that the box is properly connected to both power and the Atmel adapter.
|
|
+ In `Tools` #sym.arrow `Device Programming` detect the box as for the base firmware.
|
|
+ First, flash again the base firmware. Under `Memories`, select the `[...]application.elf` file and program the chip.
|
|
+ Next, flash the `RTOS` firmware. Select the file that end with `V71Q19B_`#text(fill:orange)[`XXXX`]`.hex` with #text(fill:orange)[XXXX] a four-characters hexadecimal number.
|
|
+ Click `Program`.
|
|
|
|
Congratulation, the box is all flashed, you are almost done.
|
|
|
|
= IoT Hub Setup
|
|
|
|
Now that the box is flashed, power cycle it and connect it to a PoE enabled port that has internet access.
|
|
|
|
+ In the IoT Hub, under `iothub-eet-dev-001` #sym.arrow `Devices` select the newly flashed box.
|
|
+ Access the configuration in `Device Twin` in the top bar.
|
|
+ Make sure the field `properties` #sym.arrow `desired` #sym.arrow `enableTransmission` is set to `true`. If not, change it and save the configuration.
|
|
+ Access the aggregator configuration in `iothub-eet-dev-001` #sym.arrow `IoT Edge` #sym.arrow `sf-pc48` #sym.arrow `IRF` (bottom section) #sym.arrow `Module Identity Twin` (top bar).
|
|
+ In the config, in the `targets` array, add an entry following the same template as the other entries with two fields:
|
|
+ `interceptorId` is the Id of the box (printed on the label).
|
|
+ `targetId` is the name of the MinIO folder where all the data will be stored. By default, enter the same as the box Id.
|
|
+ Save the configuration.
|
|
|
|
= Verification
|
|
|
|
Go on MinIO and verify that a folder with the name of the box was created and that some data started comming in. If not, good luck debugging this mess (I recomend redoing everything...).
|
|
|
|
= Appendix
|
|
|
|
== Network Setup
|
|
The network setup to get the `udp_server.py` is specific so here are the instructions to replicate it.
|
|
|
|
- The PC running the `udp_server.py` script should get the IP `192.168.29.11`. I recomend setting a DHCP reservation at the router level.
|
|
- The boxes thould get an IP in the range `192.168.29.[101-120]`. I am not sure this is a scrict requirement but I recomend setting the DHCP range in the router to this range.
|
|
|
|
== ntfy Server <ntfy>
|
|
ntfy is a publish/subscribe system that allow simple publishing of messages with an http request to a central server.
|
|
In this case, the server is my (Arthur Grisel-Davy) server running the ntfy binary.
|
|
While this is more private than using the default public #link("ntfy.sh") server, keep in mind that anyone can subscribe to the `constring` topic and get the message.
|
|
there is no user authentication from the server.
|
|
However there is server authentication from the user using SSL.
|
|
I (Arthur Grisel-Davy), hereby swear never to intentionally store the constring messages, because I don't really care.
|
|
If you are concerned about this method for sharing the conection string, feel free to use any other method.
|