Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

The firmware of NAMeC

This documentation is here to help you have a high-level overview of the different repositories and custom librairies used throughout the different firmware.

There are in total 5 different components that require their own firmware, namely :

  • the robot firmware
  • the base station, that emits commands to all robots
  • the dribbler
  • each motor card
  • the kicker card

Each of those have their own repository inside the NAMeC-Team organization on GitHub. But some librairies have been tailored for usage with our firmware, such as the library handling our radio module. You can find all of the links at a given chapter

## Dev environment Almost all of our repositories use the mBed RTOS. Briefly, you’ll find in an mBed project

  • the source code inside src/
  • one .lib file per library and its associated folder (that appears after running mbed deploy)
  • a .mbed file describing the project
  • a BUILD folder that contains the compiled code

This means you can find out which librairies a project uses by looking at the .libi files, which are merely links to Git repositories.

Only the dribbler, which uses STM32CubeIDE, is compiled differently. One day we’ll move it to mBed (or something else, idk).

## Protobuf for message transmission All of the messages that are transmitted, whether via radio or SPI, are Protobuf packets. We use the nanopb library to serialize and deserialize our Protobuf packets.

For those who don’t know Protobuf, it’s a way of easily transforming structured data into binary. We define the structure of our message in .proto files, and the Protobuf compiler’s job is to transform those into structures or objects, in the language of our choice (in our case, C++). All Protobuf messages can be found in the sensor-data-protocol internal library.

## Flashing We use a JTag connector to flash the robot, motor, and dribbler firmware. The way you must plug in the cable is (to be described)

Repository links

All repositories are hosted on GitHub, in the NAMeC-Team organization. If you do not have access, please contact the team leader (on Discord, preferably).

Code repositories

Internal libraries

External libraries

  • mBed
  • 6tron Zest core nanopb : it’s weird, we cloned the official repo in our organization. that seems anormal.

All of the following are hosted on our GitHub org, but not made by us

Robot

The robot firmware uses an EventQueue across the code to perform tasks whenever interrupts occur, as well as when communicating with the motors.

Motor communication

Periodic transmission

We start a periodic communication with each motor card on the SPI bus. Access to the SPI bus is mutex-protected and is automatically handled by the EventQueue. The mutex is important because physically, all motors are connected to the same SPI bus.

The messages passed are MainBoardToBrushless and BrushlessToMainboard, stored in brushless.proto inside the sensor-data-protocol repository.

Motors return an error count, which represents the number of times the motor card decoded the message sent from the mainboard and computed a CRC that did not match the passed CRC.

SPI Watchdog

A watchdog is in place inside the motor code, such that if the motor does not receive any SPI message after a fixed amount of time, the motor reboots entirely. This stems from the fact that F1 chips on the motor cards had a bug that blocked the SPI bus (or at least that was what I was told), so this measure has been put in place.

Orders sent

The motors are speed-controlled and obey to the commands they’re told to perform by the robot card. Once we receive a speed order from the decision software, through the base station, we transform this robot-frame speed order into 4 separate target speeds to transmit to each motor. This is performed in the compute_motor_speed() function. The mathematics are based on formulas that were tailored for our robot, which is uneven because two wheels are at a 30 degree angle, and the other two wheels at a 45 degree angle. You can search up one of the TDPs of NAMeC that should explain these formulas more in detail.

On their side, the code of the motors have their own PID to ensure the ordered target speed is respected. Tuning of the PID coefficients has been performed some years ago, but never tuned again.

Receiving commands over radio

Robot ID is hardcoded inside the robot. The nRF24L01+ radio module we use can have a physical address that can be assigned at startup. Our code does not make use of this feature (yet). Instead, we broadcast the radio command to all robots (they all have the same physical address), making it go through the radio module, that forwards it to our code.

Inside our code, we deserialize the Protobuf packet, and check if this packet is meant for us (there is a robot id field in the packet). If this packet wasn’t meant for us, we ignore it.

Time consumptino of this operation was not benchmarked, but it is pretty clear that it is very inefficient (why would robot 5 have to process 6 packets where it could’ve only processed 1 instead ?).

Dribbler control

Base station

Motor

Dribbler

Kicker