VideoRay 

M5 Thruster
 M5 Thruster Module 
Operator's Manual, 1.01.00

Copyright Notice
This material is copyright protected. No material may be reproduced or transmitted in any form or by any means for any purpose
without expressed written consent of VideoRay LLC.

Copyright © 2016, VideoRay LLC ­ The Global Leader in Micro­ROV Technology
 M5 Thruster Module 
Operator's Manual, 1.01.00

Table of Contents

Copyright
Table of Contents
About this Document
How to Get Help

Product Overview
Equipment Guide
Physical Mounting
Electrical Connections

Software Guide
Motor Controller Firmware
CSR Memory Map
CSR Field Definitions
Commands and Responses
Diagnostics / Test Mode
Motor Activation Mode
Configuration Mode
Software Management
Bootloader Operation
Firmware Updates
Using vr_refresh
Example Thruster Code

Operations Guide
LED Blink Patterns
 M5 Thruster Module 
Operator's Manual, 1.01.00

About this Document
Online Manual
This Quick Start Guide is a subset of the full version of this manual, which is available on the M5 Thruster Module control panel and
online in the following formats:

Installed on the M5 Thruster Module control panel at: m5_thruster for viewing the HMTL locally.

http://download.videoray.com/m5_thruster for viewing the HMTL online.
http://download.videoray.com/documentation/m5_thruster/pdf/videoray_doc_m5_thruster.pdf for viewing the PDF online.

http://download.videoray.com/documentation/m5_thruster/zip/videoray_doc_m5_thruster.exe for downloading the HTML and
PDF files.

Document Conventions
Several symbols are used throughout this documentation to add emphasis and to assist in relocating important information. The
following table describes these symbols and their uses.

SYMBOL DESCRIPTION
The Danger icon is used to indicate there is a potential risk of personal injury or death. Extra care should be taken to
understand the risks, and all personnel should exercise caution. It may also be appropriate to warn others in the
immediate vicinity.
The Caution icon is used to indicate there is a potential risk of damage to the equipment or surrounding property.
Personnel should receive training in the appropriate procedures before attempting to operate or maintain the
equipment.
The Do Not icon is used to indicate that an action or activity should NOT be performed.

The Note icon is used to highlight a specific detail or point of information.

The Tip icon is used to highlight a suggestion or recommendation.

Beyond this Document
There is no substitute for experience and/or training, especially with respect to the real purpose for which you plan to use this
equipment. We encourage you to explore options beyond the scope of these materials to expand your knowledge and skills
necessary to support your applications. In addition to this documentation, VideoRay offers training and technical support and hosts a
general user discussion forum and user image gallery.

We also realize that collectively, users of our products spend considerably more time operating our systems than we do ourselves.
Users also encounter more diverse operating environments across an extremely broad range of applications. We highly value this
vast experience base, and invite and encourage you to share your experiences and suggestions with us. Please feel free to contact
us by any of the methods listed below.

Quality Commitment
VideoRay strives to design, manufacture, deliver and support the highest quality products and services, including this documentation.
We have made every effort to ensure that this documentation is accurate and provides you with the most up­to­date information.

If you find any errors in this documentation or have suggestions for improvements, each page contains a "Help us improve this
document" feedback link in the left margin (you must be connected to the Internet to use this link).

Address  
VideoRay LLC   
212 East High Street 
Pottstown, PA 19464 
USA 
 
Email  
info@videoray.com General Information and Sales
support@videoray.com  Technical Support
 
Telephone  
+1 610­458­3000 Office

+1 610­458­3010 Fax
 +1 610­458­3010 Fax

Disclaimer
This document is deemed accurate at the time of its writing, however it is not a legal contract and the information contained herein
should not be construed to represent any form of commitment. This document as well as the associated products and services are
subject to change without notice.
 M5 Thruster Module 
Operator's Manual, 1.01.00

How to Get Help
Help for your M5 Thruster Module is available through several channels.

All Hours Self­Service / Crowd­Source Tools
Operator's Manuals and Standard Operating Procedures www.videoray.com/support/manuals.html
Software Downloads www.videoray.com/support/downloads.html
Frequently Asked Questions www.rovfaq.com
ROV User Forum www.rovinfo.com

Global Support
Email support@videoray.com
Phone +1 610­458­3000 (select option 1)
Skype videoray.support (by appointment )
Remote Sessions www.videoray.com/support/remote­support.html (by appointment )

