'Engineers of Innovation Wiki' - User contributions [en]

File:Vesc2 top.png

2026-09-15T17:51:58Z

Aran Dokoupil:

2026-08-17T18:48:58Z

Aran Dokoupil:

2026-08-14T07:29:03Z

Aran Dokoupil:

Foils

2026-08-14T07:28:47Z

Aran Dokoupil:

The foils of the solar boat is a system that is comprised of the following:

* Wing design
* Foil assembly
* [[Autopilot]]

A small overview is given below what any of these signify in the hydrofoils.

== Wing design ==
[[File:Nick-Wings1.jpeg|thumb|The Nick wings made with prepreg CF used for the first real flying trials]]
The wing design is based on the calculation of the airfoil database website: http://airfoiltools.com/plotter/index

From this database an implementation has been made into matlab to tweak some parameters as well as a plot for generating the wing shape.

The matlab scripts are on the [https://git.engineersofinnovation.nl git] and can be found [https://git.engineersofinnovation.nl/matlab-scripts/Hydrofoil_Design here].

The Scripts here make an assumption of a Driver weight of 75 kg and a total boat & driver weight of 180 kg. This gives a mass on rudder of 62.3 kg, mass on each of 2 foils of 58.8 kg.

[[File:cenus_lift_aoa.png|thumb|Lift vs Angle of Attack for the first Cenus wing]]

== Foil assembly ==
The foil assembly connects the wing to the foil mast and then to the hull of the boat.
[[File:Foil assembly.gif|center|thumb|230x230px|Scaled down for showing moving of the foil assembly.]]

== Autopilot ==
The [[autopilot]] is the control electronics that controls the servos of the foil assembly. This a signal PCB with that measures the angle of the solar boat and adjust accordingly towards keeping the hull above the water.

== Height sensors ==
We use ultrasonic height sensors for sensing distance between water and our hull. Currently we use cheap A02 RS485 sensors from DYP.

Datasheets can be found https://www.dypcn.com/uploads/A02-Datasheet.pdf and https://www.dypcn.com/uploads/A02-Output-Interfaces.pdf

Data from this sensor is being processed by our RS485 to CAN interface.

== Servo Specifications ==
The wings have a max positive AoA of 9.5°, and max negative AoA of -7.5°. Note that the neutral lift axis is about -4.3°, so there is not much deflection downward. At the servo this translates to +15° and -12.5° of travel. for servo values +1650uS to -1375uS. Note that the sign is fliped on the other side as the servos are "mirrored". The rough speed of the wing is 0.4s/60°

==== Pinout ====
{| class="wikitable"
|-
! Pin#!!Wire Colour !!Signal on wire
|-
| 1|| style="background: #0065B2;color:white;" | Blue||
|-
|2|| style="background: #241F21;color:white;" | Black||
|-
| 3|| style="background: #FFFFFF;" | White||
|-
|4|| style="background: #83603A;" | Brown||
|-
|5|| style="background: #B2B3B7;" | Gray||
|}
= CAN Messages =
All multi-byte values are little-endian. Any state byte not listed maps to <code>Unknown</code> on the receiver side.
{| class="wikitable"
!Message
!CAN ID
!DLC
!Byte
!Field
!Type
!Values / Range
|-
|ServoRudderSetpoint
|0x010
|2
|0–1
|Setpoint
|u16 LE
|1000–2000
|-
|HeightSensorFrontLeft
|0x011
|3
|0
|State
|u8 enum
|0=NotPluggedIn, 1=ModbusError, 2=Operational, 0xFF=Unknown
|-
|
|
|
|1–2
|Height value
|u16 LE
|distance in mm
|-
|HeightSensorFrontRight
|0x012
|3
|0
|State
|u8 enum
|0=NotPluggedIn, 1=ModbusError, 2=Operational, 0xFF=Unknown
|-
|
|
|
|1–2
|Height value
|u16 LE
|distance in mm
|-
|HeightSensor (placement TBD)
|0x013
|3
|0
|State
|u8 enum
|0=NotPluggedIn, 1=ModbusError, 2=Operational, 0xFF=Unknown
|-
|
|
|
|1–2
|Height value
|u16 LE
|distance in mm
|-
|HeightSensor (placement TBD)
|0x014
|3
|0
|State
|u8 enum
|0=NotPluggedIn, 1=ModbusError, 2=Operational, 0xFF=Unknown
|-
|
|
|
|1–2
|Height value
|u16 LE
|distance in mm
|-
|ServoRudderStatus
|0x020
|3
|0
|State
|u8 enum
|0=Uninitialized, 1=Operational, 0xFF=Unknown
|-
|
|
|
|1–2
|Current setpoint
|u16 LE
|1000–2000
|-
|ServoRudderCommand
|0x021
|1
|0
|Command
|u8 enum
|0=Initialize
|}

2026-06-16T10:37:21Z

Aran Dokoupil: /* CAN Bus Format */

== Platform ==
Ease of development dictated the choice to run the control loop on existing hard- and software, which was chosen to be Ardupilot running on a [https://docs.cubepilot.org/user-guides/autopilot/the-cube-module-overview orange cube].
[[File:Ardupilot.jpg|thumb|Ardupilot PCB with the orange cube mounted.]]
To make use for our application a PCB has been designed to integrate into the hydrofoil design.

To connect to the ardupilot on the cube for tweaking settings and tuning control loops, [https://ardupilot.org/planner/docs/mission-planner-overview.html Mission Planner] is used. The control logic itself runs as a Lua script on the cube (see [[#Lua control script|Lua control script]]). The following sections describe the tweaked settings and the on-board script.

== Hardware ==
The cube is a plug-and-play unit and therefore does not need setup changes in the underlying ardupilot software. Only necessary settings should be tweaked.

Apart from the settings, tuning needs to be done in Mission Planner; this can only be done with the solar boat in the water and therefore no values are known for now.

The ardupilot PCB supports three servo motors, two front and one back motor. It has two isolated power supplies for the servo motors. Support for CAN and the cube is powered by the 24V input from the CAN connection.

It has its own GPS antenna and four UART serial ports, where Serial1 is used for the MAVLINK connection to Mission Planner running on a laptop. The two ultrasonic height sensors connect over the '''CAN bus''' (through an RS485-to-CAN interface PCB), not the cube's UART ports; the Lua control script reads them to keep the boat at its target ride height so it can 'surf' over waves.

For steering on foils an extra MCU is added onto the board, namely the ATSAMD20E18A. This MCU receives the steering position from the rudder and forwards it (it is intended to be put on the CAN bus for the control system to use).

== Height Sensors ==
Currently testing ultrasonic height sensors, the RS485 version of the DYP-A02YY4W-V2.0, with a CAN-interface PCB in between that places the readings on the CAN bus.

Each sensor broadcasts a 3-byte frame at 8 Hz: byte 0 is a status enum (0x02 = Operational, anything else = no valid reading), bytes 1–2 are the measured height in millimetres (uint16, little-endian). The front-left sensor uses CAN ID 0x011 and the front-right 0x012 (see [[#CAN Bus Format|CAN Bus Format]]).

The sensors are mounted as far forward and outboard as possible to stay clear of the bow wake (CAD: 3.8 m forward, 0.23 m left/right, 0.175 m above the IMU). The trade-off is that their reading changes strongly with roll; the Lua script presents each sensor to ArduPilot as a downward scripting rangefinder (so ArduPilot median-filters and logs them) and applies a roll/pitch + lever-arm correction before using the values for control (see [[#Lua control script|Lua control script]]).

== Lua control script ==
The foil control logic runs as a Lua script on the cube (in the project git). It is a '''cascade''' that leans on ArduPilot's tested C++ attitude loop rather than re-implementing control in Lua:

* '''Inner loop — ArduPlane FBWA (mode 5):''' stabilises pitch and roll attitude from the IMU and drives the three foils as control surfaces. The two front foils are configured as elevons and the rear foil as an elevator output.
* '''Outer loop — the Lua script:''' reads the two CAN height sensors, computes a roll/pitch + lever-arm-corrected ride height, and turns the height error into a gentle pitch-target bias on the pitch input channel while holding roll level. Vertical-velocity damping uses the EKF's IMU-fused velocity estimate.

The rear foil is driven over CAN: the script reads ArduPilot's elevator output and sends it as a servo command (ID 0x010).

'''No RC transmitter''' is fitted — throttle and rudder are handled separately. Attitude targets are supplied via RC channel overrides from the script, refreshed every loop. A hardware '''enable pin''' (FMU_CH6) switches between active stabilisation (FBWA) and neutral foils (MANUAL). It is wired active-low and fail-safe: a disconnected or open enable line disables foiling.

On boot the script enforces the parameters it needs (see the [[#Ardupilot settings|settings table]]) and falls to neutral foils on loss of the enable signal, stale sensor data, or a script error. It also publishes attitude, both height estimates, and a status word on the CAN bus for the datalogger (see [[#CAN Bus Format|CAN Bus Format]]).

Two height estimates run simultaneously and are both logged: the Lua roll-corrected value (currently used for control) and ArduPilot's EKF/rangefinder height. The first on-water runs will be flown with the foils disabled to collect this data and decide whether the EKF estimate is reliable enough to drive control.

The script is checked with luacheck and has been validated in ArduPilot SITL (software-in-the-loop) with the CAN bus simulated over UDP multicast.

== Ardupilot settings ==
To use the ardupilot as the foil control unit, some settings need to be changed. '''Most of the settings below are applied automatically at boot by the Lua script's parameter-enforcement routine''' — only <code>SCR_ENABLE</code> and the physical sensor mounting offsets (<code>RNGFNDx_POS_*</code>) must be set/measured manually. There are more ports available on the ardupilot; whenever more are used or changed the table will be updated.
{| class="wikitable sortable"
|+ Configuration of ardupilot
!Setting
!Value
!Description
!Reason
|-
|SCR_ENABLE
|1
|Enable Lua scripting
|Required to run the control script; must be set manually before the script can run.
|-
|INS_GYR_CAL
|0
|Controls the automatic gyro calibration.
|Gyro calibration requires that the unit be held as still as possible.
|-
|INITIAL_MODE
|5
|FBWA
|Fly By Wire A, the attitude-stabilisation mode the inner loop uses. More [https://ardupilot.org/plane/docs/fbwa-mode.html here].
|-
|SERVO1_FUNCTION
|77
|ElevonLeft
|Controls the left front foil assembly (wired to IO-CH1).
|-
|SERVO2_FUNCTION
|78
|ElevonRight
|Controls the right front foil assembly (wired to IO-CH2).
|-
|SERVO3_FUNCTION
|19
|Elevator
|Rear foil pitch command; the script reads this output and forwards it to the rear foil over CAN.
|-
|SERVO14_FUNCTION
|-1
|GPIO
|Frees FMU_CH6 so it can be read as the foil enable input.
|-
|BTN_ENABLE
|1
|Enable button (digital pin) function
|Enables reading the foil enable/disable input.
|-
|BTN_PIN1
|55
|GPIO pin 55 (FMU_CH6)
|Maps the enable input to FMU_CH6; active-low and fail-safe.
|-
|BTN_REPORT_SEND
|2
|Report button state over MAVLink
|Surfaces the enable state to the GCS.
|-
|CAN_P1_DRIVER
|1
|Enable CAN port 1
|CAN carries the height sensors, the rear foil command and telemetry.
|-
|CAN_D1_PROTOCOL
|10
|Scripting
|Lets the Lua script send/receive raw CAN frames on bus 1.
|-
|RNGFND1_TYPE / RNGFND2_TYPE
|36
|Lua scripting rangefinder
|The two height sensors, fed by the script.
|-
|RNGFND1_ORIENT / RNGFND2_ORIENT
|25
|Pitch270 (downward)
|Required for ArduPilot to treat the sensor as a height source.
|-
|RNGFND1/2_MIN_CM / MAX_CM
|40 / 150
|Valid range (cm)
|Range gate for the ultrasonic sensors.
|-
|RNGFND1/2_POS_X / _POS_Y / _POS_Z
|3.8 / ∓0.23 / −0.175
|Sensor mounting offset from the IMU (m; X fwd, Y right, Z down)
|Lets the height correction compensate the roll/pitch lever arm. CAD-measured: 3.8 m forward, 0.23 m left/right, 0.175 m above the IMU. RNGFND1 = left (−Y), RNGFND2 = right (+Y).
|-
|THR_FAILSAFE
|0
|Disable throttle/RC failsafe
|No RC receiver is fitted, so RC failsafe must not trigger.
|-
|ARSPD_USE
|0
|Do not use airspeed
|No airspeed sensor.
|-
|BRD_SAFETY_DEFLT
|0
|Safety switch disabled at boot
|No safety switch fitted; outputs must be live at boot (the enable pin is the safety interlock).
|-
|TERRAIN_ENABLE
|0
|Disable terrain following
|Not applicable; avoids interference with foil height control.
|-
|GPS_TYPE2
|5
|NMEA
|Sets the GPS data sent onto the serial data port.
|-
|SERIAL1_PROTOCOL
|2
|MAVLINK2
|Protocol on the Mission Planner serial port.
|-
|SERIAL1_BAUD
|57
|57600
|Baudrate of the Mission Planner serial port.
|-
|SERIAL4_PROTOCOL
|5
|GPS
|Protocol on the GPS serial port.
|-
|SERIAL4_BAUD
|9
|9600
|Baudrate of the GPS serial port.
|}

== CAN Bus Format ==
All traffic is classic CAN, standard 11-bit IDs, 1 Mbit/s, little-endian unless noted. Inputs are produced by other nodes; outputs are produced by the Lua control script.
{| class="wikitable"
|+ CAN bus messages
!ID
!Direction
!Length
!Contents
|-
|0x011
|in
|3
|Front-left height sensor: [0] state (0x02 = Operational), [1..2] height in mm (uint16 LE)
|-
|0x012
|in
|3
|Front-right height sensor (same layout as 0x011)
|-
|0x010
|out
|2
|Rear foil servo command: PWM as uint16, '''big-endian''' (1500 = neutral)
|-
|0x250
|out
|6
|Telemetry – attitude: [0..1] roll, [2..3] pitch (int16, centidegrees), [4..5] yaw (uint16, centidegrees, 0..36000)
|-
|0x251
|out
|8
|Telemetry – state: [0..1] Lua roll-corrected height, [2..3] EKF height (uint16 mm, 0xFFFF = invalid), [4..5] status bits, [6] vehicle mode, [7] downward-rangefinder status
|}
The 0x251 status bits are: 0 wings enabled, 1 left sensor fresh, 2 right sensor fresh, 3 both fresh, 4 control height valid, 5 control source = EKF, 6 EKF healthy, 7 EKF initialised, 8 home set, 9 EKF origin set, 10 EKF height (HAGL) available, 11 EKF velocity available.

Byte 6 of <code>0x251</code> is the ArduPlane flight-mode number as reported by the autopilot. In normal operation the script only commands two: <code>0</code> = MANUAL (foils disabled / neutral) and <code>5</code> = FBWA (active stabilisation). Any other value means the mode was changed elsewhere (e.g. from the GCS); see the [https://ardupilot.org/plane/docs/flight-modes.html ArduPlane flight-mode list] for the full enumeration.

The steering angle come from the rudder controller and is planned to be used as roll input to the controller.

== Future plans ==
As of March 2026 the Lua control script provides ride-height control as an outer loop on top of FBWA, which already gives automatic altitude holding for the front foils; the rear foil is commanded over CAN. The earlier idea of switching to FBWB for altitude holding is therefore no longer required, though it remains an option for comparison.

Control-loop coefficients are still placeholders — tuning requires the boat in the water. The first runs will be passive (foils disabled) to collect attitude, height-sensor and EKF data over CAN and decide whether ArduPilot's EKF height estimate is reliable enough to use as the control input instead of the Lua-computed value.

Remaining integration work: feed the rudder/steering-angle CAN message into the controller and finalise the no-RC failsafe behaviour.

Some additional reading: https://ardupilot.org/plane/docs/common-sensor-testing.html

== Relevant links for configuring Ardupilot ==
https://ardupilot.org/copter/docs/common-gcs-only-operation.html

https://ardupilot.org/copter/docs/common-rangefinder-landingpage.html

https://ardupilot.org/copter/docs/setting-up-for-tuning.html

https://ardupilot.org/copter/docs/terrain-following-manual-modes.html

https://ardupilot.org/copter/docs/common-sensor-offset-compensation.html

https://ardupilot.org/copter/docs/crash_check.html

https://ardupilot.org/copter/docs/flight-modes.html

https://ardupilot.org/plane/docs/fbwb-mode.html

https://ardupilot.org/plane/docs/fixed-wing-faq.html --Disable Gyro calibration on start-up

https://ardupilot.org/rover/docs/sonar-sensors.html --Two sonar sensors

https://ardupilot.org/dev/docs/plane-architecture.html --Plane architecture and files

Autopilot

2026-06-16T10:27:44Z

Aran Dokoupil: /* CAN Bus Format */

Autopilot

CAN-bus

2026-05-01T05:41:15Z

Aran Dokoupil: /* CAN-bus ID overview */

The communication between the electronics within the [[Solar boat (boii)|solar boat]] is build upon the CAN-bus protocol, where the [[datalogger]] logs the CAN messages. Pinout of our Binder connectors are:

== CAN-bus ID overview ==
<syntaxhighlight lang="markdown">
0x100 EoI Battery start
0x10F EoI Battery end

0x200 EoI GNNS info, u8 fix (bool); u8 sats; u8 sats used
0x201 EoI GNNS f32 speed, kmh; f32 direction, degrees
0x202 EoI GNNS f64 Latitude, degrees
0x203 EoI GNNS f64 Longitude, degrees
0x204 EoI GNNS date time, u16 year, u8 month, u8 day, u8 hour, u8 minute, u8 second

0x400 Gan MPPT R0 : Vin, Iin, Vout, Iout
0x401 Gan MPPT R0 : Mode, Fault, Enabled, TBoard, THS
0x410 Gan MPPT R1
0x411 Gan MPPT R1
...
0x470 Gan MPPT R7
0x471 Gan MPPT R7
0x480 Gan MPPT F0
0x481 Gan MPPT F0
...
0x4F0 Gan MPPT F0
0x4F1 Gan MPPT F0

0x4E6 Gan MPPT Baseboard Front
0x4EE Gan MPPT Baseboard Rear

0x700 MPPT start
0x77F MPPT end

0x0900 THROTTLE To VESC
0x1337 THROTTLE Status

0x0909 VESC Status message 1
0x0E09 VESC Status message 2
0x0F09 VESC Status message 3
0x1009 VESC Status message 4
0x1B09 VESC Status message 5
</syntaxhighlight>

== CAN-bus pinout ==
{| class="wikitable"
|+ Colours of the Standard Binder CAN Cable and its pinout
|-
! Binder Connector pin Number !! Wire Colour !! Signal on wire
|-
| 1 ||style="background: #83603A;"| Brown || 24v Power
|-
| 2 ||style="background: #FFFFFF;"| White || CAN H
|-
| 3 ||style="background: #0065B2;"| Blue || CAN L
|-
| 4 ||style="background: #241F21;color:white;"| Black || Ground
|-
| 5 ||style="background: #B2B3B7;"| Gray || Safety

|}

Note that the M12 connectors have a different pinout and thus different colour wires. To make compatibility between systems easier the binder connectors are soldered with the wrong colored wires so that plugging in a M12 device results in the right signals being passed to the Binder connector. This Compatibility pinout is shown below:

{| class="wikitable"
|+ NON-STANDARD!! Colours when connecting an M12 cable to a binder connector NON-STANDARD!!
|-
! Binder Connector pin Number !! Wire Colour !! Signal on wire
|-
| 1 ||style="background: #FFFFFF;"| White || 24v Power
|-
| 2 ||style="background: #241F21;color:white;"| Black || CAN H
|-
| 3 ||style="background: #B2B3B7;"| Gray || CAN L
|-
| 4 ||style="background: #0065B2;"| Blue || Ground
|-
| 5 ||style="background: #83603A;"| Brown || Safety
|-

|}

== Battery (MG) CAN-format (No longer used) ==
As of now the MG electronics [[battery]] is used in the [[Solar boat (boii)|solar boat]]. Although a new battery is being developed, this MG battery is still in use (as of September '22). Therefore the battery format is given here below.
{| class="wikitable"
|+
!Node-ID
!Index
!Subindex
!Data
!Type
!Resolution
|-
|0x302
|0x2005
|0x01
|Voltage <code>[V]</code>
|uint16_t
|1 <code>[mV/LSB]</code>
|-
|
|
|0x02
|Current <code>[A]</code>
|int16_t
|10 <code>[mA/LSB]</code>
|-
|
|
|0x03
|Current Discharge <code>[A]</code>
|int16_t
|10 <code>[mA/LSB]</code>
|-
|
|
|0x04
|Current Charge <code>[A]</code>
|int16_t
|10 <code>[mA/LSB]</code>
|-
|
|
|0x05
|State-of-Charge <code>[%]</code>
|int8_t
|1 <code>[%/LSB]</code>
|-
|
|
|0x06
|
|
|
|-
|
|
|0x07
|Time to Go <code>[min]</code>
|uint16_t
|1 <code>[min/LSB]</code>
|-
|
|
|
|
|
|
|-
|0x402
|0x2005
|0x09
|Cell Temperature High <code>[°C]</code>
|int8_t
|1 <code>[°C/LSB]</code>
|-
|
|
|0x0A
|
|
|
|-
|
|
|0x0B
|Cell Temperature Low <code>[°C]</code>
|int8_t
|1 <code>[°C/LSB]</code>
|-
|
|
|0x0C
|Cell Voltage High <code>[V]</code>
|uint16_t
|1 <code>[mV/LSB]</code>
|-
|
|
|0x0D
|Cell Voltage Low <code>[V]</code>
|uint16_t
|1 <code>[mV/LSB]</code>
|-
|
|
|0x0E
|BMS State
|uint32_t
|
|-
|
|
|0x0F
|Temperature Collection <code>[°C]</code>
|4x uint8_t
|1 <code>[°C/LSB]</code>
|-
|
|
|
|
|
|
|-
|0x482
|0x2000
|Cell nr
|Cell <code>[Cell_nr]</code> Voltage <code>[V]</code>
|uint16_t
|1 <code>[mV/LSB]</code>
|-
|
|
|
|
|
|
|-
|0x202
|Don't Care
|Don't Care
|Power Level <code>[%]</code>
|uint8_t
|1 <code>[%/LSB]</code>
|}

Throttle

2026-04-06T11:35:24Z

Aran Dokoupil: /* Setting the Control Mode over CAN */

The throttle controls the motor and is operated by the pilot during sailing. It controls the duty cycle of the motor via the [[CAN-bus|CAN bus]] using the standard VESC message format.

== Usage ==
[[File:Throttle Schematic.png|thumb|Throttle shown in the inactive (green led) neutral position]]
To use the throttle to control the motor the green illuminated ''arm-button'' will have to be pressed for a few seconds, however some conditions need to be met to ensure a safe start of the motor.

# The ''dead-man cord'' needs to be applied to the bottom of the throttle body, should snap in place magnetically
# The ''throttle lever'' Should be in its neutral position, pointing straight up with a noticeable tactile bump
# The [[CAN-bus|CAN bus]] need to be actively acknowledging packets, which means other devices need to be active on the bus
# No other error should have occurred inside the electronics

If one of these conditions is not met, the throttle will beep the number of times indicated above.

== Programming Throttle Position ==
The throttle position is read out by a magnet attached tot the ''throttle lever'', because the orientation of this magnet is not know in the firmware, this position can be programmed into the EEPROM. To enter programming mode hold down the arm button during power-on. A four beep descending tone should be played, and the LED should do a double blink in red continuously. To program the throttle push lever as far forward as possible and press the button, a single beep be heard. Repeat this twice with the lever in the center and finally with the lever all the way backwards. After three beeps the throttle is reprogrammed and normal operation is resumed. To summarize:

# Lever in the forward position
# Lever in the center position
# Lever in de backward position
#

If no programming is desired leave the lever alone for 10 seconds and the lever will reboot into normal mode.

== Setting the Control Mode over CAN ==
The Throttle controls the VESC motodriver at 40Hz messaging rate with the default CAN format implemented inside the VESC. [https://dongilc.gitbook.io/openrobot-inc/tutorials/control-with-can More info on the format.] and [https://triforce-docs.readthedocs.io/en/latest/canbus/canbus.html Here]. The throttle supports the following modes:

{| class="wikitable"
|+ Different control modes of the throttle
|-
! Control Mode !! Configuration Byte Value !! Unit !! Additional data required
|-
| Filtered Duty Cycle || 0x01 || Percentage || None lever in the maximum forward position is 100%
|-
|Duty Cycle|| 0x02 || Percentage || None lever in the maximum forward position is 100%
|-
|Current Control || 0x03 || 100mA || Specify the max current for forward and backwards in two int16_t's
|-
|RPM Control || 0x04 || RPM || Specify the rpm for forward and backwards in two int16_t's
|-
|Current Control Relative
|0x05
|Percentage
|None lever in the maximum forward position is 100%
|}

These modes can be send to the throttle when the throttle is off. If the throttle is on the configuration will be ignored. A sound will play when a message is received. The message has to be send to the Throttle address 0x337, same as the reboot command. the format is as follows:

{| class="wikitable"
|+ Can Message for Setting the control mode
|-
! Byte 0 !! Byte 1 !! Byte 2 !! Byte 3 !! Byte 4 !! Byte 5
|-
| 0xAA || Control type || MSB int16_t || LSB int16_t|| MSB int16_t || LSB int16_t
|-
| Hardcoded command|| See Table Above || colspan=2 | Max value for lever completely forward || colspan=2 | Same but for backward (Positive for reverse)

|}

==== Example command: ====
<syntaxhighlight lang="bash" line="1" start="69">
# duty cycle
cansend can0 337#AA0200000000

# 120A current control
cansend can0 337#AA0304B004B0

# relative current control
cansend can0 337#AA0400000000
</syntaxhighlight>

== CAN Diagnostics messages ==
The throttle also send out messages to help debugging every 200 ms. It is send on address 0x337 and has the following format:

{| class="wikitable"
|+ Can Message for Diagnostic Purposes
|-
! Byte 0 !! Byte 1 !! Byte 2 !! Byte 3 !! Byte 4 !! Byte 5 !! Byte 6 !! Byte 7
|-
| MSB int16_t || LSB int16_t || MSB int16_t || LSB int16_t || MSB int16_t || LSB int16_t || uint8_t || Error status
|-
| colspan=2 | Filtered lever position, from +512 to -512 || colspan=2 | Raw position reported by the magnetic encoder || colspan=2 | Raw data from the deadmanswitch ADC || Gain that is required to readout the lever position || Enum of current error state. 0x00 is good
|}

If any of the error status bits are set, the throttle is set into IDLE mode and will shut off the motor. The following table shows what the bitfield represents:

{| class="wikitable"
|+ Different control modes of the throttle
|-
! Bit !! Enum Name !! Explanation
|-
| 0 to 2 || twiError || See next table for possible values
|-
| 3 || noLimitsLoaded || Reading of EEPROM for throttle limits failed
|-
| 4 || gainClipping || The Magnetic encoder detected no good magnetic field present
|-
| 5 || gainInvalid || The gain value read from the magnetic encoder is beyond the range specified in software
|-
| 6 || deadmanMissing || The hall sensor of the deadman-switch doesn't detect a strong enough magnet
|-
| 7 || impeadanceHigh || The impeadance of the deadman signal is too high, indicating a bad connection
|}

{| class="wikitable"
|+ TWI error states
|-
! Value !! Error name !! Error Description
|-
| 0 || TWI_ERROR_NoError || Indicates that the command completed successfully.
|-
| 1 || TWI_ERROR_BusFault || A TWI bus fault occurred while attempting to capture the bus.
|-
| 2 || TWI_ERROR_BusCaptureTimeout || A timeout occurred whilst waiting for the bus to be ready.
|-
| 3 || TWI_ERROR_SlaveResponseTimeout || No ACK received at the nominated slave address within the timeout period.
|-
| 4 || TWI_ERROR_SlaveNotReady || Slave NAKed the TWI bus START condition.
|-
| 5 || TWI_ERROR_SlaveNAK || Slave NAKed whilst attempting to send data to the device.
|}

Throttle

2026-04-05T14:11:08Z

Aran Dokoupil: /* Setting the Control Mode over CAN */

The throttle controls the motor and is operated by the pilot during sailing. It controls the duty cycle of the motor via the [[CAN-bus|CAN bus]] using the standard VESC message format.

== Usage ==
[[File:Throttle Schematic.png|thumb|Throttle shown in the inactive (green led) neutral position]]
To use the throttle to control the motor the green illuminated ''arm-button'' will have to be pressed for a few seconds, however some conditions need to be met to ensure a safe start of the motor.

# The ''dead-man cord'' needs to be applied to the bottom of the throttle body, should snap in place magnetically
# The ''throttle lever'' Should be in its neutral position, pointing straight up with a noticeable tactile bump
# The [[CAN-bus|CAN bus]] need to be actively acknowledging packets, which means other devices need to be active on the bus
# No other error should have occurred inside the electronics

If one of these conditions is not met, the throttle will beep the number of times indicated above.

== Programming Throttle Position ==
The throttle position is read out by a magnet attached tot the ''throttle lever'', because the orientation of this magnet is not know in the firmware, this position can be programmed into the EEPROM. To enter programming mode hold down the arm button during power-on. A four beep descending tone should be played, and the LED should do a double blink in red continuously. To program the throttle push lever as far forward as possible and press the button, a single beep be heard. Repeat this twice with the lever in the center and finally with the lever all the way backwards. After three beeps the throttle is reprogrammed and normal operation is resumed. To summarize:

# Lever in the forward position
# Lever in the center position
# Lever in de backward position
#

If no programming is desired leave the lever alone for 10 seconds and the lever will reboot into normal mode.

== Setting the Control Mode over CAN ==
The Throttle controls the VESC motodriver at 40Hz messaging rate with the default CAN format implemented inside the VESC. [https://dongilc.gitbook.io/openrobot-inc/tutorials/control-with-can More info on the format.] The throttle supports the following modes:

{| class="wikitable"
|+ Different control modes of the throttle
|-
! Control Mode !! Configuration Byte Value !! Unit !! Additional data required
|-
| Filtered Duty Cycle || 0x01 || Percentage || None lever in the maximum forward position is 100%
|-
|Duty Cycle|| 0x02 || Percentage || None lever in the maximum forward position is 100%
|-
|Current Control || 0x03 || 100mA || Specify the max current for forward and backwards in two int16_t's
|-
|RPM Control || 0x04 || RPM || Specify the rpm for forward and backwards in two int16_t's
|-
|Current Control Relative
|0x05
|Percentage
|None lever in the maximum forward position is 100%
|}

These modes can be send to the throttle when the throttle is off. If the throttle is on the configuration will be ignored. A sound will play when a message is received. The message has to be send to the Throttle address 0x337, same as the reboot command. the format is as follows:

{| class="wikitable"
|+ Can Message for Setting the control mode
|-
! Byte 0 !! Byte 1 !! Byte 2 !! Byte 3 !! Byte 4 !! Byte 5
|-
| 0xAA || Control type || MSB int16_t || LSB int16_t|| MSB int16_t || LSB int16_t
|-
| Hardcoded command|| See Table Above || colspan=2 | Max value for lever completely forward || colspan=2 | Same but for backward (Positive for reverse)

|}

==== Example command: ====
<syntaxhighlight lang="bash" line="1" start="69">
# duty cycle
cansend can0 337#AA0200000000

# 120A current control
cansend can0 337#AA0304B004B0

# relative current control
cansend can0 337#AA0400000000
</syntaxhighlight>

== CAN Diagnostics messages ==
The throttle also send out messages to help debugging every 200 ms. It is send on address 0x337 and has the following format:

{| class="wikitable"
|+ Can Message for Diagnostic Purposes
|-
! Byte 0 !! Byte 1 !! Byte 2 !! Byte 3 !! Byte 4 !! Byte 5 !! Byte 6 !! Byte 7
|-
| MSB int16_t || LSB int16_t || MSB int16_t || LSB int16_t || MSB int16_t || LSB int16_t || uint8_t || Error status
|-
| colspan=2 | Filtered lever position, from +512 to -512 || colspan=2 | Raw position reported by the magnetic encoder || colspan=2 | Raw data from the deadmanswitch ADC || Gain that is required to readout the lever position || Enum of current error state. 0x00 is good
|}

If any of the error status bits are set, the throttle is set into IDLE mode and will shut off the motor. The following table shows what the bitfield represents:

{| class="wikitable"
|+ Different control modes of the throttle
|-
! Bit !! Enum Name !! Explanation
|-
| 0 to 2 || twiError || See next table for possible values
|-
| 3 || noLimitsLoaded || Reading of EEPROM for throttle limits failed
|-
| 4 || gainClipping || The Magnetic encoder detected no good magnetic field present
|-
| 5 || gainInvalid || The gain value read from the magnetic encoder is beyond the range specified in software
|-
| 6 || deadmanMissing || The hall sensor of the deadman-switch doesn't detect a strong enough magnet
|-
| 7 || impeadanceHigh || The impeadance of the deadman signal is too high, indicating a bad connection
|}

{| class="wikitable"
|+ TWI error states
|-
! Value !! Error name !! Error Description
|-
| 0 || TWI_ERROR_NoError || Indicates that the command completed successfully.
|-
| 1 || TWI_ERROR_BusFault || A TWI bus fault occurred while attempting to capture the bus.
|-
| 2 || TWI_ERROR_BusCaptureTimeout || A timeout occurred whilst waiting for the bus to be ready.
|-
| 3 || TWI_ERROR_SlaveResponseTimeout || No ACK received at the nominated slave address within the timeout period.
|-
| 4 || TWI_ERROR_SlaveNotReady || Slave NAKed the TWI bus START condition.
|-
| 5 || TWI_ERROR_SlaveNAK || Slave NAKed whilst attempting to send data to the device.
|}