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.; 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???

Make Arduino functions working in Simulink when compiling (maybe declare Arduino functions as external in Simulink, so as the linker links them)

To implement brake motor