File content as of revision 0:7f26f0680202:

//=============================================================================
// Description  |  Header file with definition of the software interface
//              |  to the ROBO TX Controller firmware.
//              |  Can be used for building C-programs which can run
//              |  under control of the ROBO TX Controller firmware in
//              |  download (local) mode or for building PC-programs which
//              |  can communicate with the ROBO TX Controller firmware in
//              |  online mode.
//              |
// Copyright    |  � 2009 MSC Vertriebs GmbH, Germany.
//              |
//              |  This software is distributed in the hope that it will be useful,
//              |  but WITHOUT ANY WARRANTY; without even the implied warranty of
//              |  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
//=============================================================================

#ifndef __ROBO_TX_FW_H__
#define __ROBO_TX_FW_H__


#define N_CNT               4           // number of counters
#define N_PWM_CHAN          8           // number of PWM channels
#define N_MOTOR             4           // number of motors
#define N_UNI               8           // number of universal inputs

// 5kOhm range
#define R_MIN               10          // [Ohm]
#define R_MAX               4999        // [Ohm]
#define R_OVR               5000        // [Ohm] overload

// 10V range
#define U_MIN               0           // [mV]
#define U_MAX               9999        // [mV]
#define U_OVR               10000       // [mV] overload

// Ultrasonic Sensor range
#define ULTRASONIC_MIN      2           // [cm]
#define ULTRASONIC_MAX      1023        // [cm]
#define ULTRASONIC_OVR      1024        // [cm] overload
#define NO_ULTRASONIC       4096        // not present

// Motor outputs PWM values range
#define DUTY_MIN            0
#define DUTY_MAX            512

// Length of strings
#define DEV_NAME_LEN_MAX    16          // "ROBO TX-xxxxxxxx"
#define BLUETOOTH_ADDR_LEN  17          // "xx:xx:xx:xx:xx:xx"
#define DISPL_MSG_LEN_MAX   64          // max length of a pop-up display message


// Identifiers of the Transfer Area
enum ta_id_e
{
    TA_LOCAL = 0,           // Transfer Area for local Controller. Corresponds to the Controller
                            // on which program is currently running in download (local) mode or
                            // to the remotely controlled Controller (seen from controlled device,
                            // not from controlling device) in online mode.
    TA_EXT_1,               // Transfer Area for Extension 1 Controller
    TA_EXT_2,               // Transfer Area for Extension 2 Controller
    TA_EXT_3,               // Transfer Area for Extension 3 Controller
    TA_EXT_4,               // Transfer Area for Extension 4 Controller
    TA_EXT_5,               // Transfer Area for Extension 5 Controller
    TA_EXT_6,               // Transfer Area for Extension 6 Controller
    TA_EXT_7,               // Transfer Area for Extension 7 Controller
    TA_EXT_8,               // Transfer Area for Extension 8 Controller
    TA_COUNT                // Number of Transfer Areas in array = 9
};

#define N_EXT               (TA_COUNT - 1)  // Number of extension Controllers = 8


// Device (Controller) functioning modes
enum dev_mode_e
{
    DEV_MODE_LOCAL = 0,
    DEV_MODE_ONLINE,
    DEV_MODE_INVALID
};


// State of connection to an extension device (Controller)
enum ext_dev_connect_state_e
{
    EXT_DEV_OFFLINE = 0,
    EXT_DEV_ONLINE,
    EXT_DEV_INVALID
};


// Modes of universal inputs
enum input_mode_e
{
    MODE_U = 0,
    MODE_R = 1,
    MODE_ULTRASONIC = 3,
    MODE_INVALID
};


// Program states
enum pgm_state_e
{
    PGM_STATE_INVALID = 0,
    PGM_STATE_RUN,
    PGM_STATE_STOP
};


// Timer units for GetSystemTime hook function
enum TimerUnit
{
    TIMER_UNIT_INVALID        = 0,
    TIMER_UNIT_SECONDS        = 2,
    TIMER_UNIT_MILLISECONDS   = 3,
    TIMER_UNIT_MICROSECONDS   = 4
};


//=============================================================================
//  Structures for Transfer Area (TA)
//=============================================================================


// Program information, 8 bytes
typedef struct
{
    char          * name;   // Name of a program with a full path, for example, "/ramdisk/Program_1"
    UINT8           state;  // enum pgm_state_e
    char            reserved[3];
} PGM_INFO;


