HiveMind

The HiveMind is the embedded application that provides swarm capabilities which runs on SwarmUS HiveBoard.

Requirements

• ROS Noetic for building the POSIX target

  • ROS melodic should compile and run normally if you have cmake 3.13, but you won't be able to compile the tests since it comes with googletest 1.8 and not 1.10

• CMake 3.13

• Gcc or arm-gcc-none-eabi for the embedded targets.

• Buzz to compile the user buzz script.

• Protoc and some python deps to build Propolis. Check Propolis repo for more info

• OpenOCD. Note that version 0.11 or higher is required for the HiveBoard.

• Development tools

  • Clang tools are used to match the style and warnings used in the project
    • clang-format to match the coding style
    • clang-tidy for additional compiler warnings
  • Doxygen and graphviz to generate the documentation

Building

ROS

Before building for the ROS environment variables need to be sourced by running the command or adding them to .bashrc otherwise the ROS build will fail.

source /opt/ros/noetic/setup.bash

In the source directory.

mkdir build
cd build
cmake ..
make

Or you can simply use catkin_make instead.

cd catkin_ws
catkin_make

Embedded

To generate the build system and compile

mkdir build
cd build

For the F4

cmake -D CMAKE_BUILD_TYPE=Debug -D CMAKE_TOOLCHAIN_FILE=../cmake/stm32_f429zi_gcc.cmake ..

For the H7/HiveBoard

cmake -D CMAKE_BUILD_TYPE=Debug -D CMAKE_TOOLCHAIN_FILE=../cmake/stm32_h735zg_gcc.cmake ..

You can then flash using make flash and see the log output using screen /dev/ttyUSBXXX where XXX is the USB number of the board.

OpenOCD Lib USB error

You may need to add the udev rules and add groups permissions to your user. If you get a LIBUSB_ERROR_ACCESS follow these step.

Copy the udev rules

