Table of Contents
Sapog
Sapog is an advanced multi-platform three phase brushless motor controller firmware.
The most up-to-date description is currently located at https://docs.zubax.com/sapog.
Please refer to the list of known devices that run this firmware at the bottom of this page.
Building the firmware
- Make sure the toolchain is installed
- Grab the sources from https://github.com/PX4/sapog
- Prepare the sources:
git submodule update --init --recursive cd firmware
- Build:
make RELEASE=1 # RELEASE is optional; omit to build the debug version
- Flash the board using any available flash loader. For instance (linux only):
cd tools ./blackmagic_flash.sh
Powering on
Sapog performs power-on self test, the result of which is indicated as described in the dedicated chapter below. If the board failed to start up, additional info can be retrieved via CLI (see below).
Interfaces
The following interfaces are supported:
- Command line interface (CLI) over UART
- PWM input
Each option is described below.
UAVCAN
Helpful resources:
UAVCAN node name string: org.pixhawk.sapog-v1.
The list of supported messages and services is provided below. No vendor-specific data types are used.
Messages
Input:
- uavcan.equipment.esc.RawCommand - Duty cycle setpoint.
- uavcan.equipment.esc.RPMCommand - RPM setpoint.
- uavcan.equipment.indication.BeepCommand - Beep using the motor windings (ignored while running).
- uavcan.equipment.indication.LightsCommand - Controls the on-board RGB LED.
- uavcan.protocol.EnumerationRequest - Active only in passive mode. See below for details.
- uavcan.protocol.GlobalDiscoveryRequest
Output:
- uavcan.equipment.esc.Status - 10 Hz when the motor is running, 1 Hz when not.
- uavcan.protocol.NodeStatus - 1 Hz, status_code reflects the status of the continuous self diagnostics.
Services
Calls: None
Provides:
- uavcan.protocol.* - all standard services
- uavcan.protocol.param.* - configuration services
Automatic enumeration
Please refer to the DSDL definition of uavcan.protocol.EnumerationRequest for implementation details.
If Node ID is configured as zero, the following happens at startup:
- The local node starts in passive mode, i.e. can't transmit anything to the bus, but still can listen.
- The local node subscribes to uavcan.protocol.EnumerationRequest.
- All other subscribers are not initialized. This means that in passive mode ESC cannot be controlled via UAVCAN.
Enumeration request should be confirmed by turning the rotor in the direction it should be rotating during normal operation. Once enumeration is confirmed, the firmware will save its new Node ID and the motor reverse settings (derived from the direction of rotation during confirmation) into non-volatile memory and restart. If everything went as planned, the node will enter normal operating mode (not passive) after restart and will cease to react to enumeration requests (unless its Node ID is reset to zero again).
Note that pending enumeration request (i.e. when ESC is awaiting confirmation from the user) is indicated via LED - see below for details.
Command line interface
UART parameters:
- Baudrate: 115200
- Word width: 8
- Parity: no
- Stop bits: 1
The board prints diagnostic info at power on, which can be used for troubleshooting.
Basic CLI commands:
- help - get basic usage info
- cfg - change, save or reset the board configuration
- cfg help - crash course on command usage
- dc - set duty cycle
- dc arm - needs to be executed once before the command can be used
- dc X - set duty cycle to (X * 100) percent
- dc - stop
- rpm - set RPM setpoint
- rpm arm - needs to be executed once before the command can be used
- rpm X - set RPM setpoint to X RPM
- rpm - stop
- test - run the self test
- stat - print the basic motor control state (RPM, duty cycle, mode, voltage, current)
PWM input
RC PWM input features:
- Can be disabled completely (refer to configuration parameters)
- No low pass filter is used
- Pulse width range from 1 ms to 2 ms (configurable)
- Safety feature - the motor will not start if the setpoint went straight at a high value
Indication
Sound
After power on:
- Two short high-pitched beeps - self test OK, ready to work.
- One short low-pitched beep every few seconds - self test failed, the motor will not start.
During UAVCAN enumeration:
- Long high-pitched beep - enumeration confirmed, the board is restarting.
LED
State | Meaning |
---|---|
Solid white | Initialization is in progress, not ready to work yet |
Solid green | Everything is OK |
Blinking green | UAVCAN is in passive mode and can be auto-enumerated |
Blinking cyan | UAVCAN auto-enumeration is in progress, awaiting confirmation |
Solid yellow | Unable to start the motor (e.g. rotor is stuck) |
Solid red | Fatal error, or self test failure. Use CLI to obtain detailed info |
Note that if the LED is being controlled externally (e.g. via UAVCAN), the firmware won't indicate its status via LED in order to not interfere with external LED commands.
Configuration
The most important configuration parameters are documented in this chapter.
Abbreviations:
- DCyc - duty cycle in range [0,1]
Name | Default value | Units | Function |
---|---|---|---|
pwm_enable | true | Boolean | Enable RC PWM input |
can_bitrate | 1000000 | Bit/second | CAN bus speed |
uavcan_node_id | 0 (passive) | UAVCAN Node ID, passive mode by default | |
uavcan_esc_index | 0 | Self UAVCAN ESC index | |
uavcan_light_index | 0 | Self UAVCAN light index (for LED control) | |
motor_dc_min_voltage | Volt | Minimum voltage on the motor windings | |
motor_dc_step_max | DCyc | Maximum instant duty cycle change | |
motor_dc_slope | DCyc/sec | Maximum duty cycle change speed | |
motor_num_poles | 14 | Number of motor poles | |
motor_reverse | false | Boolean | Invert the direction of rotation |
motor_rpm_min | RPM | Minimum RPM for closed loop RPM mode | |
motor_current_limit | Ampere | Maximum motor windings current | |
motor_current_limit_p | DCyc/Ampere | Duty cycle reduction at over current | |
motor_pwm_frequency | 30000 | Hertz | PWM frequency |
motor_timing_advance_deg | 15 | Degrees | Commutation advance angle |
Valid range and default values for each parameter can be retrieved using the communication interfaces documented above (CAN, UART). Also note that the table above does not present complete list of all available parameters.
Hardware
In future, the set of devices that run this firmware will be extended with other designs.
Zubax Orel 20
Zubax Orel 20 is the first commercially available design based on PX4 Sapog.
The design can be purchased from TitanElite, Inc.
Pixhawk ESC
Pixhawk ESC is the reference hardware for Sapog. While the ESC can run with other flight controller hardware as well, the reference flight controller is Pixhawk, and hence the hardware designation.
Please refer to the page dedicated to Pixhawk ESC to learn more.