Skip to content

Getting started

Jump to bottom Edit New page
Ben Dyer edited this page Mar 29, 2015 · 20 revisions

Getting started

Updated 2015-03-29

Hardware overview

As at 2015-03-18, all shipped boards are hardware revision 3. The minimum firmware version shipped is aa124d5484.

Depending on the hardware options you selected, you will have received:

  • S2740VC ESC
  • 15 cm 3-pin 0.1" PWM to UAVCAN adapter cable (twisted red, brown and yellow)
  • 15 cm 4-pin Pixhawk DF13 to UAVCAN adapter cable (black wires)
  • ST-Link/v2 USB to JTAG/SWD debugger with 20-pin ribbon connector
  • 20-pin to mini 10-pin JTAG/SWD debug adapter
  • Mini-USB cable
  • Fischl USBtin USB to CAN adapter with UAVCAN cable (twisted red, brown and yellow)

If any hardware is missing or non-functional, please contact [email protected].

Note that the Fischl USBtin adapters we shipped on or prior to the 18th March do not have CAN termination enabled. Depending on your network configuration, this may cause unreliable communications. If you're not able to connect to the ESC(s), try shorting the two large vias closest to the ground (black) wire on the USBtin PCB to enable termination. If this solves the problem, solder a link between those vias.

Software preparation

A VMware virtual machine with all the necessary software pre-installed can be downloaded from here (3.2 GB): http://thiemar.com/downloads/stm32-toolchain.ova

The same virtual machine, packaged for VirtualBox, can be downloaded here (2.9 GB): http://thiemar.com/downloads/stm32-toolchain.zip

If downloading the VirtualBox image, you will need to edit line 12 of the .vbox file to reflect the full path to the .vmdk file.

The username for this machine is dev, and the password is dev.

The software is in a git repository located at /home/dev/workspace/vectorcontrol.

In order to access the firmware, you will need to configure the VM to authenticate using your GitHub account as described here: https://help.github.com/articles/which-remote-url-should-i-use/

By default, the repository on the VM uses SSH authentication, but if you prefer HTTPS, run the following commands:

cd /home/dev/workspace/vectorcontrol
git remote set-url origin https://github.com/thiemar/vectorcontrol.git

After configuring authentication, run:

cd /home/dev/workspace/vectorcontrol
git pull