sudo cp ./tools/udev-rules/* /etc/udev/rules.d/

Reload the udev manager

sudo udevadm control --reload-rules
sudo udevadm trigger

Add yourself in the plugdev (to flash) and dialout to read the tty output without sudo

sudo usermod -a -G plugdev $USER
sudo usermod -a -G dialout $USER

Development

For development you may want to use the warnings and static checks used by the team

If you want all the warnings used by the team, use this command for cmake build generation. And if you have clang-tidy installed, the build will use it for static analysis.

Check the cmake options for more information.

cmake -DENABLE_ERROR_ON_MISSING_TOOL=ON -DENABLE_WARNINGS_AS_ERROR=ON -DENABLE_WARNINGS=ON -DENABLE_CLANG_TIDY_CHECK=ON -DENABLE_TESTS=ON -DCMAKE_BUILD_TYPE=Debug ..

or using catkin

cd catkin_ws
catkin_make -DENABLE_ERROR_ON_MISSING_TOOL=ON -DENABLE_WARNINGS_AS_ERROR=ON -DENABLE_WARNINGS=ON -DENABLE_CLANG_TIDY_CHECK=ON -DENABLE_TESTS=ON -DCMAKE_BUILD_TYPE=Debug

Just add the required toolchain to build for the embedded targets.

cmake -DENABLE_ERROR_ON_MISSING_TOOL=ON -DENABLE_WARNINGS_AS_ERROR=ON -DENABLE_WARNINGS=ON -DENABLE_CLANG_TIDY_CHECK=ON -DENABLE_TESTS=ON -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=../cmake/TOOLCHAINFILE.cmake ..

Note that as of now, the tests can only be built on the native target.

Running

You can run the ROS build using this command.

roslaunch hive_mind hive_mind.launch

you can edit, or create a new launch file to change the parameters

Flashing

Install OpenOCD. Then you can flash using the provided make flashcommand or directly via openocd.

For the F4

openocd -f ./tools/openocd/stm32_f4/stm32_f4.cfg -c "program build/src/hive-mind.elf verify reset exit"

For the H7

openocd -f ./tools/openocd/stm32_h7/hiveboard.cfg -c "program build/src/hive-mind.elf verify reset exit"

Mass Erase

A mass erase of the flash on the H7 target can be done via the make mass_erase command or via openocd:

openocd -f ./tools/openocd/stm32_h7/hiveboard.cfg -c 'init' -c 'halt' -c 'stm32h7x mass_erase 0' -c 'reset run' -c 'shutdown'

Running tests

Software Tests

You can use make test or ctest to launch the tests on the native build.

Hardware Tests

Two different kind of tests can be run to verify the functionality of the HiveBoard.

The first series of tests use the HAL library directly and are therefore purely hardware/driver tests. These tests can only be run one the HiveBoard (STM32H7) as some tested components are not available on the previous Nucleo STM32F4 + HiveSight assembly. To compile the tests, CMake must be run with the ENABLE_HARDWARE_TESTS variable.

cmake -D CMAKE_BUILD_TYPE=Debug -D ENABLE_HARDWARE_TESTS -D CMAKE_TOOLCHAIN_FILE=../cmake/stm32_h735zg_gcc.cmake ..

From there, a second target, hardware_tests.elf can be compiled and flashed with OpenOCD. The make flash_tests target can be used to flash.

The tests are not self-validating and must be run through a debugger stepping instruction by instruction to verify everything is working.

The second series of tests are aimed at validating the functionality of the BeeBoards and more specifically, the DW1000 UWB Radio. These tests are activated by setting the DECAWAVE_TESTS variable to one of three values:

• TX, to transmit data via UWB in a loop
• RX, to receive UWB data and log it to the serial logger
• SPI, to perform a SPI write/readback test on the DW1000 in a loop
• LED, to flash all LEDs that are controlled by the DW1000

For example, to test TX, you would compile with:

cmake -D CMAKE_BUILD_TYPE=Debug -D DECAWAVE_TESTS=TX -D CMAKE_TOOLCHAIN_FILE=../cmake/TOOLCHAINFILE.cmake ..

As with the hardware tests, a make target (make flash_deca_tests) was created for flashing the board.

Formatting

You can run make format and make check-format to match the formatting convention used.

Doc

The documentation is built using doxygen. The doc will be built on make all target, if you need to only rebuild the doc, use make doc.

An up to date version of the master branch documentation for the native build can be found here

Debugging

OpenOCD has a gdb server that defaults to port 3333, you can then connect to it using arm-none-eabi-gdb. The server can be launched using this command

For the F4:

openocd -f ./tools/openocd/stm32_f4/stm32_f4.cfg -c init -c \"reset init\"

For the H7/HiveBoard:

openocd -f ./tools/openocd/stm32_h7/hiveboard.cfg -c init -c \"reset init\"

You can use the ENABLE_TARGET_RUNTIME_STATS CMake option on the H7 to get a periodic log of the task usage.

External connections

Ethernet port

The firmware assigns a static IP of 192.168.1.10 to the device with a subnet mask of 255.255.255.0.

The ethernet speed can be measured with iperf 2. To open the server on the device, simply build with the ENABLE_TARGET_IPERF_SERVER CMake option:

cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_TARGET_IPERF_SERVER -DCMAKE_TOOLCHAIN_FILE=TOOLCHAINFILE.cmake ..

Configuration

Different firmware settings can be configured at build time (for the STM32 target) or runtime (for the ROS target).

Log level

It's possible to change the log level, check how to configure the build depending on the platform. Here are the levels available:

• Debug
• Info
• Warn
• Error

STM32 Target

CMake variables can be used to override certain default firmware settings.

Variable	Default value
HOST_PORT	7001
HOST_IP	192.168.1.101
LOG_LEVEL	Info
MAX_AGENTS_IN_SWARM	6
BBZVM_STEP_DELAY_MS	50

The variable MAX_AGENTS_IN_SWARM is used to define how many timeslots to create in the interlocalisation state machine. Make sure this number is at least equal to the highest agent ID present in the swarm.

The CMake variable UUID_OVERRIDE may also be used to change the UUID value currently saved in the non-volatile memory. Make sure each UUID in your swarm is unique.

ROS Target

ROS launch parameters are used to configure variables.

Variable	Default value
board_uuid	1 (0 is reserved for broadcast)
host_tcp_port	7001
host_tcp_address	127.0.0.1
remote_mock_port	12346
log_level	Info
bbzvm_step_delay_ms	50