SBBMicro

Introduction

This repository contains the source code for the self-balancing-bike micro-controller unit (Teensy 4.1-based 🚀️). The introduction shows the files and folders contained in this repository and how they are organized, the prerequisites necessary, and the procedures to be used in order to build and upload the code, to generate the documentation, and to automatically generate the control-algorithm code from the Simulink model (using matlab tools).

Windows is officially supported, although compilation is also implemented for Linux. MacOS is NOT supported.

Files

Files:

• controlModel.slx: control model implementation in Simulink
• gencode.m: MATLAB function for code generation from Simulink model
• params.sldd: Simulink parameters used in controlModel.slx
• build_linux.sh: build shell script for Linux
• build_win.bat: build shmell script for Windows
• Doxyfile: configuration file for documentation generation from source code using doxygen
• Makefile: makefile for building, uploading and documentation generation using make
• startup.m: startup file for MATLAB (just to add necessary path)
• INSTALL_PREREQ.md: guide for the installation of the pre-requisites
• README.md: readme file

Code folders:

• ./include: contains .h files included in source code
• ./src: contains source .c or .cpp files, including main file main.cpp
• ./lib: contains a folder for each used library, with file library.properties for defining the library properties (mandatory for arduino compiling) and .h and .cpp files (possibly contained in folder ./src/)
• ./tools/teensy: contains the core code for the Teensy microcontroller

Additional folders:

• ./tools/teensy-windows: build tools for Windows
• ./tools/teensy-linux: build tools for Linux
• ./docs/html: contains the documentation in html (generated automatically from source code using doxygen)
• ./docs/extra: contains extra documentation (user-written), which is included using doxygen
• ./matlab-tools: contains matlab tools usefull for code generation and other stuff
• ./hardware: contains the kicad project files
• ./.vscode: contains VS code property file(s)
• ./.build and .cache: hidden folders created only during compilation

Pre-requisites

• MATLAB/Simulink with the Embedded Coder Toolbox installed (>=2021a), for control algorithm code generation only

No other dependecies are necessary: all used libraries are already included in ./lib/.

Additional utilities (only recommended):

• make to build using the Makefile; alternativelly, shell or MATLAV scripts can be used
• Visual Studio Code with C/C++ extension for code completation
• Doxygen to generate the documentation
• KiCad to open the schematic files in ./hardware

See the installation guide for the pre-requisites for details.

Documentation

Documentation for the source code and the user-defined libraries (but not for other third-party libraries) can be generated from the source using Doxygen with

doxygen

or using make

make doc

Generated documentation includes only a html version in ./docs/html, with main file index.html. Documentation is also available on https://stefphd.github.io/SBBMicro/. A latex documentation may be also generated by setting

GENERATE_LATEX  = YES

in Doxyfile. The latex version will be in ./docs/latex, and can be compiled using latex with

cd ./docs/latex
make

which generates the pdf file ./doc/latex/refman.pdf.

\attention Latex documentation requires having both latex and make installed.

Code generation

Code generation of the control algorithm is performed via MATLAB/Simulink with the Embedded Coder Toolbox. Other toolboxes may be required. Code generation can be launch with MATLAB using

startup;
gencode

The general usage of this function is

startup;
gencode(modelname,dest_dir);

where modelname is the name of the Simulink model (without the *.slx extension included), while dest_dir is the destination directory: generated code is placed in ./dest_dir/modelname/src. If no modelname is given, the function uses the first *.slx file found in the current directory. If no destination directory is given, the functions uses ./lib. Code generation may be also performed using make, however this may take some time.

\note Toolboxes required by the code generation can be shown by running in MATLAB

startup;
check_toolbox();

\attention For a correct usage in this project the above functions should be run in the main directory, and not in ./matlab-tools/.

Building

Compilation is performed using the arduino-builder. Bash scripts provide simple usage depending on the operative system:

• Linux:

  ./build_linux.sh

  or

  bash build_linux.sh

  \note Tested with Arch-Linux x64.

• Windows:

  ./build_win.bat

  \note Tested with Windows 10 x64.

• MacOS: not implemented yet, however it should be similar to Linux.

Alternatively, one can use ctrl+shift+B to build the code in Visual Studio Code with both Linux and Windows (this makes use of build_linux.sh or build_win.sh depending on the operative system). One may also use make the building and uploading.

\note The above shell scripts perform both the building and the uploading: it is not possible to build or upload only.

Make tools

One may also use make for the building, uploading and the documentation generation. This allows several operations using similar syntax, so as to perform single operations at a time:

• make or make all to build and upload the code.
• make build to build the code only
• make upload to upload code only
• make clean to clean the build and cache directories
• make remake to clean, build and upload the code
• make rebuild to clean and rebuild
• make doc to build the documentation
• make cleandoc to clean the documentation
• make help to print the Makefile help

\note The above commands can be also used at the same time, e.g. make build doc to build and generate the documentation.

MATLAB make

As an alternative to make and gencode, the code generation, buiding, uploading and documentation generation may be also performed at the same time from within the MATLAB command window. This employs a MATLAB function name make in ./matlab-tool/. The function must be used inside MATLAB with the following syntax:

• make all or just make to generate code from the Simulink model, build and upload

• make gencode to generate the code only from the Simulink model. Note that this corresponds to call gencode with no input arguments, i.e. the first *.slx file found is used

• make build to build the code

• make upload to upload the code

• make clean to clean the build and cache directories

• make remake to clean, build and upload the code

• make rebuild to clean and rebuild

• make doc to build the documentation

• make cleandoc to clean the documentation

• make help to print the help.

\note Note that this function emulates the function gencode and the standard make commands. However, it does not require having make installed but only doxygen for the generation of the documentation.

\note The above commands can be also used at the same time, e.g. make build doc to build and generate the documentation.

Known issues

• Undefined identifiers found by Visual Studio Code, however this is only a C/C++ IntelliSense issue (compilation works fine)

\todo Doc: Documentaton for Simuling and code generation??? \todo Make Arduino functions working in Simulink when compiling (maybe declare Arduino functions as external in Simulink, so as the linker links them) \todo To implement brake motor