// Display message, 36 bytes. Used to show pop-up message box on the boards display
typedef struct
{
    unsigned char   id; // Should be increased by 1 each time a new pop-up message is to be shown
    char            text[DISPL_MSG_LEN_MAX + 1];
    char            reserved[2];
} DISPLAY_MSG;


// Display frame, 8 bytes. Used to refresh boards display with a bitmap image frame
typedef struct
{
    unsigned char * frame;  // Contents of a frame as a 128x64 pixels bitmap
    UINT16          id;     // Should be increased by 1 each time a new display frame is to be shown
    BOOL16          is_pgm_master_of_display;   // ++ if program wants to have control over display,
                                                // i.e. image frame is displayed over firmware menus;
                                                // -- if program wants to return control over display
                                                // to the firmware menus
} DISPLAY_FRAME;


// Version structure definition, 4 bytes
typedef union
{
    unsigned long abcd;
    struct
    {
        unsigned char   a;
        unsigned char   b;
        unsigned char   c;
        unsigned char   d;
    } part;
} FT_VER;


// Versions of hardware and firmware components, 16 bytes
typedef struct
{
    FT_VER          hardware;   // Version of hardware (hardware.part.a = 'A' or 'B' or 'C')
    FT_VER          firmware;   // Version of firmware ("V %d.%02d, DLL %d", firmware.part.c,
                                // firmware.part.d, firmware.part.b)
    FT_VER          ta;         // Version of transfer area ("V %d.%02d", ta.part.c, ta.part.d)
    char            reserved[4];
} FT_VERSION;


// Info structure, 64 bytes
typedef struct
{
    char            device_name[DEV_NAME_LEN_MAX + 1];  // Controller name
    char            bt_addr[BLUETOOTH_ADDR_LEN + 1];    // Bluetooth address as a string
    char            reserved;
    unsigned long   ta_array_start_addr;
    unsigned long   pgm_area_start_addr;
    unsigned long   pgm_area_size;
    FT_VERSION      version;
} TA_INFO;


// State structure, 36 bytes
typedef struct
{
    // Used by local program
    BOOL8           pgm_initialized;
    char            reserved_1[7];

    // Public state info
    BOOL8           dev_mode;   // enum dev_mode_e
    UCHAR8          id;         // Should be increased by 1 each time something (except id fields)
                                // is changed in this state structure
    UCHAR8          info_id;    // Should be increased by 1 each time something is changed in info structure
    UCHAR8          config_id;  // Should be increased by 1 each time something is changed in config structure
    BOOL8           ext_dev_connect_state[N_EXT];    // enum ext_dev_connect_state_e
    char            reserved_2[8];
    PGM_INFO        local_pgm;  // Corresponds to the program currently being in the program memory
} TA_STATE;


// Universal inputs configuration, 4 bytes
typedef struct
{
    UINT8           mode;       // enum input_mode_e
    BOOL8           digital;    // FALSE = analog input, TRUE = digital input
    unsigned char   reserved[2];
} UNI_CONFIG;


// Counter inputs configuration, 4 bytes
typedef struct
{
    UINT8           mode;       // 0 = normal counter mode (change 0 -> 1 is counted)
                                // 1 = inverse counter mode (change 1 -> 0 is counted)
    unsigned char   reserved[3];
} CNT_CONFIG;


// Config structure, 88 bytes
typedef struct
{
    UINT8           pgm_state_req;  // enum pgm_state_e, program state change request
    char            reserved_1[3];
    BOOL8           motor[N_MOTOR]; // TRUE = corresponding outputs are used as a pair of motor outputs M1...M4,
                                    // FALSE = corresponding outputs are used as a pair of separate digital
                                    // PWM outputs O1...O8
    UNI_CONFIG      uni[N_UNI];
    CNT_CONFIG      cnt[N_CNT];
    char            reserved_2[32];
} TA_CONFIG;


// Input structure, 44 bytes
typedef struct
{
    INT16           uni[N_UNI];             // Current values of the universal inputs
    INT16           cnt_in[N_CNT];          // Current levels (0 or 1) on the counter inputs according
                                            // to their configuration (normal or inverse)
    INT16           counter[N_CNT];         // Current values of the counter inputs
    INT16           display_button_left;    // Number of milliseconds during which the left display button
                                            // is being kept pressed
    INT16           display_button_right;   // Number of milliseconds during which the right display button
                                            // is being kept pressed
    INT16           motor_pos_reached[N_MOTOR]; // Set to 1 by motor control if target position
                                                // (distance from output structure) is reached
} TA_INPUT;


