# 6. DroneCAN PWM node
This page is about DroneCAN software related details such as interface, supported features, parameters, configuration and usage example and versions history. For general information please refer 1. General, for hardware related details including connection example scheme please refer 2. uNode or 4. Mini v2 node.
This section is related to the latest released version of the software.
# 6.1. DroneCAN interface
This node interacts with the following messages:
№ | type | message |
---|---|---|
1 | subscriber | uavcan.equipment.esc.RawCommand (opens new window) |
2 | subscriber | uavcan.equipment.actuator.ArrayCommand (opens new window) |
3 | publisher | uavcan.equipment.esc.Status (opens new window) |
4 | publisher | uavcan.equipment.power.CircuitStatus (opens new window) |
5 | publisher | uavcan.protocol.debug.LogMessage (opens new window) |
6 | publisher | uavcan.equipment.device.Temperature (opens new window) |
Besides required and highly recommended functions such as NodeStatus (opens new window) and GetNodeInfo (opens new window) this node also supports the following application-level functions:
№ | type | message |
---|---|---|
1 | RPC-service | uavcan.protocol.param (opens new window) |
2 | RPC-service | uavcan.protocol.RestartNode (opens new window) |
3 | RPC-service | uavcan.protocol.GetTransportStats (opens new window) |
6.1.1. Circuit status
PWM-node as well as any other our nodes measures and sends 5V
and Vin
voltages as 2 uavcan.equipment.power.CircuitStatus (opens new window) messages
The first message has circuit_id=NODE_ID*10 + 0
and following 3 significant fields:
- voltage - is the 5V voltage
- current - is the max current for the last 0.5 seconds (supported only by
5A
node) - error_flags - might have ERROR_FLAG_OVERVOLTAGE or ERROR_FLAG_UNDERVOLTAGE or non of them
The second message has circuit_id=NODE_ID*10 + 1
and following 3 significant fields:
- voltage - is the Vin voltage
- current - is the average current for the last 0.5 seconds (supported only by
5A
node) - error_flags - ERROR_FLAG_UNDERVOLTAGE or non of them. There is no ERROR_FLAG_OVERVOLTAGE flag because the expected max Vin voltage is unknown.
6.1.2. Device temperature
The node measures and sends device temperature as uavcan.equipment.device.Temperature (opens new window) message.
6.1.3 Log messages
The node may inform you with a text message when something happen. It uses uavcan.protocol.debug.LogMessage (opens new window) message.
A visualization of this message in gui_tool
in case of error shown on a picture below.
This message might be used in PX4 as logmessage (opens new window) feature.
6.1.4 Esc Status
If you use Tmotor esc flame (opens new window) it might be possible to get feedback from it via UART port.
In this case, the PWM node will send uavcan.equipment.esc.Status (opens new window) for each of up to 2 activated channels.
It will fill the following fields of the message:
№ | Field name | Description |
---|---|---|
1 | error_count | This field is used for debug only. The value is incremented after receiving of each byte. If it doesn't change, typically your UART connection is broken. |
2 | voltage | Voltage on the regulator. |
3 | rpm | Rotation per minute. |
4 | esc_index | Index of esc. From 0 to 31. |
Other fields such as current and temperature are not supported.
This feature is supported only by mini v1 and mini v2 nodes:
mini v1
requires to use a special firmware calledcan_pwm_esc_flame
(orcan_pwm_with_feedback
that is the same) to enable this feature,mini v2
uses this feature in all firmware.
# 6.2. DroneCAN Parameters
Below you can see the table with complete set of the node parameters.
The actual list of parameters on your node depends on the firmware version and hardware type.
№ | Parameter name | Reboot required | Description |
---|---|---|---|
0 | uavcan.node.id | true | Node identifier |
1 | flight_time_sec | false | The total flight time in seconds. Appeared since v0.5.2 |
2 | command_type | true | 0 means RawCommand, 1 means ArrayCommand. Appeared since v0.5.2 |
3 | pwm_frequency | true | Pwm frequency from 50 to 400 Hz. Appeared since v0.8.8 |
4 | pwm*_ch | false | Index of setpoint channel. |
5 | pwm*_min | false | PWM duration when setpoint is min. |
6 | pwm*_max | false | PWM duration when setpoint is max. |
7 | pwm*_def | false | PWM duration when setpoint is negative or there is no setpoint at all. |
8 | mot_num_poles | false | Motor number of poles. Appeared since v0.9.8 |
9 | fb_1_enable | false | Enable ESC Flame feedback 1. Appeared since v0.9.8 |
10 | fb_2_enable | false | Enable ESC Flame feedback 2. Appeared since v0.9.8 |
11 | enable_5v_check | false | Set ERROR status if 5V voltage is out of range 4.5 - 5.5 V |
12 | enable_vin_check | false | Set ERROR status if Vin voltage is less than 4.5 V |
13 | cmd_ttl_ms | false | Time to live (opens new window) timeout |
14 | can_bus_check_level | false | Every CAN bus error will be treated as a specified level of error. Appeared since v0.9.8 |
15 | log_level | true | Specify what level of log can be sent. Appeared since v0.5.2 |
16 | name | true | Name of the node |
The detailed description of some of these parameters is shown in the chapters below.
6.2.1. Log level
According to the LogLevel (opens new window) message, we have 4 log levels:
- debug
- info
- warning
- errors
log_level
parameter might have values described in the table below.
Param value | DEBUG | INFO | WARNING | ERROR | Description |
---|---|---|---|---|---|
0 | + | + | + | + | Log everything |
1 | - | + | + | + | At least INFO level |
2 | - | - | + | + | At least WARNING level |
3 | - | - | - | + | At least ERROR level |
4 | - | - | - | - | Disable logging |
0 - log everything, 1 - discard less than info level, 2 - discard less than warn level, 3 -log only errors, 4 - disable logging
6.2.2. Mapping configuration
Mainly parameters are dedicated to PWM mapping configuration. Here we have 2 or 4 groups so called pwm1
, pwm2
, pwm3
, pwm4
of the parameters.
Old versions of the software may have different naming of these groups:
A1
,A2
,B1
,B2
.
Below you can see a table with their description:
Param name | Description |
---|---|
pwm*_ch | Index of setpoint channel (RawCommand or ArrayCommand). Default value -1 means disable. |
pwm*_min | PWM duration when setpoint is min (RawCommand is 0 or Command is 0.0) |
pwm*_max | PWM duration when setpoint is max (RawCommand is 8191 or Command is 1.0) |
pwm*_def | PWM duration when setpoint is negative or there is no setpoint at all |
6.2.3. Node health checks
The node performs self testing and change his health if something goes unexpected. But sometimes warnings and errors might be annoying, so here you have 3 option to disable some of them.
enable_5v_check
checks 5V node's voltage. If the 5V check is enabled (the parameter value is 1), the node state will beERROR
if the 5V voltage is less than 4.5V or bigger than 5.5Venable_vin_check
checks checks node's Vin voltage. Right now it doesn't supported and this check is always disabled.can_bus_check_level
specifies at which level every CAN bus error will be treated. If the parameter value is 0, the node will ignore all CAN bus errors. If the parameter value is 1 or 2, the node will keep WARNING or ERROR state for 6 seconds.
6.2.4. Node name customization
By default this node has Unknown
name. Change name
parameter value to set the desired name.
Choosing the name using the table with preloaded names is legacy now and will not be significantly supported in future. Update you firmware.
# 6.3. Getting started (bench test)
Before mounting on a real vehicle, especially when using the node for the first time, it is recommended to test the node and perform configuration on a bench using gui_tool (opens new window). This utility allows to easily use the full functionality of the node.
The following checklist allows you to test most of the features and configure the most important parameters.
Step 1. Connect the node properly to a sniffer. Initially, when there is no command, the node goes into STANDBY mode and LED should blink with blue color
The simplest connection scheme just for bench testing and configuration is shown below.
Fig. uNode connected to a servo and a sniffer without an input command
Here, the uNode (it might be Mini node as well) is connected with 2 devices:
- a CAN sniffer via CAN (the sniffer is connected to PC via USB and power the node),
- a servo is connected via pwm1 channel.
For other connection schemes, e.g. with ESC and motor, please refer to the hardware page of the corresponding board.
Initially, without any input commands, the node should blink with blue color, which means that the node is in STANDBY state. If the node blinks with Yellow and even Red color it means that the node has a warning or error. You can try to get more info in gui tool. For better understanding of the color, please refer to the LED Meaning page.
Step 2. Open gui_tool and set the local node ID. The node should send data and respond to GetNodeInfo
Apply the Local Node ID by clicking the button in the corresponding field at the top.
Open gui_tool
and check that the node publishes some data like NodeStatus
and GetNodeInfo
. You can quickly press 2 times on the node in Online nodes
list. You should be able to see additional information such as node name, software version, UID, etc.
The node should respond with the software version that suits you (probably it should be the latest available stable version).
If your node doesn't send
GetNodeInfo
it probably means that your gui_tool is still in anonymous mode. Apply local node ID.
Step 3. Configure the node ID and name, Store parameters, then reboot it. ID value and name should be updated.
Select the node ID by changing uavcan.node.id
that fits your CAN-network without ID-collision.
The name is optional thing. It should help you to identify it among other similar nodes. Change it by typeing new name in name
parameter.
Step 4. Check CircuitStatus. The node should measure the input voltages and temperature correctly.
Use Tools > Subscriber to look at topics.
If you power a node from USB, the voltage should be ~5V.
The temperature may be a slightly higher than in your room.
Step 5. Configure command_type
, pwm_frequency
, pwm*
and press the reboot button. The node should correctly control a device (servo or ESC) with either Esc or Actuator Panel.
The ESC panel
and Actuator panel
are shown below.
If the node successfully receives the setpoint, it will go into the ENGAGED state, so its internal RGB LED will be solid blue.
If the parameters are configured correctly, you can control a servo by moving the sliders.
After the configuration, don't forget to
Store All
parameters and reboot the node.
Step 6. Configure the mot_num_poles
, fb_1_enable
and fb_2_enable
parameters if you use ESC. The node should return EscStatus correctly.
You can check this using ESC or Actuator Panel.
Step 7. Configure the cmd_ttl_ms
parameter. When you close the ESC or Actuator Panel, the node will go to STANDBY mode after the specified period of time, where all PWM channels should have the default values.
This is a safety feature. You typically don't want a motor to continue spinning if your autopilot fails or the CAN-wire is broken.
Step 8. Configure log_level
. If it is not the default, the node should report about TTL timeout event in Log messages.
You can play with log_level
to get the notification level you need for your logging system. By default, the node notifies only about real critical events.
Step 9. Check the flight_time_sec
parameter. After the node goes to STANDBY state, it should increment the flight_time_sec
parameter value within a short time .
Typically, you should set this parameter to 0 before mounting the node in a vehicle, but it is up to you.
Step 10. Specify the strictness of onboard checks.
The current list of checks that you are able to modify are: enable_5v_check
, enable_vin_check
, can_bus_check_level
and log_level
.
Some more checks might be appeared in the future.
# 6.4. PX4 integration
You can integrate this node with PX4 by performing the following steps:
- According to the PX4 user guide (opens new window) you need to set
UAVCAN_ENABLE
parameter to3
value - You need to manually set node id to each nodes you are going to use.
- You need to manually configure nodes channels according to your mixer.
An example of configuration for Generic Quadcopter (opens new window) airframe that uses 2 motors for each node is shown below:
Node id | Node name | A1_channel | A2_channel | Description |
---|---|---|---|---|
50 | esc.left (5) | 1 (rear left) | 2 (front left) | Left motors |
51 | esc.right (6) | 0 (front right) | 3 (rear right) | Right motors |
Standard VTOL (opens new window) airframe with corresponded vtol_AAERT (opens new window) aux mixer might have the same configuration as Generic Quadcopter
+ additional configuration for control surfaces:
Node id | Node name | A1_channel | A2_channel | Description |
---|---|---|---|---|
60 | servos.aileron_left (9) | 4 | -1 (unused) | AUX1: Aileron 1 |
61 | servos.aileron_right (10) | 4 | -1 (unused) | AUX2: Aileron 2 |
62 | servos.elevators (11) | 5 | -1 (unused) | AUX3: Elevator |
63 | servos.rudders (12) | 6 | -1 (unused) | AUX4: Rudder |
64 | can_pwm (0) | 7 | -1 (unused) | AUX5: Throttle |
Number of used channels for node depends on configuration of your vehicle. You are free to use more nodes for ESC example based on Generic Quadcopter
or less nodes for servo example based on Generic Quadcopter
airframe.
# 6.5. Software versions
History of all releases and changes related to the node:
Version | Date | Description |
---|---|---|
v0.10.17 3960cc2 (opens new window) | Mar 29, 2023 | Fix bug with cmd_ttl_ms , send ESC feedback only when it is availiable (it is usefull when we loose it), update names of the most of parameters |
v0.9.10 9fe8120 | Dec 10, 2022 | Bug found: cmd_ttl_ms doesn't work. Do not use this version of the firmware. Updates: Add mot_num_poles, Add parameters to disable esc_status, Update internal LED standard for all v2 hardware, Add can_bus_check_level |
v0.8.8-stable f915a39 (opens new window) | Sep 14, 2022 | Add Mini v2 and Micro boards, CAN-bus error status monitor, string name, temperature sensor, custom pwm frequency and improve transport stats |
v0.5.7 f951dc6 (opens new window) | May 06, 2022 | Use individual TTL for each setpoint instead of a single one |
v0.5.2.1 a208527 (opens new window) | Apr 5, 2022 | Extended Mini v1 RC channels amount to 20, Add ArrayCommand, LogMessages, Watchdog, Flight time recorder |
v0.3.2.1 3aaaacf (opens new window) | Mar 28, 2022 | Mini v1 esc-flame with extended RC channels amount to 20 |
v0.3.2 0b55576 (opens new window) | May 31, 2021 | Mini v1 esc-flame feedback first release |
v0.3.0.1 699cbd6 (opens new window) | Mar 28, 2022 | Mini v1 (4 channels) with extended RC channels amount to 20 |
v0.3.0 04866c1 (opens new window) | Apr 05, 2021 | Mini v1 (4 channels) first release |
Note that Mini v1 will not have further software updates. It is recommended to use mini v2 instead.