This document describes how to run the embeNET demo application on NUCLEO-WL55JC boards.
Optionally, to play with the MQTT-SN demo service you'll need:
Optionally, to easily interact with the custom UDP service you'll need
Picture below presents the architecture of the embeNET network presented in this demo.
The PC acts as a Border Router and becomes the gateway to the network. One Nucleo board runnig the Root firmware is connected to the PC via USB cable and acts as a network interface. The other Nucleo boards are running the Node firmware. When running the Border Router application, it connects to the root using serial connection (COM in Windows) and a new network interface is registered in the system. All other Nucleo boards then join the network as nodes. Since embeNET is a true mesh network, every node in the network is a router and can extend the network through successive hops.
The embeNET demo package for Nucleo-WL55JC is distributed as a single ZIP file. Unzip it into a convenient location on disk. Inside you'll find a couple of folders:
A pre-build firware hex files are available inside the embenet_demo_hex folder. You can upload them to the boards using a tool of your choice. We recommend the STM32CubeProgrammer. Here are the steps needed to get started.
Download and install the STM32CubeProgrammer
Run the STM32CubeProgrammer tool and connect the Nucleo-WL55JC board to your PC. Next hit the "Connect" button.
You should see a log similar to this and a status that connection was successful.
Next hit the "Open file" button and select the firmware file you want to upload.
Go to the embenet_demo_hex folder and select:
Finally hit the "Download" button to program the board.
A "File download complete" message should confirm that the firmware was properly downloaded.
Please note that by default the code will not run until you reset the board.
Now you should have one Nucleo board running Root firmware and at least one or more Nucleo boards running the Node firmware.
Download and install the STM32CubeIDE.
Once you have it installed, open it and import the project located in embenet_demo_src folder.
You should see and navigate a project called "embenet_node_demo".
Within the project there will be following folders:
The project has two build configurations: Root and Node. You can switch between them using the "Build Configurations" project option.
Right click on the project name and select "Build Configurations" -> "Set Active" -> "Node". Build the demo application using the Build project option.
The application should build without errors. Connect the Nucleo board that should act as a node. From the Run menu select the embenet_node_demo configuration to program the board. If the configuration is not visible, mark it as favorite in the Organize favorites... menu
Right click on the project name and select "Build Configurations" -> "Set Active" -> "Root". Build the demo application using the Build project option.
The application should build without errors. Connect the Nucleo board that should act as a root. From the Run menu select the embenet_root_demo configuration to program the board. If the configuration is not visible, mark it as favorite in the Organize favorites... menu
The Nucleo boards have an on-board ST-LINK programmer. Once connected to your computer the board will register in the system with its own ST-LINK Virtual COM Port (VCP).
To obtain log from Node you need to run your favorite serial terminal (like Putty), and open connection to this COM port with 115200 baurate.
Note that log from Root is not available through the Virtual COM Port because it is used to communicate with the Border Router application. Therefore log from Root is available on an additional pin (CN10: pin 35) as shown in the picture below :
Once you have the boards programmed you can see the demo in action.
To start the network you need to connect the root Nucleo board to the PC. It should register as a COM port. Next go to the embenet_br folder and edit the config.json file that holds the border router configuration. The file will look similar to this:
The file has the following entries:
Please edit the file to make sure that the serial_port entry matches the COM port registered for the root board.
Each node in the network, including root has an IPv6 address consisting of two parts:
prefix:uid
where the prefix is set for the network in the config.json file and the uid is the 64-bit IEEE EUI-64 identifier, also know as the MAC address. In case of Nucleo-WL55JC boards it is printed on the ST-Link chip in the bottom-left part of the board, near the micro-USB socket.
Each node that wishes to join the embeNET network needs to be authorized by the built-in Authentication Authority. The authentication process uses a pre-shared key (psk), that needs to be configured in the nodes during commissioning. In the provided demo application firmware the key is hardcoded in main.c file. During the authentication process both the uid and psk have to match what is defined in the join_rules in order to let the node join the network. However, when uid is set to 0, EVERY node with matching psk (pre-shared key) will be able to join the network. We call it the "zero rule". It is useful for testing and experimenting, however it should probably be disabled in the real deployment.
The network is started once you run the border router application embenet_br.exe. The application will try to connect to the root node and then manage the network.
This is a console application that will also log a lot of information about what is going on in the network and what packets are received from the nodes. Analyzing this log may help dealing with problems, if they arise during the further development process.
Once the border router application is running, all nodes within the communication range, should start to join the network. Be aware that this process may take couple of minutes depending on the network topology and the state of the nodes. For example: nodes that previously joined the network may require some time to notice that the border router was restarted before they attempt to join again.
While running, the border router application registers a virtual network interface within Windows. The interface name will be set according to the config.json file. You can check the presence of this interface by running the standard Windows command:
ipconfig
Also, each connected node is reachable by ICMPv6 'ping'.
The demo package includes an application that visualizes the network. It is called enms_visualizer and it is based on the ENMS service running in the background of the network. To use it simply run the application while the network is running. After a minute or so the ENMS messages will feed the application with the current state of the network, that will be visualized as a graph, spanning from the root node.
Exemplary topology with two nodes may look like this:
A network service in embeNET, is a separated piece of functionality built around the communication over a single UDP port (rarely - multiple UDP ports). Three examples of services distributed with the embeNET stack are:
The users however can easily develop their own services using UDP. An example of such a custom UDP service is implemented in the demo nodes.
The MQTT-SN demo service uses MQTT-SN client and does three things:
Refer to Using MQTT-SN demo service for more information on how this service works and how to use it.
The custom service implemented in the demo works on UDP port number 1234. Please note that this service works on remote nodes only - it is not available in root node. The service does two things:
There are many ways you can interact with UDP ports to test this service. One of the easiest is to use an application called UDP - Sender/Reciever app from Microsoft Store. Once you run set the mode to Sender/Receiver. Next, in the Remote IP box input the IPv6 address of the remote node that you wish to communicate with. When using the default network prefix, this IP address will have the following form:
where the UID will be the MAC address of the node.
In the Remote Port and Local Port boxes put port number: 1234
Once you hit Connect you should see incoming text messages. You can also send some commands to light the LEDs on and off.
In order to get to know the internals of the demo and to modify or extend it refer to Internals of the embeNET demo for NUCLEO-WL55JC board.
In order to test MQTT-SN part of the demo go to Using MQTT-SN demo service.
Any question or remarks? Just write us a message!
Feel free to get in touch