Regional Support
VideoRay Authorized Service Centers and Dealers www.videoray.com/dealer.html

Training
Operator Training www.videoray.com/learn­more/training.html
Advanced Maintenance Training www.videoray.com/learn­more/advanced­maintenance­courses.html

Operational Strategies and Tactics Support
If you need help understanding how to apply your system to a specific project, contact VideoRay or you local VideoRay dealer. We
can provide guidance or help you find a certified consultant.
 M5 Thruster Module 
Operator's Manual, 1.01.00

M5 Thruster Module Overview
VideoRay is pleased to introduce the M5 series thruster motor. This thruster features oil compensation for a 2,000 m (6,560 ft) depth
rating, direct drive brushless motor with the motor controller built into the housing. It delivers a high thrust to input power ratio and is
very efficient at low inputs. It has a low starting RPM, reverses instantly and does not cog. It can be operated with either a left or a
right pitch propeller. Addressable firmware allows multiple thrusters to be connected to the same bus using a stackable plug.
 M5 Thruster Module 
Operator's Manual, 1.01.00

Equipment Guide
The M5 Thruster is a modular unit that includes a brushless motor and motor controller in a single housing with an integrated nozzle
for the propeller. It is easy to mount and includes a stackable M/F 5 pin connector.

   

Physical Mounting
Click on the image to view a pdf in a new window.

Electrical Connections
M5 Thruster connectors are molded neoprene, 10,000 psi rating, 5 contacts with 12 AWG, 600 VDC, 20A per pin.

Connector pin configuration: Male face from the front

Pin Configuration
Pin Conductor AWG Conductor Color Signal Name Comments
1 20 RED 48V+ Teflon cable
2 28 GREEN Signal GND RS­485 signal ground
3 20 BLACK 48V Return Teflon cable
4 28 GRAY RS485+ B Twisted pair
5 28 WHITE RS485­ A Twisted pair

Mating Connector
Connector Vendor: Teledyne Impulse

LPIL­5­MP, Male / Female Connector with whip used on the thruster

LPBH­5­FS, Female Bulkhead Connector used on the platform vehicle
LPBH­5­FS, Female Bulkhead Connector used on the platform vehicle
 M5 Thruster Module 
Operator's Manual, 1.01.00

Software Guide
Software requirements include the low level firmware for the motor controller (provided by VideoRay) and application control
software to adjust the thrust during operation (user supplied).

Motor Controller Firmware
On power up a serial bootloader is executed. After one second, the bootloader will load and initiate the motor controller firmware.

 If "+++++" (5 plus signs) are entered within 5 seconds of power up, the device will enter diagnostic test mode where a simple
ASCII user interface is implemented and a terminal can be used to control and configure the device. See the Diagnostic Mode
section for more information.

 The vr_refresh.exe application can be used to flash new firmware onto the controller. See the Firmware Updates section for more
information.

Communication Timeout
The motor controller has a communication lost timeout of 1 second. If the time since last vr_csr packet is >= 1 second the motor will
set the power to 0. Note that this does not occur in diagnostic mode. Also note that the motor is NOT de­energized but remains active
with the motor power set to 0.

Fault Handling
If a fault occurs, the thruster will de­energize and the fault must be cleared and the thruster re­initialized before it will actuate the
motor.

CSR Memory Map
In normal operation the device implements a CSR type memory mapped data space. The VideoRay CSR comms protocol is used for
communication. See https://github.com/videoray/VRCommsProtocol_doc/raw/master/VR_CSR_Communication_Protocol.doc for
more information on the base binary protocol.

Register Function Comments