Alternatively, if not using the VM:

  1. Install Python (version 2.6 or later).
  2. Install the Python pip package (see https://pip.pypa.io/en/latest/installing.html).
  3. Run pip install tornado>=4.0 pyserial.
  4. Clone the software repository at https://github.com/thiemar/vectorcontrol.git (if you do not have access to this repository, contact [email protected]).

Toolchain preparation

The S2740VC uses an STM32F302 MCU, so a variety of toolchains can be used. The firmware contains an Eclipse project which builds using gcc, with debugging via gdb and OpenOCD.

The default Eclipse workspace includes the firmware project so it will load when Eclipse is opened.

If you do not use the virtual machine, complete the steps under "Software preparation" above, then:

  1. Ensure you have git and a functioning ARM toolchain installed.
  2. Install Eclipse Luna for C/C++ developers from https://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/lunasr2
  3. Open Eclipse.
  4. Select and install the "CDT main" options via Help > Install New Software…
  5. Add the "GNU ARM Eclipse" plug-ins via the "Add…" button next to the "Work with:" drop-down in Help > Install New Software…
  6. Select and install all packages in GNU ARM C/C++ Cross Development Tools
  7. Install GCC and related tools from https://launchpad.net/gcc-arm-embedded
  8. Install the GNU build tools from http://sourceforge.net/projects/gnuarmeclipse/files/Build%20Tools/
  9. Go to Window > Preferences > C/C++ > Build > Environment, create a new PATH variable, and add the install directories for the two GNU tools packages above.
  10. In Eclipse, go to File > Import > General > Existing Projects into Workspace, click Next, then click "Browse" next to "Select root directory", select the vectorcontrol directory you checked out while following the "Software preparation" steps, then click "Finish".

Hardware preparation

Bench testing is required before the S2740VC ESC is used in a vehicle. A number of motor and control parameters need to be configured, and depending on the firmware version, motor and application, additional manual tuning may be necessary.

  1. Use a current-limited power supply for testing and motor tuning. In the absence of a current-limited power supply, use a small, low-voltage battery (e.g. 2S / 850 mA h). This may still destroy the ESC and/or motor, but is less likely to pose a fire hazard than a large battery.
  2. Ensure the ESC is placed on a non-conductive surface, and is not near any objects which could be blown onto the ESC by the motor/propeller.
  3. Ensure your motor is securely fastened to a solid object, and is not near any objects which could entangle the rotor or propeller.
  4. Connect the CAN adapter (and debug adapter if required) to the ESC. Pin 1 of the 10-pin SWD connector is identified by a white dot.
  5. Connect the CAN adapter (and debug adapter if required) to your computer. If you're using a non-isolated power supply with a computer connected to mains power, connect the debug adapter via a powered hub to reduce the risk of damage to your computer in the event of a wiring fault.
  6. Connect ESC's three motor phase drive leads to your motor. The order of the leads changes the direction of rotation, but otherwise does not matter. Ensure the phase drive leads are located away from the debug adapter and any EMI-sensitive devices. Also ensure the connectors are physically separated so shorts can't develop between them.
  7. Check the polarity of the ESC's power connector and your power supply. Reversing the supply polarity will immediately destroy the ESC, and may also damage other equipment.
  8. Power the ESC up. You will hear a brief, soft chirp as the ESC identifies your motor, and current draw should stabilize at less than 100 mA depending on the input voltage.

Firmware update

Prior to testing, ensure you are running the latest firmware. This can be downloaded from http://thiemar.com/downloads/vectorcontrol-latest.zip

After downloading the .zip archive:

  1. Extract the enclosed .hex file.
  2. Connector your CAN adapter.
  3. cd into the tools directory in the vectorcontrol repository.
  4. Run python flash.py --node-id 1 --read-config /dev/ttyACM0 (you may need to change /dev/ttyACM0 to point to the CAN adapter's tty device); you should see a series of parameters representing the current configuration of the ESC.
  5. Run python flash.py --node-id 1 --firmware /path/to/vectorcontrol.hex /dev/ttyACM0 (replacing /path/to/vectorcontrol.hex with the path to the .hex file you extracted in step 1).
  6. The firmware update progress will be displayed. Wait for it to complete; after it does, the ESC will restart.

If you are unable to connect to the ESC, ensure it is powered up, and check your CAN wiring. In particular, your CAN bus requires at least one device with termination. The ESC does not have termination; the Pixhawk always has termination enabled on its CAN port, while the supplied USBtin CAN adapter has termination disabled by default but selectable via the termination jumper (see "Hardware overview" for instructions to enable termination if required).

Configuration

Whether you're using the virtual machine or not, you can now start the S2740VC management interface:

  1. Connect your CAN adapter.
  2. cd into the tools directory in the vectorcontrol repository.
  3. Run python ui.py --port 8080 /dev/ttyACM0 (you may need to change /dev/ttyACM0 to point to the CAN adapter's tty device).
  4. Open your web browser and navigate to http://localhost:8080/
  5. Power the ESC up

You should now see a series of configuration options on the left-hand side of the page, and charts on the right.

Critical parameters are:

  1. The first parameter to configure is the UAVCAN node ID. All your ESCs will initially have the same ID, but you will need to set this to a unique value from 1 to 125 before multiple ESCs are able to coexist on the same CAN bus. The default ESC node ID is 1, the same as the Pixhawk. Before running a Pixhawk on the same UAVCAN bus you will need to change the ESC's node ID to another value, e.g. 10.
  2. If you intend to use UAVCAN with multiple ESCs, the ESC index should be set. This is essentially equivalent to the RC channel in traditional PWM setups; PWM channel 1 should be set as ESC index 0, PWM channel 2 should be set as ESC index 1, and so forth. There is no relationship between node ID and ESC index.
  3. Click "Apply configuration" to save changes to flash and restart the ESC.

Once the ESC starts up (there will be a chirp from the motor, and the uptime counter will reset), configure the motor paramters:

  1. Number of poles: Used to convert mechanical speeds to electrical speeds. Your motor's specification sheet will list this; the number will be even and is commonly around 10–14.
  2. Current limit: The motor's rated continuous current, in amperes. When testing a new motor it is often good to set this to the lowest value at which the motor will still start up (1 A is sufficient for small motors with low cogging force, while 10 A may be required for cheap high-Kv motors).
  3. Voltage limit: The motor's rated voltage, in volts. When testing a new motor, set this to 2 V initially in order to limit peak current and speed. Subsequently this can be increased to your motor's rated voltage, or even higher provided the maximum speed and power dissipation specifications of the motor are not exceeded.
  4. Maximum speed: The motor's rated maximum speed, in rpm.
  5. Resistance and inductance: These parameters are measured by the ESC on start-up. If your motor specification sheet lists these figures, check that the measured values are within approx 10%.
  6. Kv: The motor's back-EMF constant, in rpm per volt. If you have an empirical value for this parameter, enter that here; otherwise, enter the value quoted in your motor's specification sheet. Frequently this value is over-stated for marketing reasons; it is not uncommon for a motor's actual back-EMF constant to be 10–15% lower than quoted.
  7. Click "Apply configuration". The ESC will restart again.

After these parameters have been configured, use the "Setpoint" section of the interface to spin your motor up to a moderate speed (for example, equal to the motor's Kv value: 600 rpm if the Kv is 600 rpm / V). If the motor starts smoothly, you can increase the current and voltage limits, click "Apply configuration", and experiment with higher speeds and dynamic setpoints. If the motor starts roughly, the primary tuning parameters are "Acceleration torque limit" and "Acceleration gain". Reduce either or both of these values for more gentle starts and smoother responses to changes in throttle; increase the values if the cogging force of your motor prevents rotation otherwise.

In general, very little tuning should be required: the acceleration gain should remain in the range 0.005 to 0.05, and the acceleration torque limit should generally be around 20% of the motor's maximum current. The "Nominal load torque" value can be set to the current draw at full throttle for somewhat faster response to speed inputs, but the default value of 10 A is sufficient for most supported motors.

For multirotors and possibly certain fixed-wing configurations, it is more appropriate to use the torque controller than the speed controller, as the torque controller provides more direct influence over output thrust and generally faster response. The only parameter used in torque control mode is "Acceleration torque limit"; set this to the largest value at which the motor still starts smoothly. A reasonable starting point for this parameter is 20–50% of the motor's current limit.

Prior to using PWM input, you will need to configure the PWM input parameters. These are:

  1. PWM control mode: Either "speed" or "torque", this parameter determines which motor controller is used when under PWM control. "torque" is most similar to conventional ESCs, and most appropriate for multirotors. "speed" mode will cause the motor to spin at a specific speed, and dynamically vary torque to maintain that speed.
  2. PWM min pulse width: The minimum pulse width in µs at which the motor will spin.
  3. PWM max pulse width: The maximum pulse width in µs. Pulses wider than this will be clipped to this value.
  4. PWM deadband width: The width of the throttle deadband in µs. Any input within this range around zero throttle is considered to be zero. Most useful when motor reverse is used and zero throttle is configured in the middle of the PWM pulse width range.
  5. PWM control offset: Determines the offset of the zero throttle point. If set to 0, zero throttle occurs at a pulse width equal to the "PWM min pulse width" setting. If set to 0.5, zero throttle occurs at half-way between "PWM min pulse width" and "PWM max pulse width". If set to 1.0, the entire PWM range is negative and zero throttle occurs at "PWM max pulse width".
  6. PWM control curve: Determines the relationship between input and output throttle values. "sqrt" results in the output throttle value being proportional to the square root of the input throttle value; "linear" results in the output throttle value being directly proportional to the inptu throttle value; "quadratic" results in the output throttle value being proportional to the square of the input throttle value.
  7. PWM control min: The smallest non-zero throttle setpoint which will be output by a valid PWM signal. If "PWM control mode" is "speed", this value is the minimum speed in rpm; if "PWM control mode" is "torque", this value is the minimum torque expressed as a fraction of current draw multiplied by 8191. That is, 8191 corresponds to a torque controller setpoint of "Current limit" amps.
  8. PWM control max: The largest throttle setpoint which will be output by a valid PWM signal. Units are the same as "PWM control min".

UAVCAN support

The UAVCAN Linux tools are located at /home/dev/uavcan/build/libuavcan_drivers/linux.

Before these tools can be run, SocketCAN must be started. The version of slcand installed on the stm32-toolchain virtual machine image does not appear to work, so instead, open a new console window and run the following commands:

sudo modprobe can && sudo modprobe can-raw && sudo modprobe slcan
sudo slcan_attach -f -o -s8 -c -w /dev/ttyACM0

(Depending on the device your CAN adapter was enumerated as, you may need to replace /dev/ttyACM0 with /dev/ttyACM1 or similar; the adapter may also be enumerated as /dev/ttyUSB<n>.)

This command does not exit; while it is running, the SocketCAN device slcan0 will be available. Once complete, you can terminate slcan_attach by typing ctrl+c.

After running slcan_attach but prior to using slcan0, you must bring the interface up:

sudo ip link set up slcan0

Two tools are relevant:

  • uavcan_status_monitor: run uavcan_status_monitor slcan0 to see live status updates for each node on the UAVCAN network.
  • uavcan_nodetool: run uavcan_nodetool 126 slcan0 to join the UAVCAN network as node ID 126. This tool provides a command-line interface to configure, restart and get information from any node on the network. Type help and press enter for a command listing.

The PX4ESC project includes a program called uavcan_tool which can be used to send ESC throttle commands, and read ESC status packets. To install this, visit https://github.com/PX4/px4esc and follow the instructions in the README file.

PWM support

For compatibility with conventional RC equipment outputting PWM throttle signals, the S2740VC includes a 3-pin 0.1" to UAVCAN adapter cable. The firmware recognises 3.3–5 V pulses ranging in duration from 1000–2000 µs as PWM throttle commands, and translates them to a speed or torque controller setpoint based on your PWM input configuration (see "Configuration" above).

Ensure that no CAN equipment is connected to the S2740VC while PWM input is being used, and power off the S2740VC before connecting a PWM device to ensure the PWM input is recognised.

Prior to flight

Before using the ESC in an aircraft, ensure that you have conducted tests with the motor and propeller you will use, and the ESC functions reliably with that combination.

If speed control is in use, two tests are recommended prior to flight:

  • Control mode: rpm
  • Command type: step
  • From setpoint: your motor's Kv rating in rpm
  • To setpoint: your motor's maximum achievable speed
  • Low time: 1 s
  • Rise time: 0.01 s
  • High time: 1 s
  • Fall time: 1 s

This first test causes the motor to accelerate from a very low speed to full throttle in the shortest time possible. If the ESC loses sync during the step, reduce the acceleration gain, acceleration torque limit, current limit and/or acceleration rise time.

  • Control mode: rpm
  • Command type: sweep
  • From setpoint: your motor's Kv rating in rpm
  • To setpoint: your motor's maximum achievable speed
  • From frequency: 0.25 Hz
  • To frequency: 4 Hz
  • Sweep rise time: 20 s

This test causes the motor to follow a sinusoidal setpoint increasing in frequency from 0.25 Hz to 4 Hz, over its full speed range. If the ESC loses sync during the high-frequency part of the sweep, or motor vibration or prop load is unacceptable, reduce the acceleration gain and/or acceleration rise time until the speed response is sufficiently diminished in magnitude.

Development notes

TODO

Warning: if you're using a debugger, DO NOT CLICK PAUSE/STOP WHILE THE MOTOR IS RUNNING. If you do, the motor will stop instantly and the resulting voltage spike is likely to destroy one of the ESC's MOSFET drivers, resulting in shoot-through on the affected phase and probably quite a bit of smoke.

It may be best to customize your Eclipse toolbar to hide those buttons, as they're super-tempting.

Add a custom footer
Add a custom sidebar
Clone this wiki locally