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.

1. Make sure the toolchain is installed
2. Grab the sources from https://github.com/PX4/sapog
3. Prepare the sources:

   git submodule update --init --recursive
   cd firmware

4. Build:

   make RELEASE=1 # RELEASE is optional; omit to build the debug version

5. Flash the board using any available flash loader. For instance (linux only):

   cd tools
   ./blackmagic_flash.sh

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).

The following interfaces are supported:

• UAVCAN
• Command line interface (CLI) over UART
• PWM input

Each option is described below.

Helpful resources:

• UAVCAN specification
• How to enable UAVCAN on Pixhawk

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.

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.

Calls: None

Provides:

• uavcan.protocol.* - all standard services
• uavcan.protocol.param.* - configuration services

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.

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)

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

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.

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.

The most important configuration parameters are documented in this chapter.

Abbreviations:

• DCyc - duty cycle in range [0,1]

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.

In future, the set of devices that run this firmware will be extended with other designs.

Zubax Orel 20 is the first commercially available design based on PX4 Sapog.

The design can be purchased from TitanElite, Inc.

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.