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:

1. voltage - is the 5V voltage
2. current - is the max current for the last 0.5 seconds (supported only by 5A node)
3. 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:

1. voltage - is the Vin voltage
2. current - is the average current for the last 0.5 seconds (supported only by 5A node)
3. 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 called can_pwm_esc_flame (or can_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.

1. enable_5v_check checks 5V node's voltage. If the 5V check is enabled (the parameter value is 1), the node state will be ERROR if the 5V voltage is less than 4.5V or bigger than 5.5V
2. enable_vin_check checks checks node's Vin voltage. Right now it doesn't supported and this check is always disabled.
3. 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:

1. According to the PX4 user guide (opens new window) you need to set UAVCAN_ENABLE parameter to 3 value
2. You need to manually set node id to each nodes you are going to use.
3. 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.