#set enum(numbering: "1.a.i.") #align(center)[#text(size:2em, weight:"bold")[EET Boxes Setup Instruction]] #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. 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: + 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`. + #text(fill:red)[??] + 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` For later 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`. 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 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. + 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. + Under `Memories` in the left sidebar, select the file to flash 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. The finale step is to restart the aggregator to apply all the changes. + SSH into the `sf-pc48` server. + #text(fill:red)[write command] = 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.