Sumodd mini-sumo robot

Sumodd is a mini-sumo robot developed from scratch, including firmware in C, 3D modelling and PCB design. See competition rules and robot requirements for mini-sumo robots here.

The idea for this project, the design of the firmware statemachine and some of the hardware choices were inspired by artfulbytes excellent youtube series where he made a sumo robot from scratch. See his project code here.

Documentation

The schematic and PCB layout KiCad files for the Sumodd motherboard are available in the sumodd-hardware repository, with more detailed documentation of the parts used and their layout on the board.

The 3D model for the sumo robot chassis, armor and other modules are created in Onshape, the models for the current v03 version are publicly available here.

Documentation of the robot's core functionality can be found in the docs directory, with scope captures for illustration.

• Firmware state machine
• Enemy detection with time of flight sensors
• Dohyo border line detection
• Remote start IR signal handling
• Motor control

Development

This project uses mise to manage tools and commands/tasks. If you'd rather not use it, inspect the mise.toml file to read which tools are required, and which commands it runs.

For more information on command usage, append --help to a command, e.g. mise run build --help. For an interactive overview of the available commands, run mise run.

Firmware overview

• Our application code and our driver code lives in app and app/drivers.
• The STM32CubeMX generated source and header files live in Src and Inc.
• External libraries live in external, at the time of writing it holds a Segger RTT library git submodule, used for logging in debug builds, ST's VL53L4CD driver and the Unity unit testing framework.
• Integration/HIL and unit tests live in tests.

We use the STM32 HAL to configure and interact with the hardware, and we use the STM32CubeMX software to generate the hardware initialization code for GPIO, I2C, ADC etc., as well as the initial CMake configuration.

If you'd like to view or mutate the current configuration in CubeMX, simply initialize a project from the sumo.ioc file in the root of this repo.

Building

# Defaults to debug
mise run build

# Alternatively, specify build preset
mise run build release

Flashing

To build, flash the firmware and reset the device:

# Build preset is required, defaults to debug
mise run flash

To build, flash, reset and attach an RTT logger to device:

# Build preset is required, defaults to debug
mise run launch

To reset the device:

mise run reset

To format the C application code with clang-format:

mise run reset

To lint the C application code with cppcheck:

mise run lint

Debugging

To debug the firmware, first build it with the debug preset, then install the probe-rs vscode extension. You can now start a DAP debug session with probe-rs in the vscode debugging tab.

• To launch a new debug session, which flashes first and resets the device, run the VSCode debugger with the .vscode/launch.json "probe-rs launch" configuration.
• Alternatively, to attach a debugger to a running device to inspect the current state, run the VS Code debugger with the .vscode/launch.json "probe-rs attach" configuration

You can also view logs sent over RTT in debug or integration test builds:

# Build preset is required, defaults to debug
mise run log

Flashing without probe-rs

The mise commands depend on probe-rs. If you don't want to use probe-rs for flashing and resetting, you can convert the .elf file to an ARM binary, then flash with st-flash, or whichever other method you prefer:

# Create the binary
arm-none-eabi-objcopy -O binary build/debug/sumo.elf build/debug/sumo.bin

# Flash it and reset the device
st-flash --reset write  build/debug/sumo.bin 0x08000000

Testing

To run the unity unit tests, run: mise run test

To run the HIL tests, connect the device, then repeat the build and flash steps above, but use the desired integration test cmake preset.

The currently existing integration test presets are:

• test-drive

For example, if you want to build, flash and attach a logger to an integration test, run:

mise run launch test-drive

Diagrams

PlantUML is used for diagrams, it depends on Java, which mise manages.

To download the jar file for platuml: mise run plantuml-setup. The path it downloads to is set in a mise variable, which may need to be adjusted to your local system.

To generate a UML png: mise run plantuml-generate. Defaults to state machine diagram UML.