This repo contains all code related to LHR Solar's Battery Protection System (BPS) The Documentation for the BPS contains other useful software and an in depth explanation of our architecture.
NOTE: As of 2023, the simulator for the BPS repository is deprecated.
Development is done in a Linux environment to build and flash the BPS program.
Cloning repos onto your machine is usually straightforward, but our RTOS project depend on uCOS-III-Simulator and uCOS-III-STM32F4 repos. Extra steps must be taken to correctly pull submodules. Submodules are repos that are inside a repo.
The most common way to clone repos is to use the HTTPS link, but the most secure way is to clone with SSH. The submodules use SSH, so you must generate and add an SSH key to your GitHub account. Follow the instructions in this tutorial. If this is your first time doing this, you can start at the Generating a new SSH key and adding it to the ssh-agent step, but reading everything is beneficial.
Once you're able to use Git with SSH, go to the green "Code" button of the repo, and click "Use SSH" to get the URL. Copy the git@hithub.com:repo-name
link. Then, enter the following command to the terminal but with the correct URL:
git clone --recurse-submodules git@github.com:repo-name
If you already cloned the repo but don't have the submodules, enter the following commands:
git submodule init
git submodule update --remote
The BPS is designed be built and deployed from a Linux terminal, allowing you to use your choice of text editor/IDE.
sudo apt install gcc gdb
/etc/security/limits.conf
then restart your machine:
<username> - rtprio unlimited
The tabbing MUST MATCH the other dashes at the bottom of the file, otherwise this will not work!
Run make help
for more information on usage.
When calling any of the following commands, make sure you are in the top level of the repo.
Call make bsp_type
to compile the release version of the code. bsp_type
is the system you want to compile for. It can either be
stm32f4132
or simulator
. The stm32f413 version is selected by default.
Call make help
for more information on how to build the project.
Call make clean
if the build fails for any reason other than syntax related.
The BPS has an RTOS version and a bare metal version for its BSP files. To select which one to build, pass either RTOS
or BAREMETAL
to the OS
argument. For example
make simulator OS=BAREMETAL
will build the bare metal version, and
make simulator OS=RTOS
will build the RTOS version. The RTOS version is selected by default.
The BPS configuration settings can be modified from the command line from Make. In the top-level of the repo,
you can specify DEFINES=
alongside the make
command to override values from the configuration
header file with the values you specify. For example
make test=Voltage DEFINES=NUM_MINIONS=2
Would update the BPS build to use 2 minion boards in the code and calculations as opposed to 3.
Run make help
for more information on usage.
For testing, please read the Testing section.
To build a new test, you need to use the following command:
make bsp_type TEST=x
x
specifies which test you want to compile. TEST= is optional and only required if a test is to be compiled. Set TEST equal to the suffix of the Test_ Src files i.e. if the test you want to run is in Test_x.c, set TEST=x.
E.g. Call make stm32f413 TEST=Voltage
if you want to test Voltage.c with the Test_Voltage.c src fileWhen calling any of the following commands, make sure you are in the top most level of the directory. You must be on a Linux VM or dual boot machine. Consider using VMWARE using this free license key
st-util
make flash
to flash the most recently built BPS code. You may need to run this with sudo
.The following testing information is specifically for terminal development.
OpenOCD is a debugger program that is open source and compatible with the STM32F413. GDB is a debugger program that can be used to step through a program as it is being run on the board. To use, you need two terminals open, as well as a USB connection to the ST-Link programmer (as if you were going to flash the program to the board).
./openocd-debug.sh
in one terminal.gdb-multiarch ./Objects/bps-leader.elf
(assuming that you are doing this in the root of the project directory.target extended-remote localhost:4242
, which will connect to the st-util command from earlier.Note: If you get an error message for Permission denied, try giving openocd read/write permissions using chmod: chmod 764 openocd
https://linuxcommand.org/lc3_lts0090.php
The simulator reads input from a JSON file to simulate dummy values and dumps output to a log file to simulate controlling the BPS's peripherals. The goal is to create repeatable tests that can be checked automatically by using the same test file, and by parsing the log file.
The simulator can be compiled with make simulator
. The simulator also has an optional command line argument TEST=
to specify the name of the test file to run.
Note: when typing name it, don't type the Test_
part or the .c
part.
Example: make simulator TEST=SimulatorInit
.
The simulator can be run with ./bps-simulator.out <path to JSON test>
. However, in order to run properly, ulimit -r
must be set from within a script. In order to debug, edit the test.sh
file
to either debug, or just run a specific test.
You can check the log file by doing cat bps-sim-<logged time>.log
.
Commit frequently into your own branches. Create a Pull Request whenever you are ready to add you working code to the master branch. Make sure that your code compiles without any errors or warnings before you open a pull request. At least one approver must approve your pull request before it can be merged. The reviewers will make sure everything is up to par with the coding standards.
You can review a pull request even if you are not an approver. In addition to helping us catch bugs, code reviews are a good opportunity to learn more about the BPS codebase. Some examples on what you can include in a code review are:
You can either approve, comment, or request changes at the end of your pull request. These are the scenarios in which I would use each option: