Sapog

THIS PAGE IS NO LONGER MAINTAINED. Please proceed to Zubax Docs or PX4 Development Guide.

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

  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

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

It is highly recommended to have the motor disconnected during the first power on. In this case the board will be able to detect cross-phase short circuits.

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.

Translations of this page:


Quick Links

QR Code: URL of current page