// Output structure, 36 bytes
typedef struct
{
    BOOL8           cnt_reset[N_CNT];   // Counter reset requests
    UINT8           master[N_MOTOR];    // If not 0, synchronize this channel with the given channel
                                        // (1:channel 0, ...)
    INT16           duty[N_PWM_CHAN];   // Selected motor outputs PWM values
    UINT16          distance[N_MOTOR];  // Selected distance (counter value) at which motor shall stop
    char            reserved[4];
} TA_OUTPUT;


// Display structure, 44 bytes
typedef struct
{
    DISPLAY_MSG     display_msg;
    DISPLAY_FRAME   display_frame;
} TA_DISPLAY;


// Change structure (only for ftMscLib), 8 bytes
typedef struct
{
    char            reserved_1[2];
    UINT8           ChangeStatus;   // TRUE = there was a change in any of the following fields
    UINT8           ChangeUni;      // There was a change of the input value (bit 0 = I1, bit 1 = I2, ...)
    UINT8           ChangeCntIn;    // There was a change of the counter level (bit 0 = C1, bit 1 = C2, ...)
    UINT8           ChangeCounter;  // There was a change of the counter value (bit 0 = C1, bit 1 = C2, ...)
    char            reserved_2[2];
} TA_CHANGE;


// 16-bit timers, 12 bytes
typedef struct
{
    UINT16          Timer1ms;
    UINT16          Timer10ms;
    UINT16          Timer100ms;
    UINT16          Timer1s;
    UINT16          Timer10s;
    UINT16          Timer1min;
} TA_TIMER;


struct ta_s;

// Hook table with pointers to the firmware functions,
// that can be called by local program, 16 bytes
typedef struct
{
    // Informs the calling program if it can still run (return TRUE) or should
    // immediately return to the firmware in order not to destroy the multitasking
    // mechanism of the firmware (return FALSE).
    BOOL32  (*IsRunAllowed)             (void);
    // Returns system time in seconds, milliseconds or microseconds depending on the
    // parameter unit.
    UINT32  (*GetSystemTime)            (enum TimerUnit unit);
    // Display pop-up message on the display of the ROBO TX Controller. If p_msg
    // is NULL, then all pop-up messages are removed from the display and its cache,
    // and the main frame is displayed.
    void    (*DisplayMsg)               (struct ta_s * p_ta, char * p_msg);
    // Returns TRUE if display is currently being refreshed. A program should in such a
    // case wait until the display finishes its refreshing before sending new output to it.
    BOOL32  (*IsDisplayBeingRefreshed)  (struct ta_s * p_ta);
} TA_HOOK_TABLE;



// ============================================================================
//  Transfer Area (TA) of ROBO TX Controller (one element of TA array)
// ============================================================================
#define RESERVED_1_SIZE  4
#define RESERVED_2_SIZE  28
#define RESERVED_3_SIZE \
    (512 - ( \
    sizeof(TA_INFO)         + \
    sizeof(TA_STATE)        + \
    sizeof(TA_CONFIG)       + \
    sizeof(TA_INPUT)        + \
    sizeof(TA_OUTPUT)       + \
    sizeof(TA_DISPLAY)      + \
    RESERVED_1_SIZE         + \
    sizeof(TA_CHANGE)       + \
    sizeof(TA_TIMER)        + \
    RESERVED_2_SIZE         + \
    sizeof(TA_HOOK_TABLE)     \
    ))


typedef struct ta_s
{
    TA_INFO             info;           // info structure
    TA_STATE            state;          // state structure
    TA_CONFIG           config;         // config structure   
    TA_INPUT            input;          // input structure
    TA_OUTPUT           output;         // output structure
    TA_DISPLAY          display;        // display structure

    char                reserved_1[RESERVED_1_SIZE];

    TA_CHANGE           change;         // change structure
    TA_TIMER            timer;          // 16-bit timers

    char                reserved_2[RESERVED_2_SIZE];

    TA_HOOK_TABLE       hook_table;     // hook table with functions pointers

    char                reserved_3[RESERVED_3_SIZE];
} TA;


#endif // __ROBO_TX_FW_H__