The C++ firmware for our Stepper-Locking-System hardware.
An overview (German) of this complete project is also available.
On the basis of stepper motor and its driver, the hall encoder and connected switches, the firmware implements a error-tolerant and robust state maschine with overwatchings of current state. At non-planned events like step losses it tries to recover from this.
This project currently contains two important branches:
baselegacy_compatibility(default)
The base branch all features necessary for the operation of the locking system.
The legacy_compatibility includes additional changes to base branch in order to be able work with the old central system, which is currently used in Netz39.
The process of compiling project and flash the binary to microcontroller is described in compile_flash.md.
For visualization of current state the system controls two LED-rings with integrated crossbar. Each unit has 42 LEDs. Both rings are visible from inside and outside respectively.
| appearance | description | meaning |
|---|---|---|
 |
The ring is full with green. | The door lock is open. You can entrance. |
 |
The crossbar is full with red. | The door lock is closed. You need the locking authorisation to open it. |
 |
The greens are whirling in the circle. The blue ones represent the progess of the operation. | The door lock is opening. |
 |
The reds are whirling in the circle. The blue ones represent the progess of the operation. | The door lock is closing. |
 |
The ring is full with green. In the crossbar a red dot is running back and forth. | A closing operation is planned but the door wing is still open. Close it to continue the operation. |
 |
Yellows distributed over the circle are wiggeling back and forth. | A unplanned event occurs. That can be step losses, hall encoder failure or external motor movement. However a normal operation is still possible by simply short press on the open/close buttons. See Troubleshooting section for more details. |
 |
Reds distributed over the circle are wiggeling back and forth. | A fatal error occurs. This can be the failure of stepper driver (like no 12V power) or calibration failed. In this mode you can manually drive the motor by pressing the open/close buttons for min. 2 seconds. With normal clicks on buttons you can start the calibration again. See Troubleshooting section for more details. |
 |
Yellows on both sides are wiggeling back and forth. | The calibration procedure is ongoing. |
 |
Yellows and greens are set opposite. Those are whirling in the circle. | The motor opens the door lock in manual mode by pressing the open button for min. 2 seconds. |
 |
Yellows and reds are set opposite. Those are whirling in the circle. | The motor closes the door lock in manual mode by pressing the close button for min. 2 seconds. |
In case of unwanted things, the door will give either warning or fatal error.
| animation | meaning |
|---|---|
|
warning: - step losses - hall encoder disconnection - external motor movement |
|
fatal error: - step driver disconnection - calibration failed |
step losses: At opening/closing, too many step losses are detected. Please make sure there are no obstacles and the door wing is closed correctly. Then retry the open/close action.
hall encoder disconnection: There is no connection to hall encoder. This has no impact on opening/closing actions, but there will be no step loss detection anymore. Make sure there is an I²C connection to the hall encoder mounted on the front of stepper motor.
external motor movement: The stepper motor has been moved externally. To get a normal state, simply use the open/close button.
step driver disconnection: Communication to the stepper driver has failed. One of the cause can be a failure of 12V supply. Please check the voltage.
calibration failed: At calibration step losses has occured or the lock switch can not be triggered by the lock bolt. Make sure there are no obstacles and door wing is closed properly. Make also sure that the lock switch is working.
This firmware contains the CubeHal and intialization code generated by CubeMX. Both are in "cubemx" folder. The rest is logic code written in C++.
This firmware is designed to work without global variables and so-called "externs" declarations. This is also known as Dependency injection. To implement this, an application class is created, from there finally the whole classes with the logic code and also tasks are created. C-style callbacks from CubeHAL are passed on over the Application class to the relevant class objects as call of its member functions.
With this structure one can clearly understand, which dependencies between the objects exist. This handling is especially important for unit testing.
RTOS tasks are integrated in classes. These classes derive from a base class, which automatically creates a task when constructing the class. With this a class has to override its member taskMain function. After Application class is completely finished with the initializing the tasks will be called.
| classes with RTOS task | description |
|---|---|
| AnalogDigital | convert analog values to digital (input current, motor temperature) |
| HallEncoder | polling raw values and calculate an absolute postion |
| LightController | controls status LED and addressable LEDs |
| MotorController | controls stepper motor and overwatch its operation |
| Settings | load and save settings from/to EEPROM, also notifies classes, which are derived from SettingsUser to get newest parameters |
| StateMachine | the brain of system - knows to every action a reaction |
| TacticleSwitches | polling the input of switches/buttons and update state of each button class instances |