USBInterface.h

Go to the documentation of this file.

/*
 * Copyright (c) 2013, Osnabrueck University
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * * Redistributions of source code must retain the above copyright notice,
 *   this list of conditions and the following disclaimer.
 * * Redistributions in binary form must reproduce the above copyright notice,
 *   this list of conditions and the following disclaimer in the documentation
 *   and/or other materials provided with the distribution.
 * * Neither the name of the Osnabrueck University nor the names of its
 *   contributors may be used to endorse or promote products derived from this
 *   software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef USBINTERFACE_H_
#define USBINTERFACE_H_

#include <libusb.h>
#include <list>
#include <string>
#include <cmath>
#include <cstdint>
#include <unistd.h>

using std::string;
using std::fabs;

enum ChannelMode
{
    Servo=0,
    ServoMultiplied=1,
    Output=2,
    Input = 3,
};

enum HomeMode
{
    Off=0,
    Ignore=1,
    Goto=2
};


enum uscSerialMode
{
    SERIAL_MODE_USB_DUAL_PORT = 0,

    SERIAL_MODE_USB_CHAINED = 1,

    SERIAL_MODE_UART_DETECT_BAUD_RATE = 2,

    SERIAL_MODE_UART_FIXED_BAUD_RATE = 3,
};


enum uscRequest
{
    REQUEST_GET_PARAMETER = 0x81,
    REQUEST_SET_PARAMETER = 0x82,
    REQUEST_GET_VARIABLES = 0x83,
    REQUEST_SET_SERVO_VARIABLE = 0x84,
    REQUEST_SET_TARGET = 0x85,
    REQUEST_CLEAR_ERRORS = 0x86,
    REQUEST_GET_SERVO_SETTINGS = 0x87,

    // GET STACK and GET CALL STACK are only used on the Mini Maestro.
    REQUEST_GET_STACK = 0x88,
    REQUEST_GET_CALL_STACK = 0x89,
    REQUEST_SET_PWM = 0x8A,

    REQUEST_REINITIALIZE = 0x90,
    REQUEST_ERASE_SCRIPT = 0xA0,
    REQUEST_WRITE_SCRIPT = 0xA1,
    REQUEST_SET_SCRIPT_DONE = 0xA2, // value.low.b is 0 for go, 1 for stop, 2 for single-step
    REQUEST_RESTART_SCRIPT_AT_SUBROUTINE = 0xA3,
    REQUEST_RESTART_SCRIPT_AT_SUBROUTINE_WITH_PARAMETER = 0xA4,
    REQUEST_RESTART_SCRIPT = 0xA5,
    REQUEST_START_BOOTLOADER = 0xFF
};


struct channelSetting
{
    channelSetting()
    {
        name = "";
        mode = ChannelMode::Servo;
        homeMode = HomeMode::Off;
        home = 6000;
        minimum = 3968;
        maximum = 8000;
        neutral = 6000;
        range = 1905;
        speed = 0;
        acceleration = 0;
    }


    string name;

    ChannelMode mode;

    HomeMode homeMode;

    uint16_t home;

    uint16_t minimum;

    uint16_t maximum;

    uint16_t neutral;

    uint16_t range;

    uint16_t speed;

    uint8_t acceleration;
};


struct uscSettings
{
    uscSettings()
    {
        servosAvailable = 6;
        servoPeriod = 156;
        miniMaestroServoPeriod = 80000;
        servoMultiplier = 1;
        serialMode = uscSerialMode::SERIAL_MODE_UART_DETECT_BAUD_RATE;
        fixedBaudRate = 9600;
        enableCrc = false;
        neverSuspend = false;
        serialDeviceNumber = 12;
        miniSscOffset = 0;
        serialTimeout = 0;
        scriptDone = true;
        enablePullups = false;
    }


    uint8_t servosAvailable;

    uint8_t  servoPeriod;

    uint32_t miniMaestroServoPeriod;

    uint16_t servoMultiplier;

    uscSerialMode serialMode;

    uint32_t fixedBaudRate;

    bool enableCrc;

    bool neverSuspend;

    uint8_t serialDeviceNumber;

    uint8_t miniSscOffset;

    uint16_t serialTimeout;

    bool scriptDone;

    std::list<channelSetting> channelSettings;

    bool enablePullups;
};

struct servoStatus
{
    uint16_t position;

    uint16_t target;

    uint16_t speed;

    uint8_t acceleration;
};

struct maestroStatus
{
    uint8_t stackPointer;

    uint8_t callStackPointer;

    uint16_t errors;

    uint16_t programCounter;

    int16_t buffer[3];

    int16_t stack[32];

    uint16_t callStack[10];

    uint8_t scriptDone;

    uint8_t buffer2;
};

enum uscParameter
{
    PARAMETER_INITIALIZED = 0, // 1 byte - 0 or 0xFF
    PARAMETER_SERVOS_AVAILABLE = 1, // 1 byte - 0-5
    PARAMETER_SERVO_PERIOD = 2, // 1 byte - ticks allocated to each servo/256
    PARAMETER_SERIAL_MODE = 3, // 1 byte unsigned value.  Valid values are SERIAL_MODE_*.  Init variable.
    PARAMETER_SERIAL_FIXED_BAUD_RATE = 4, // 2-byte unsigned value; 0 means autodetect.  Init parameter.
    PARAMETER_SERIAL_TIMEOUT = 6, // 2-byte unsigned value
    PARAMETER_SERIAL_ENABLE_CRC = 8, // 1 byte boolean value
    PARAMETER_SERIAL_NEVER_SUSPEND = 9, // 1 byte boolean value
    PARAMETER_SERIAL_DEVICE_NUMBER = 10, // 1 byte unsigned value, 0-127
    PARAMETER_SERIAL_BAUD_DETECT_TYPE = 11, // 1 byte value

    PARAMETER_IO_MASK_C = 16, // 1 byte - pins used for I/O instead of servo
    PARAMETER_OUTPUT_MASK_C = 17, // 1 byte - outputs that are enabled

    PARAMETER_CHANNEL_MODES_0_3                 = 12, // 1 byte - channel modes 0-3
    PARAMETER_CHANNEL_MODES_4_7                 = 13, // 1 byte - channel modes 4-7
    PARAMETER_CHANNEL_MODES_8_11                = 14, // 1 byte - channel modes 8-11
    PARAMETER_CHANNEL_MODES_12_15               = 15, // 1 byte - channel modes 12-15
    PARAMETER_CHANNEL_MODES_16_19               = 16, // 1 byte - channel modes 16-19
    PARAMETER_CHANNEL_MODES_20_23               = 17, // 1 byte - channel modes 20-23
    PARAMETER_MINI_MAESTRO_SERVO_PERIOD_L = 18, // servo period: 3-byte unsigned values, units of quarter microseconds
    PARAMETER_MINI_MAESTRO_SERVO_PERIOD_HU = 19,
    PARAMETER_ENABLE_PULLUPS = 21,  // 1 byte: 0 or 1
    PARAMETER_SCRIPT_CRC = 22, // 2 bytes - stores a checksum of the bytecode program, for comparison
    PARAMETER_SCRIPT_DONE = 24, // 1 byte - copied to scriptDone on startup
    PARAMETER_SERIAL_MINI_SSC_OFFSET = 25, // 1 byte (0-254)
    PARAMETER_SERVO_MULTIPLIER = 26, // 1 byte (0-255)

    // 9 * 24 = 216, so we can safely start at 30
    PARAMETER_SERVO0_HOME = 30, // 2 byte home position (0=off; 1=ignore)
    PARAMETER_SERVO0_MIN = 32, // 1 byte min allowed value (x2^6)
    PARAMETER_SERVO0_MAX = 33, // 1 byte max allowed value (x2^6)
    PARAMETER_SERVO0_NEUTRAL = 34, // 2 byte neutral position
    PARAMETER_SERVO0_RANGE = 36, // 1 byte range
    PARAMETER_SERVO0_SPEED = 37, // 1 byte (5 mantissa,3 exponent) us per 10ms
    PARAMETER_SERVO0_ACCELERATION = 38, // 1 byte (speed changes that much every 10ms)
    PARAMETER_SERVO1_HOME = 39, // 2 byte home position (0=off; 1=ignore)
    PARAMETER_SERVO1_MIN = 41, // 1 byte min allowed value (x2^6)
    PARAMETER_SERVO1_MAX = 42, // 1 byte max allowed value (x2^6)
    PARAMETER_SERVO1_NEUTRAL = 43, // 2 byte neutral position
    PARAMETER_SERVO1_RANGE = 45, // 1 byte range
    PARAMETER_SERVO1_SPEED = 46, // 1 byte (5 mantissa,3 exponent) us per 10ms
    PARAMETER_SERVO1_ACCELERATION = 47, // 1 byte (speed changes that much every 10ms)
    PARAMETER_SERVO2_HOME = 48, // 2 byte home position (0=off; 1=ignore)
    PARAMETER_SERVO2_MIN = 50, // 1 byte min allowed value (x2^6)
    PARAMETER_SERVO2_MAX = 51, // 1 byte max allowed value (x2^6)
    PARAMETER_SERVO2_NEUTRAL = 52, // 2 byte neutral position
    PARAMETER_SERVO2_RANGE = 54, // 1 byte range
    PARAMETER_SERVO2_SPEED = 55, // 1 byte (5 mantissa,3 exponent) us per 10ms
    PARAMETER_SERVO2_ACCELERATION = 56, // 1 byte (speed changes that much every 10ms)
    PARAMETER_SERVO3_HOME = 57, // 2 byte home position (0=off; 1=ignore)
    PARAMETER_SERVO3_MIN = 59, // 1 byte min allowed value (x2^6)
    PARAMETER_SERVO3_MAX = 60, // 1 byte max allowed value (x2^6)
    PARAMETER_SERVO3_NEUTRAL = 61, // 2 byte neutral position
    PARAMETER_SERVO3_RANGE = 63, // 1 byte range
    PARAMETER_SERVO3_SPEED = 64, // 1 byte (5 mantissa,3 exponent) us per 10ms
    PARAMETER_SERVO3_ACCELERATION = 65, // 1 byte (speed changes that much every 10ms)
    PARAMETER_SERVO4_HOME = 66, // 2 byte home position (0=off; 1=ignore)
    PARAMETER_SERVO4_MIN = 68, // 1 byte min allowed value (x2^6)
    PARAMETER_SERVO4_MAX = 69, // 1 byte max allowed value (x2^6)
    PARAMETER_SERVO4_NEUTRAL = 70, // 2 byte neutral position
    PARAMETER_SERVO4_RANGE = 72, // 1 byte range
    PARAMETER_SERVO4_SPEED = 73, // 1 byte (5 mantissa,3 exponent) us per 10ms
    PARAMETER_SERVO4_ACCELERATION = 74, // 1 byte (speed changes that much every 10ms)
    PARAMETER_SERVO5_HOME = 75, // 2 byte home position (0=off; 1=ignore)
    PARAMETER_SERVO5_MIN = 77, // 1 byte min allowed value (x2^6)
    PARAMETER_SERVO5_MAX = 78, // 1 byte max allowed value (x2^6)
    PARAMETER_SERVO5_NEUTRAL = 79, // 2 byte neutral position
    PARAMETER_SERVO5_RANGE = 81, // 1 byte range
    PARAMETER_SERVO5_SPEED = 82, // 1 byte (5 mantissa,3 exponent) us per 10ms
    PARAMETER_SERVO5_ACCELERATION = 83, // 1 byte (speed changes that much every 10ms)
};


const uint8_t servoParameterBytes = 9;


class USBPololuInterface
{
public:
    USBPololuInterface(uint16_t vendorID = 8187, uint16_t productID = 137);
    ~USBPololuInterface();

    void setTarget(int servo, ushort value);
    void setSpeed(int servo, ushort value);
    void moveToTarget(int servo, ushort value);
    void moveToTarget(int servo, ushort value, ushort time);
    void getServoStatus(int servo, servoStatus& status);

    void setUscSettings(uscSettings settings);

    static int MOVE_TARGET_TIMEOUT;
    static int MOVE_TARGET_MAX_TRYS;
private:

    void controlTransfer(char requestType, char request, ushort value, ushort index);
    void controlTransfer(char requestType, char request, ushort Value, ushort Index, unsigned char * data, ushort length);


    uscParameter    specifyServo(uscParameter p, uint8_t servo);
    void            setRawParameter(ushort parameter, ushort value, int bytes);
    uint8_t         channelToPort(uint8_t channel);
    uint8_t         normalSpeedToExponentialSpeed(ushort normalSpeed);

    string getErrorDescription(int code);
    libusb_device*              m_device;
    libusb_context*             m_context;
    libusb_device_handle*       m_deviceHandle;

};


#endif /* USBINTERFACE_H_ */