Before Contacting Support

Equipment Mounting

Click on the image to view this image as a PDF in a new window.

5 Pin Connector

The M5 Thruster Module 5 pin connector is 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

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

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.

Firmware

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 [   ].

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

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 "+++++" (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.

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

Programming

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.

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 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.

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

#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))

    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();

European Union (EU)

The following sections are specific to the European Union.

The Waste Electrical and Electronic Equipment Regulations (WEEE) 2013

In accordance with the requirements of the Waste Electrical and Electronic Equipment Regulations 2013, all non fixed electrical and electronic equipment must be disposed of correctly at the end of its useful life through an authorised waste company, and there is an associated requirement to obtain the correct paperwork as per Duty of Care legislation. Please ensure that you treat this equipment as WEEE when you come to dispose of it.