Features
This firmware is primarily a pet hobby project with a focus on insect class combat robotics. There is no calibration mode or configuration mode that uses the throttle inputs, like most other ESCs. In the middle of a competitive match, even after a brownout or voltage spike, the ESC will recover very quickly and never get into a calibration state becaus the throttle was detected as high when the reboot occurred. The human driver does not need to frantically try to listen to the motor beeps to exit the calibration mode or configuration mode, and there's no chance of a setting being reconfigured just because a brownout happened at the exact wrong time.
This is why entering the CLI configuration mode requires the radio receiver to be completely disconnected for a full 10 seconds upon boot. It is not just checking if there's no signal, it is actually checking if the wire is physically disconnected. This is a great way of determining that the user's truly intended to enter CLI configuration mode.
(if your wire got cut in the middle of a robot fight, then you've lost the match anyways)
Please recall what you have already read from the main README about the principle of operation and the caveats.
There are three voltage splitting modes that split the voltage in different ways
Boosted-almost-always mode is probably preferred, it will attempt to maximize power output all the time.
Half-voltage mode will always have a linear response, but always have less power.
Boosted-when-not-turning means both motors get full power when possible, but transitions to half-voltage more smoothly during a turn.
To select a mode, change the vsplitmode option by using the configuration CLI.
Additionally, if you are using CRSF as the input mode, you can assign a channel to change the voltage splitting mode on-the-fly.
This means you can be in the very linear (easy to use) half-voltage mode most of the time, but hit a button and have extra pushing power for your robot.
To do this, simply configure the item channel_mode to the CRSF channel the switch is mapped to. (once channel_mode is configured, the item vsplitmode will be ignored)
The switch channel output value maps to the voltage-split-mode according to this table
| switch value | voltage split mode |
|---|---|
| < 1333 us (-100% to -33% stick) | boosted almost always |
| 1334 to 1666 us (-33% to +33% stick) | half-voltage |
| 1667 us (+33% to +100% stick) > | boosted while not turning |
This feature is similar to other dual ESCs with tank-drive-arcade-mixing. When it is enabled, input channel 1 will be responsible for throttle (moving forward and backwards), and input channel 2 will be responsible for steering (turning left and right). The outputs to motor 1 and motor 2 will be calculated by the mixing algorithm.
When it is disabled, input channel 1 directly controls the speed of motor 1, input channel 2 directly controls the speed of motor 2.
By default, mixing is off. There are several advantages to using the radio transmitter itself perform the mixing, instead of using the ESC to do the mixing. The ESC can only do the most basic mixing algorithm and cannot compensate for weird things like gyroscopic forces or a damaged wheel, but it is possible to handle these things if mixing is done on the radio transmitter.
To enable or disable tank drive arcade mixing, change the tankmix option by using the configuration CLI.
Braking mode should be the default mode and used 99% of the time. It is more responsive, allowing for more precision when used in a robotics application.
If braking mode is off, then the ESC is operating in coasting mode. The momentum of the motors will remain for much longer. For applications when physical resistance is heavy, this might be more ideal if saving power is a priority.
To enable braking mode, set braking option by using the configuration CLI.
Additionally, if you are using CRSF as the input mode, you can assign a channel to change braking mode on-the-fly so that you can activate braking using a switch on your radio transmitter.
To do this, simply configure the item channel_brake to the CRSF channel the switch is mapped to. (once channel_brake is configured, the item braking will be ignored)
If the switch channel output value is over 1500 microseconds (0% stick), then braking is enabled.
Like almost all other ESCs, this ESC firmware features arming and disarming. This means you must have a valid input signal and tell the ESC to "stop" first before the ESC will move. On this firmware, both motors must be simultaneously commanded to stop first in order to arm. If the ESC has LEDs, the LED colour and blink pattern will indicate the armed/disarmed status of the ESC.
And the ESC will become disarmed if the input signal is lost (broken wire, radio lost power, etc).
The arming parameters are configurable, you can edit the options armdur and disarmtime using the configuration CLI.
This feature can also be disabled, but it is not recommended. This is a safety feature meant to prevent a robot from running away unexpectedly.
Please be advised: only some ESCs have current sensors, and current limiting can only be used on ESCs with current sensors.
To avoid burning out the ESC or burning out a motor, you can configure a current limit.
(most brushed ESCs featuring current limiting cannot adjust their current limit through software, they are usually set by a resistor, or even just not configurable at all)
Once the current limit has been reached, the voltage supplied to the motors will be lowered according to an algorithm (PID loop). Usually the motor will settle to a steady-state drawing the maximum allowable current, it is not a sudden stop.
Please read the guide on sensor calibration and then the dedicated page on current limiting. (sensor calibration is only required if the official release firmware does not include calibration for that particular ESC)
Caveat: These ESCs only feature one current sensor because they were only designed to drive one motor. We are driving two motors, so the sensor is sensing the total combined current draw from two motors. When current limiting is being applied, the voltage is dropped for both motors simultaneously. If one motor is using more power than another, the current limit is automatically temporarily lowered automatically.
Please be advised: only some ESCs have voltage sensing, and voltage limiting can only be used on ESCs that can sense voltage.
To avoid over-drawing a battery (which may negatively affect battery health), the user can specify a low-battery detection threshold in a few ways, and the ESC can handle a low-battery situation in a few ways.
Please read the guide on sensor calibration and then the dedicated page on low battery voltage limit. (sensor calibration is only required if the official release firmware does not include calibration for that particular ESC)
If your remotely controlled project requires some fancy LED lighting or otherwise you just wished there was a simple way to remotely control power to something, then you can use direct-PWM mode. This will let a RC transmitter's channel directly control the MOSFETs on the ESC. This provides 3 outputs without any mixing or splitting algorithm. The outputs can also be used in three modes: Push-Pull, Hi-FETs-Only, Open-Drain.
More details about direct-PWM mode is on this page
CRSF is a serial protocol designed for low latency, high precision, high refresh rate control of racing drones. The data packets are protected by a CRC, which is nice as a safety feature. Using a digital serial protocol also increases the accuracy of the data compared to using RC PWM pulses, as there's no noise or jitter to worry about.
Using a serial protocol instead of a traditional RC PWM pulse means one wire can carry 16 channels worth of information. This one wire can also be connected to multiple devices. The radio receivers that feature CRSF are ridiculously small as they are meant for drone racing.
CRSF defaults to using a blistering fast 420000 baud rate. This is actually problematic for older 8-bit microcontrollers. That's why I've made the baud rate configurable. If somebody needs to digitally control the ESC from a 8-bit microcontroller, they can change the option baud using the configuration CLI.
Don't worry, the default values should always be good. And there's no problem that can't be fixed with a factory reset, there's a command for that in the CLI.
You do have the option to change the RC PWM pulse ranges, midpoint, and deadzone. You can also map just one input channel to both motor outputs. You can swap the outputs or invert the outputs.
There is a giant list of options on the configuration CLI's guide
Plus, this project is open source, and written with object-oriented principles in mind.