0x0 float rpm_target rpm (RW) NOT USED YET
0x4 float pwr_target ­1 to 1 (RW)
0x8 float rpm rpm (R)
0xc float bus_v volts (R)
0x10 float bus_i amps (R)
0x14 uint32_t fault fault flags (R)
0x18 float temp deg C (R)
0x1c float pwr_actual ­1 to 1 (R)
0x20 float rpm_P 0 to 1 (R) NOT USED YET
0x24 float rpm_I 0 to 1 (R) NOT USED YET
0x28 float rpm_D 0 to 1 (R) NOT USED YET
0x2c RESERVED
0x4c uint16_t thruster_ID ordinal (RW)
0x4e RESERVED
0x50 uint8_t operation_flags
0x51 RESERVED
0x54 uint32_t motor_fault_interlock password (RW)
0x58 RESERVED
0x60 uint8_t motor_control_flags Bitfield (RW)
0x61 uint8_t poles count (RW)
0x62 uint8_t pwm_deadband ticks (RW)
0x63 RESERVED
0x63 RESERVED
0x64 float commutation_threshold 0 to 1 (RW)
0x68 uint32_t commutation_loss_timeout ms (RW)
0x6c float startup_dutycycle 0 to 1 (RW)
0x70 uint16_t startup_initial_rpm rpm (RW)
0x72 uint16_t startup_final_rpm rpm (RW)
0x74 float startup_duration mS (RW)
0x78 float deadband_neg ­1 to 0 (RW)
0x7c float deadband_pos 0 to 1 (RW)
0x80 float limit_neg ­1 to 0 (RW)
0x84 float limit_pos 0 to 1 (RW)
0x88 float slew_rate_up delta/mS (RW)
0x8c float slew_rate_down delta/mS (RW)
0x90 float rpm_kP ­1 to 1 (RW) NOT USED YET
0x94 float rpm_kI ­1 to 1 (RW) NOT USED YET
0x98 float rpm_kD ­1 to 1 (RW) NOT USED YET
0x9c RESERVED
0xa4 uint8_t fault_control flag (RW)
0xa5 uint8_t undervoltage_trigger volts (RW)
0xa6 uint8_t overvoltage_trigger volts (RW)
0xa7 uint8_t overcurrent_trigger amps (RW)
0xa8 uint8_t temp_trigger deg C (RW)
0xa9 uint8_t stall_count_max count (RW)
0xaa RESERVED
0xac uint32_t undervoltage_err_cnt count (R)
0xb0 uint32_t overvoltage_err_cnt count (R)
0xb4 uint32_t overcurrent_err_cnt count (R)
0xb8 uint32_t temp_err_cnt count (R)
0xbc uint32_t stall_err_cnt count (R)
0xc0 RESERVED
0xd8 uint32_t comms_sync1_err_cnt count (R)
0xdc uint32_t comms_sync2_err_cnt count (R)
0xe0 uint32_t comms_headerxsum_err_cnt count (R)
0xe4 uint32_t comms_overrun_err_cnt count (R)
0xe8 uint32_t comms_payloadxsum_err_cnt count (R)
0xec uint16_t comms_err_flag
0xee uint16_t save_settings code (W)
0xf0 uint32_t custom_command (W) Special Register
0xf4 uint32_t FACTORY_SERVICE_DATA (R) Device specific service data
0xf8 uint16_t CONFIG_DATA_SIZE (R)
0xfa uint8_t CONFIG_DATA (R) Special Register
0xfb uint8_t FIRMWARE_VERSION (R) Special Register
0xfc uint8_t NODE_ID (RW) Special Register
0xfd uint8_t GROUP_ID (RW) Special Register
0xfe uint16_t UTILITY (W) Special Register

CSR Field Definitions
To be added.

Commands and Responses
The motor controller firmware also supports custom commands that allow for the instantaneous setting of multiple controllers on a
party line comms bus.

PROPULSION_COMMAND: 0xaa
The propulsion command is an application custom command which is sent as a write request to CSR address 0xF0 (the custom
The propulsion command is an application custom command which is sent as a write request to CSR address 0xF0 (the custom
command register. It has the following data payload format:

0xAA R_ID THRUST_0 THRUST_1 THRUST_2 ... THRUST_N

Where:

0xAA is the command byte
R_ID is the NODE ID of the thruster to respond with data
THRUST_X is the thruster power value (­1 to 1) for the thruster with motor id X

Typically this is sent as a group multicast to address 0x81 which is reserved for thrusters.

RESPONSE_THRUSTER_STANDARD: 0x02
The standard thruster response is typically used in conjunction with the multicast PROPULSION COMMAND to retrieve data from
each thruster in the system in a round robin fashion.

When the FLAG byte is set to 0x02 the RESPONSE_THRUSTER_STANDARD data payload is sent.

The format of this payload is defined by the following structure:

Response_Thruster_Standard {
    /** Measured shaft rotational velocity */
    float rpm;
    /** Bus voltage (Volts) */ 
    float bus_v;
    /** Bus current (Amps) */
    float bus_i;
    /** Temperature (Degree C) */ 
    float temp;
    /** fault flags */
    uint8_t fault;
}

Please see the example thruster.py for an illustration of how to use the PROPULSION_COMMAND and parse the
RESPONSE_THRUSTERS_STANDARD response packet.

Diagnostic / Test Mode
Diagnostic mode is a simple ASCII terminal user interface that allows interaction with the motor controller electronics without
requiring any additional topside software other than a serial terminal (such as Tera Term). The baud rate should be set to 115,200.

Test cables are available from VideoRay and use an FTDI RS­485 to USB serial adapter. The driver for the adapter is a available
from FTDI's website at: http://www.ftdichip.com/Drivers/D2XX.htm.

 To enter Diagnostic mode, input "+++++" (5 pluses) within 5 seconds after power up. If 5 seconds have elapsed, or any vrcsr
packets have been received, diagnostic mode will be locked out until the next power cycle.

Diagnostic mode includes Motor Activation Mode and Configuration Mode. These modes are described on the following pages.

 Since diagnostic mode is a simple ASCII terminal it is not appropriate for multiparty communications.

Motor Activation Mode
When the motor controller enters diagnostic mode it will go directly to motor actuation mode. In motor actuation mode the motor can
be directly controlled by key presses in the terminal window.

The diagnostic menu illustrates the keys which can be used actuate the motor.

Diagnostics:
=: Increase motor (0.1%) increments
­: Decrease motor (0.1%) increments
0­9: Set motor direct (10% increments)
Shift + 0­9: Set motor direct reverse (10% increments)
r: Reset motor control algorithm state
' ': Print data (space)
c: Configuration
d: Dump runtime log
?: Print this menu
x: Exit diagnostic mode

Notes:

Pressing "x" will exit diagnostic mode. After exiting, diagnostic mode can be re­entered within 5 seconds by pressing "+++++"
 Pressing "x" will exit diagnostic mode. After exiting, diagnostic mode can be re­entered within 5 seconds by pressing "+++++"
(5 plus signs).
Pressing "c" will bring up the configuration menu.
Actuation is immediate on each keypress, i.e. the "Enter" key does not have to be pressed after the desired command input.

Configuration Mode
The diagnostic configuration menu allows for various operating parameters to be set. The parameters can also be saved in non­
volatile storage.

The diagnostic configuration menu displays the motor controller serial number as well as the firmware versions number and firmware
inception date.

In diagnostic configuration mode the "Enter" key must be hit after each command input.
Primary Configuration Commands:

Pressing "x" followed by "Enter" will exit diagnostic configuration mode and return to the diagnostic menu.
Pressing "s" followed by "Enter" will save the current parameters in non­volatile memory.
Pressing "f" followed by "Enter" will reset the all parameters to their hardcoded factory defaults.

Entering a number followed by "Enter" will prompt for a new setting for the configuration parameter. If "Enter" is pressed before a new
value has been entered the current value will remain.

Motor Controller: THR0006
SW Version: 0.8.3 Dec 1, 2014 09:38:00

Default
Command Function Description
Value
1 Motor control 0x0 The motor control flags are a bitfield that sets binary operation parameters.
flags
Currently defined:

CONTROL_FLAG_REVERSE_ROTATION (1 << 0)
When set, reverses the rotation of the motor.

2 Motor poles 14 Defines the number of poles in the attached motor.
3 PWM 32 Defines the time that band that insures that the motor driving FETs are off. This prevents
deadband both the high and low driving complementary FETs to be on at the same time. Units are in
processor cycles.
4 Commutation 0.100000 This defines the trigger level at which the commutation algorithm determines it is time to
threshold commutate the motor.
5 Commutation 100 If the time between detected commutations is greater than this value, in mS, then the
loss timeout algorithm will assume the motor is stalled and reset the commutation algorithm and switch
to open loop startup mode.
6 Startup duty 0.040000 The duty cycle that will be used to power the motor when in initial open­loop startup mode.
cycle
7 Startup initial 80 The initial startup RPM that will be used when the motor is in initial open­loop startup
RPM mode. The algorithm will attempt to commutate at this RPM using the Startup Duty Cycle
PWM. The open loop phase will ramp up from this RPM to the startup end RPM at a rate
defined by the Ramp Startup time.
8 Startup final 100 he ending startup RPM that will be used when the motor is in initial open­loop startup
RPM mode. The algorithm will attempt to commutate at this RPM using the Startup Duty Cycle
PWM. The open loop phase will ramp up to this RPM from the startup initial RPM at a rate
defined by the Ramp Startup time.
9 Startup 50.000000 This parameter defines the duration required to ramp from startup initial RPM to startup end
duration RPM. This value is in units of ????
10 Negative ­0.020000 This defines the largest (closest to 0) negative value that can be set as a motor thruster
deadband setpoint. It is assumed that due to stiction the motor will not spin at power levels closer to 0
than this.
11 Positive 0.020000 This defines the smallest positive (closest to 0) value that can be set as a motor thruster
deadband setpoint. It is assumed that due to stiction the motor will not spin at power levels closer to 0
than this.
12 Negative ­0.990000 This value is the limit in the negative direction of applicable power to the motor. The
duty cycle command setpoint will never be less than this value.
limit
13 Positive duty 0.990000 This value is the limit in the positive direction of applicable power to the motor. The
cycle limit command setpoint will never be greater than this value.
14 Acceleration 0.000050 This value defines the rate at which the motor will change from the current power setpoint
rate to the target setpoint. This value defines the rate when the absolute value of the target
setpoint is larger than the current setpoint. The units of this value are change in normalized
power per mS.
15 Deceleration 0.000050 This value defines the rate at which the motor will change from the current power setpoint
rate to the target setpoint. This value defines the rate when absolute value of the target setpoint
is less than the current setpoint. The units of this value are change in normalized power per
mS.
16 Power 200.000000 This actively limits the power that the thruster will use. The default is 200W.
manager
threshold
17 Fault control 0x0 This is a bit­field mask is used to enable or disable the de­energizeing of the motor on the
detection of a fault. Faults will still be detected, but if the bit field is cleared the controller will
not de­energize on that specific fault condition.

Current fault conditions are defined as:

FAULT_UNDERVOLT (1<<0)
FAULT_OVERRVOLT (1<<1)
FAULT_OVERCURRENT(1<<2)
FAULT_OVERTEMP(1<<3)
FAULT_STALL(1<<4)
FAULT_STALL_WARN (1<<5)

18 Minimum 19.200001 Sets the undervoltage fault trip point in Volts.

voltage
19 Max bus 50.000000 Sets the over voltage fault trip point in Volts.
voltage
20 Max current 20.000000 Sets the overcurrent fault trip point in Amps.
21 Max 100.000000 Sets the overtemp fault trip point in degrees Celsius.
temperature
22 Max stall 100 Sets the threshold for the number of stall event detections at which to declare a fault.
count
23 Node Id 2 This is the communication protocol network node id. This is used to designate this device
on a multiparty RS­485 communication network. A module will accept a packet which is
addressed to its node ID, Group ID, or uses the broadcast ID.
24 Group Id 129 This is the communication protocol network group id. This is used to designate a group of
device on a multiparty RS­485 communication network. A module will accept a packet
which is addressed to its node ID, Group ID, or uses the broadcast ID.
25 Motor Id 0 This is the motor controller ID. This associates a motor with a specific datum in the motor
controller propulsion command. Modules with the same motor ID will all use the same set
point when sent an acceptable propulsion command.
26 System 1 The motor control flags are a bitfield that sets binary operation parameters.
control flags
Currently defined:

ENABLE_LOSS_OF_COMMS_TIMOUT (1 << 0)
DISABLE_STARTUP_TONES (1<<1)

When set the controller will set the power setpoint to 0 if communications have been lossed
for 1 second.Clearing this flag allows for a greatly reduced communications bandwidth.
However the motor will continue to spin even if communications have been lost.

27 Fault 0 This value must be set to the proper password to allow the faults control mask to be
interlock changed. The password is 0xdeadbeef
f Reset n/a Reset parameters to factory default.
s Save n/a Save parameters.
x Exit n/a Exit configuration mode.

Software Management
This section addresses the low level firmware installed on the controller. Application control software is the responsibility of the user.

Bootloader Operation
The bootloader runs on the module upon power up. The module will remain in the bootloader for 1 second waiting for a command to
remain in the bootloader. If no command is received and the module has a valid application firmware loaded then the module will run
the application firmware. If the "remain in bootloader" command is received or if there is no valid application firmware the module will
remain in the bootloader.
 The module must have the bootloader running. The primary mechanism of installing the bootloader on the module is via JTAG
(Joint Test Action Group). If you require provisioning a module with a bootloader, please see the appropriate documentation.

Bootloader LED Blink Patterns
The bootloader blinks the module status LED to indicate its operational state.

Start­up Blink (3 blinks): The bootloader will blink 3 blinks (100ms ON, 200 ms OFF) on startup.

Active Blink (fast 5 times a second continuous): The status led will rapidly blink (5 times a second) while running in the
bootloader. The blink will remain continuously active until the module leaves the bootloader.

Command reception blink (fast 5 times a second continuous): The status led will rapidly blink (5 times a second) while
running in the bootloader. The blink will remain active while the module is in the bootloader.

Typical blink startup pattern will be:

3 blinks, followed by 1 second of rapid blinks, followed by the application firmware blink pattern. If there is no valid application, the
pattern will be 3 blinks, followed by continuous rapid blinks.

Verification of Bootloader Operation via a Terminal
The bootloader emits an identifying message on startup. Part of the message is ASCII and thus human readable. This provides a
method to insure that the bootloader is loaded on the module.

Connect a terminal emulator (such as tera term or putty) to the serial port connected to the module. The terminal should be set to
115200, 8n1.

Upon power up of the module the terminal will display the received characters. The display will look similar to the image below. If the
text "BOOT" is visible then it is most likely that the bootloader is on the module.

ASCII terminal display showing bootloader message as well as text banner from a module application firmware (LED Controller).
"BOOT" is highlighted in yellow, and the firmware message is highlighted in green.
Updating Firmware on M5 Modules
Quick Steps for manual updating a single module:

1. Download vr_refresh if needed from ftp.videoray.com
2. Download new firmware for the module from ftp.videoray.com
3. Connect the serial power to the module. Do NOT power on the module yet.
4. Run vr_refresh with a command line similar to "vr_refresh ­c COM7 firmware­1.0.0.hex"
5. Apply power to the module.
6. It should start the download process. If not, or if any errors during download, repeat steps 3­5.

Downloading Firmware and Tools
All M5 software is distributed via the VideoRay FTP server (http://ftp.videoray.com/) using the following credentials:

Username: quarterdeck
Password: quarterdeck

 Note the use of http://, not ftp:// in the server URL above.

The firmware is located in the ./firmware folder.

Tools (such as vr_refresh) are located in the ./windows_tools folder or ./ubuntu_tools folder depending upon what OS you are using.

At a minimum the firmware for the module and the appropriate vr_referesh application are required to update the firmware on a
module

 Instructions for using vr_refresh are included in the next section.

Using vr_refresh
The vr_refresh tool is a standalone command line application that can be used to update the firmware on a module. There are no
dependencies for vr_refresh.

Usage: vr_refresh [OPTIONS] [SINGLE_HEX_FILE_NAME]

 Do not include the brackets [   ].

OPTION Description
­? [ ­­help ] show the help message
­­version show version
­c [ ­­com ] arg set com port name (=/dev/ttyUSB0)
­i [ ­­id ] arg node ID, 255 for broadcast (=255)
­­sn arg serial number (=any)
­­block_size arg flash block size (=1024)
­d [ ­­dir ] arg set firmware folder, not used if an input file is specified
­q [ ­­quite ] do not send check active command
­v [ ­­verbose ] output verbose diagnostics
­r [ ­­RESET ] reset device upon completion
­­UNLOCK allow reprogramming of bootloader
­­input_file arg input file

For example, to download the firmware to a LED controller module, the typical usage on a Windows machine would be:

vr_refresh ­c com7 led_controller­1.0.0.hex

The typically usage on a Linux host would be:

vr_refresh ­c /dev/ttyUSB0 led_controller­1.0.0.hex

By default vr_refresh will use BROADCAST transmissions to establish connections. This behavior can be changed by using the ­i or
the ­sn parameters.

vr_refresh, like all VideoRay command line tools will output its usage options when run with the "­?" parameter.

vr_refresh Methods of Connection
There are two ways to establish a connection between vr_refresh and the module.
Power on Connection

When vr_refresh is run it will sit and wait for the initial announcement message sent by the module. The modules use a randomized
transmission to attempt to minimize collisions when there are multiple devices on the bus. Since vr_refresh by default uses
broadcasts, this means that if there are multiple devices connected and powered up at the same time it is a matter of chance as to
which module will connect. It is therefore recommend that either the ­sn or ­i parameters be used or only as single module be
connected at a time when updating firmware.

Application Firmware Reboot Connection

When vr_refresh is run it will send a REBOOT message immediately (­i parameter applies). If a module is connected, powered up,
and accepts the REBOOT message from vr_refresh (either it is a broadcast message or the proper node id was passed in) the
module will reboot and jump to the bootloader. It should then connect as desired.

vr_refresh Output
vr_refresh will output status strings during operation. Examples are given below:

Waiting to connect (command line: vr_refresh ­c com7 ­I 1); response:

INFO: Attempting connection to Node: 1 S/N: any

Successful connection (command line: vr_refresh ­c com7); response:

INFO: Attempting connection to Node: 255 S/N: any
INFO: Connected to Node: 5
INFO: Done

Successful connection VERBOSE mode (command line: vr_refresh ­c com7 ­­verbose); response:

INFO: Attempting connection to Node: 255 S/N: any
INFO: Connected to Node: 5
INFO: Boot Data
Data version: 1
Device type: 131
Incept date: 2014­Nov­10 22:29:55
Serial number: LED0001
App Size: 0x9118
App crc: 0x23f766a8
INFO: Done

Sample end of firmware update (command line: vr_refresh ­c com7 ­verbose led_controller­1.0.0.hex); response:

INFO: Progress 90%
INFO: Erase 0xc400
INFO: Progress 91%
INFO: Progress 92%
INFO: Progress 93%
INFO: Erase 0xc800
INFO: Progress 94%
INFO: Progress 95%
INFO: Progress 96%
INFO: Erase 0xcc00
INFO: Progress 97%
INFO: Progress 98%
INFO: Erase 0xd000
INFO: Progress 99%
INFO: Progress 100%
INFO: Done

Example Thruster Control Code (Python)
The following code can be used to control the thruster and display the response information.

All M5 software, including this sample code, is distributed via the VideoRay FTP server (http://ftp.videoray.com/) using the following
credentials:

Username: quarterdeck
Password: quarterdeck

import serial
import struct
import sys
import operator
import argparse
import binascii

import time
import time

#VRCSR protocol defines  
SYNC_REQUEST  =  0x5FF5
SYNC_RESPONSE =  0x0FF0
PROTOCOL_VRCSR_HEADER_SIZE = 6
PROTOCOL_VRCSR_XSUM_SIZE   = 4

#CSR Address for sending an application specific custom command
ADDR_CUSTOM_COMMAND  = 0xF0

#The command to send.
#The Propulsion command has a payload format of:
# 0xAA R_ID THRUST_0 THRUST_1 THRUST_2 ... THRUST_N 
# Where:
#   0xAA is the command byte
#   R_ID is the NODE ID of the thruster to respond with data
#   THRUST_X is the thruster power value (­1 to 1) for the thruster with motor id X
PROPULSION_COMMAND   = 0xAA

#flag for the standard thruster response which contains 
RESPONSE_THRUSTER_STANDARD = 0x2
#standard response is the device type followed by 4 32­bit floats and 1 byte
RESPONSE_THRUSTER_STANDARD_LENGTH = 1 + 4 * 4 + 1 

#The proppulsion command packets are typically sent as a multicast to a group ID
#defined for thrusters
THRUSTER_GROUP_ID    = 0x81

def main(): 

    #Parse command line arguments for portname, node id, motor id, and thrust values
    parser = argparse.ArgumentParser()
    parser.add_argument('­c', '­­com', help='Comm port to use.', default = 'COM2',
                        dest='portname')
    parser.add_argument('­i', '­­id', help="Node id for the request packet.
                        The default is the thruster group ID.", default = THRUSTER_GROUP_ID,
                        dest='node_id')
    parser.add_argument('­m', '­­motor', help="Motor NODE ID from which to get a response.",
                        default = 0, dest='motor_id')
    parser.add_argument('thrust', metavar='N', type=float, nargs='*', help='list of thrust
                        settings, in order of motor id.  These are power settings and
                        should be in the ­1 to 1 range.' )
    args = parser.parse_args()

    #default to 0 thrust for motor 0 if no thrust parameters are passed in
    if (len(args.thrust) == 0):
        thrust  = [0.0]
    else:
        thrust = args.thrust

    #open the serial port
    try:        
        port = serial.Serial(args.portname,115200)
        port.timeout = 1
        port.flushInput();
    except IOError:
        print ("Error:  Could not open serial port: " + args.portname)     
        sys.exit()

    #Create the custom command packet for setting the power level to a group of thrusters
    #generate the header
    flag = RESPONSE_THRUSTER_STANDARD
    CSR_address = ADDR_CUSTOM_COMMAND
    length = 2 + len(thrust) * 4
    header = bytearray(struct.pack('HBBBB',SYNC_REQUEST,int(args.node_id),
                       flag,CSR_address,length))
    header_checksum = bytearray(struct.pack('i', binascii.crc32(header))) 

    #generate the paylaod, limiting the thrust to reasonable values
    payload = bytearray(struct.pack('BB', PROPULSION_COMMAND, int(args.motor_id)))
    for t in thrust:
        t = max(t,­1)
        t = min(t, 1)
        payload += bytearray(struct.pack('f',t))
    payload_checksum = bytearray(struct.pack('i', binascii.crc32(payload)))    

    #send the packet and wait for a response
    packet = header + header_checksum + payload + payload_checksum 
    #uncomment to dump the request payload
    #print (":".join("{:02x}".format(c) for c in packet))
    #print (":".join("{:02x}".format(c) for c in packet))

    write_time = time.time()

    #put the packet on the wire
    port.write(bytes(packet))

    #get the response

    expected_response_length = PROTOCOL_VRCSR_HEADER_SIZE + PROTOCOL_VRCSR_XSUM_SIZE +
                               RESPONSE_THRUSTER_STANDARD_LENGTH +  PROTOCOL_VRCSR_XSUM_SIZE
    response_buf = port.read(expected_response_length)

    print ("Got response: %d bytes" % len(response_buf))
    print ("Turnaround time: %f mS" % ((time.time()­write_time) * 1000))

    #parse the response
    response = struct.unpack('=HBBBB I BffffB I', response_buf)

    #uncomment to dump the response buffer
    #print (":".join("{:02x}".format(ord(c)) for c in response_buf))
        
    #header data
    sync =              response[0]
    response_node_id =  response[1]
    flag =              response[2]
    CSR_address =       response[3]
    length =            response[4]
    header_checksum =   response[5]

    #response device type
    device_type      =   response[6];

    #custom response data payload
    rpm = response[7]
    bus_v = response[8]
    bus_i = response[9]
    temp = response[10]
    fault = response[11]

    payload_checksum = response[12]

    print ("\nResponse:")
    print ("\tSync:\t\t0x%04x" % sync)
    print ("\tId:\t\t%d" % response_node_id)
    print ("\tFlag:\t\t0x%x" % flag)
    print ("\tAddress:\t0x%x" % CSR_address)
    print ("\tLength:\t\t0x%x" % length)
    print ("\t\tChecksum: 0x%x" % header_checksum)

    print ("\n\tDevice Type:\t\t0x%x" % device_type)
    print ("\tRPM:\t\t\t%f" % rpm)
    print ("\tBus Voltage (V):\t%f" % bus_v)
    print ("\tBus Current (A):\t%f" % bus_i)
    print ("\tTemp (C):\t\t%f" % temp)
    print ("\tFault:\t\t\t0x%x" % fault)

    print ("\t\tChecksum: 0x%x" % payload_checksum)

if __name__ == "__main__":
    main();
 M5 Thruster Module 
Operator's Manual, 1.01.00

Operations Guide

LED Blink Patterns
The POWER LED is a constant on RED when power is applied.

The other indicator is a three color LED package, which is made up of the STATUS led (blue), the MOTOR led (green), and the FAULT
led (RED). In diagnostic mode the STATUS and FAULT LEDs are turned ON.

The STATUS LED is blue and has several blink patterns:

Bootloader:
Three blinks on startup
Rapid blink if no valid application is found, or if commanded to stay in the bootloader.
Normal Operation:
Three blinks on application startup
One blink per second
Fast triple blink when a CSR communication packet is accepted

THE MOTOR LED is green and blink at a rate proportional to the RPM of the motor.

The FAULT LED is red and is active when a fault condition has been detected.