leon
/
Elysium
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Elysium/Demo_C/Common/ROBO_TX_FW.h

577 lines
23 KiB
C
Raw Permalink Blame History

//=============================================================================
// 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.
//
// Disclaimer - Exclusion of Liability
//
// 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. It can be used and modified by anyone
// free of any license obligations or authoring rights.
//=============================================================================
#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 BT_ADDR_STR_LEN 17 // "xx:xx:xx:xx:xx:xx"
#define DISPL_MSG_LEN_MAX 98 // Max. length of a pop-up display message
// Number of Bluetooth channels
#define BT_CNT_MAX 8
// Allowed values for channel index are 1...8
#define BT_CHAN_IDX_MIN 1
#define BT_CHAN_IDX_MAX 8
#define BT_ADDR_LEN 6 // Bluetooth address length
#define BT_MSG_LEN 16 // Max. Bluetooth message length
// Bluetooth connection states
enum BtConnState
{
BT_STATE_IDLE = 0, // BT channel is disconnected
BT_STATE_CONN_ONGOING, // BT channel is being connected
BT_STATE_CONNECTED, // BT channel is connected
BT_STATE_DISC_ONGOING // BT channel is being disconnected
};
// Status of Bluetooth inquiry scan
enum BtInquiryScanStatus
{
BT_INQUIRY_SCAN_NOT_POSSIBLE = 0,
BT_INQUIRY_SCAN_START,
BT_INQUIRY_SCAN_RESULT,
BT_INQUIRY_SCAN_BUSY,
BT_INQUIRY_SCAN_TIMEOUT,
BT_INQUIRY_SCAN_END
};
// Status codes for status field in Bluetooth callback functions
enum CB_BtStatus
{
/* 0 */ BT_SUCCESS = 0, // Successful end of command
/* 1 */ BT_CON_EXIST, // Already connected
/* 2 */ BT_CON_SETUP, // Establishing of connection is ongoing
/* 3 */ BT_SWITCHED_OFF, // Cannot connect/listen, Bluetooth is set to off
/* 4 */ BT_ALL_CHAN_BUSY, // Cannot connect, no more free Bluetooth channels
/* 5 */ BT_NOT_ROBOTX, // Cannot connect/listen, device is not a ROBO TX Controller
/* 6 */ BT_CON_TIMEOUT, // Cannot connect, timeout, no device with such a BT address
/* 7 */ BT_CON_INVALID, // Connection does not exist
/* 8 */ BT_CON_RELEASE, // Disconnecting is ongoing
/* 9 */ BT_LISTEN_ACTIVE, // Listen is already active
/* 10 */ BT_RECEIVE_ACTIVE, // Receive is already active
/* 11 */ BT_CON_INDICATION, // Passive connection establishment (incoming connection)
/* 12 */ BT_DISCON_INDICATION, // Passive disconnection (initiated by remote end)
/* 13 */ BT_MSG_INDICATION, // Received data (incoming message)
/* 14 */ BT_CHANNEL_BUSY, // No connect command is allowed when listen is active or
// no listen command is allowed when connected
/* 15 */ BT_BTADDR_BUSY, // BT address is already used by another channel
/* 16 */ BT_NO_LISTEN_ACTIVE // Cannot connect, no active listen on remote end
};
// 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
};
// Bluetooth inquiry scan status
typedef struct bt_scan_status_s
{
UINT16 status; // Status code, see enum BtInquiryScanStatus
// Bluetooth device info, valid only when status == BT_INQUIRY_SCAN_RESULT
UCHAR8 bt_addr[BT_ADDR_LEN];
char dummy_1[2];
char bt_name[DEV_NAME_LEN_MAX + 1];
char dummy_2[3];
} BT_SCAN_STATUS;
// Structure for Bluetooth callback functions (other than receive)
typedef struct bt_cb_s
{
UINT16 chan_idx; // Channel index
UINT16 status; // Status code, see enum CB_BtStatus
} BT_CB;
// Structure for Bluetooth receive callback function
typedef struct bt_receive_cb_s
{
UINT16 chan_idx; // Channel index
UINT16 status; // Status code, see enum CB_BtStatus
UINT16 msg_len; // Bluetooth message length
UCHAR8 msg[BT_MSG_LEN];// Bluetooth message
} BT_RECV_CB;
// Status codes for status field in I2C callback functions
enum CB_I2cStatus
{
/* 0 */ I2C_SUCCESS = 0, // Successful end of command
/* 1 */ I2C_READ_ERROR, // read error
/* 2 */ I2C_WRITE_ERROR // write error
};
// Structure for I2C callback functions
typedef struct i2c_cb_s
{
UINT16 value; // read/write value
UINT16 status; // status code, see enum CB_I2Status
} I2C_CB;
struct ta_s;
// Pointer to the Bluetooth callback function (other than receive)
typedef void (*P_CB_FUNC)(struct ta_s *, BT_CB *);
// Pointer to the Bluetooth receive callback function
typedef void (*P_RECV_CB_FUNC)(struct ta_s *, BT_RECV_CB *);
// Pointer to the I2C callback function
typedef void (*P_I2C_CB_FUNC)(struct ta_s *, I2C_CB *);
//=============================================================================
// Structures for Transfer Area (TA)
//=============================================================================
// Bluetooth connection status structure, 8 bytes
typedef struct btstatus_s
{
UINT16 conn_state; // See enum BtConnState
BOOL16 is_listen; // If TRUE - BT channel is waiting for incoming connection (listening)
BOOL16 is_receive; // If TRUE - BT channel is ready to receive incoming messages
UINT16 link_quality; // 0...31, 0 - the worst, 31 - the best signal quality
} BT_STATUS;
// Program information, 8 bytes
typedef struct
{
char * name; // Name of a program with a full path, for example, "/ramdisk/Program_1"
UINT8 state; // See enum pgm_state_e
char reserved[3];
} PGM_INFO;
// Display message, 128 bytes. Used to show pop-up message box on the boards display
typedef struct
{
UINT8 id; // Should be increased by 1 each time a new pop-up message is to be shown
char text[DISPL_MSG_LEN_MAX + 1];
} DISPLAY_MSG;
// Display frame, 8 bytes. Used to refresh boards display with a bitmap image frame
typedef struct
{
UCHAR8 * 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
{
UINT32 abcd;
struct
{
UCHAR8 a;
UCHAR8 b;
UCHAR8 c;
UCHAR8 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[BT_ADDR_STR_LEN + 1]; // Bluetooth address as a string
char reserved;
UINT32 ta_array_start_addr;
UINT32 pgm_area_start_addr;
UINT32 pgm_area_size;
FT_VERSION version;
} TA_INFO;
// State structure, 100 bytes
typedef struct
{
// Used by local program
BOOL8 pgm_initialized;
char reserved_1[7];
// Public state info
BOOL8 dev_mode; // See enum dev_mode_e
UINT8 id; // Should be increased by 1 each time something (except id fields and btstatus)
// is changed in this state structure
UINT8 info_id; // Should be increased by 1 each time something is changed in info structure
UINT8 config_id; // Should be increased by 1 each time something is changed in config structure
BOOL8 ext_dev_connect_state[N_EXT]; // See enum ext_dev_connect_state_e
BT_STATUS btstatus[BT_CNT_MAX]; // Status of Bluetooth connections
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; // See enum input_mode_e
BOOL8 digital; // FALSE = analog input, TRUE = digital input
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)
char reserved[3];
} CNT_CONFIG;
// Config structure, 88 bytes
typedef struct
{
UINT8 pgm_state_req; // See 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, 68 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
BOOL16 cnt_resetted[N_CNT]; // Set to 1 when last requested counter reset was fulfilled
BOOL16 motor_pos_reached[N_MOTOR]; // Set to 1 by motor control if target position
// (distance from output structure) is reached
char reserved[16];
} TA_INPUT;
// Output structure, 44 bytes
typedef struct
{
UINT16 cnt_reset_cmd_id[N_CNT]; // Counter reset requests (should be increased by 1 each time
// counter reset is needed)
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
UINT16 motor_ex_cmd_id[N_MOTOR]; // Should be increased by 1 each time settings for extended
// motor control mode (duty and/or distance) are changed
} TA_OUTPUT;
// Display structure, 108 bytes
typedef struct
{
DISPLAY_MSG display_msg;
DISPLAY_FRAME display_frame;
} TA_DISPLAY;
// Status of Transfer Area (valid only for ftMscLib), 4 bytes
typedef struct
{
UINT8 status; // Status of transfer area
// TA_STATUS_STOP = 0 - Transfer Area is not running,
// TA_STATUS_RUN = 1 - Transfer Area is running,
// TA_STATUS_SYNC = 2 - Transfer Area is being synchronized
UINT8 iostatus; // Status of I/O communication
// SE_REMIO_REQ = 0 - Remote I/O Request was sent,
// SE_CONFIG_REQ = 1 - Set Configuration Request was sent
UINT16 ComErr; // System error code by COM port connection error
} TA_STATUS;
// Change structure (valid 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;
// Hook table with pointers to the firmware functions,
// that can be called by local program, 132 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);
// Connect to the Bluetooth device with the given Bluetooth address through the given
// channel (1...8). If p_cb_func (pointer to the callback function) is not NULL, then the
// callback function is called to inform about the result of this command.
void (*BtConnect) (UINT32 channel, UCHAR8 * btaddr, P_CB_FUNC p_cb_func);
// Disconnect from the Bluetooth device on the given channel (1...8). If p_cb_func
// (pointer to the callback function) is not NULL, then the callback function is called
// to inform about the result of this command.
void (*BtDisconnect) (UINT32 channel, P_CB_FUNC p_cb_func);
// Send a message (max 255 characters) through the given Bluetooth channel (1...8).
// If p_cb_func (pointer to the callback function) is not NULL, then the callback function is called
// to inform about the result of this command.
void (*BtSend) (UINT32 channel, UINT32 len, UCHAR8 * p_msg, P_CB_FUNC p_cb_func);
// Start wait for incoming messages on the given Bluetooth channel (1...8). If p_cb_func
// (pointer to the callback function) is not NULL, then the callback function is called
// to inform about the result of this command and about arrival of a Bluetooth message.
void (*BtStartReceive) (UINT32 channel, P_RECV_CB_FUNC p_cb_func);
// Stop wait for incoming messages on the given Bluetooth channel (1...8). If p_cb_func
// (pointer to the callback function) is not NULL, then the callback function is called
// to inform about the result of this command.
void (*BtStopReceive) (UINT32 channel, P_RECV_CB_FUNC p_cb_func);
// Start wait for incoming connection (i.e. listen) from the Bluetooth device with the given
// Bluetooth address on the given channel (1...8). If p_cb_func (pointer to the callback function)
// is not NULL, then the callback function is called to inform about the result of this command.
void (*BtStartListen) (UINT32 channel, UCHAR8 * btaddr, P_CB_FUNC p_cb_func);
// Stop wait for incoming connection (i.e. listen) on the given Bluetooth channel (1...8).
// If p_cb_func (pointer to the callback function) is not NULL, then the callback function is called
// to inform about the result of this command.
void (*BtStopListen) (UINT32 channel, P_CB_FUNC p_cb_func);
// Convert a Bluetooth address (6 bytes) to the string with the format "xx:xx:xx:xx:xx:xx".
// Returns pointer to the string with converted btaddr (same pointer as str parameter).
char *(*BtAddrToStr) (UCHAR8 * btaddr, char * str);
// Interface to I2C API functions
UINT32 (*I2cRead) (UCHAR8 devaddr, UINT32 offset, UCHAR8 protocol, P_I2C_CB_FUNC p_cb_func);
UINT32 (*I2cWrite) (UCHAR8 devaddr, UINT32 offset, UINT16 data, UCHAR8 protocol, P_I2C_CB_FUNC p_cb_func);
// Interface to some runtime library functions.
INT32 (*sprintf) (char * s, const char * format, ...);
INT32 (*memcmp) (const void * s1, const void * s2, UINT32 n);
void *(*memcpy) (void * s1, const void * s2, UINT32 n);
void *(*memmove) (void * s1, const void * s2, UINT32 n);
void *(*memset) (void * s, INT32 c, UINT32 n);
char *(*strcat) (char * s1, const char * s2);
char *(*strncat) (char * s1, const char * s2, UINT32 n);
char *(*strchr) (const char * s, INT32 c);
char *(*strrchr) (const char * s, INT32 c);
INT32 (*strcmp) (const char * s1, const char * s2);
INT32 (*strncmp) (const char * s1, const char * s2, UINT32 n);
INT32 (*stricmp) (const char * s1, const char * s2);
INT32 (*strnicmp) (const char * s1, const char * s2, UINT32 n);
char *(*strcpy) (char * s1, const char * s2);
char *(*strncpy) (char * s1, const char * s2, UINT32 n);
UINT32 (*strlen) (const char * s);
char *(*strstr) (const char * s1, const char * s2);
char *(*strtok) (char * s1, const char * s2);
char *(*strupr) (char * s);
char *(*strlwr) (char * s);
INT32 (*atoi) (const char * nptr);
} TA_HOOK_TABLE;
// ============================================================================
// Transfer Area (TA) of ROBO TX Controller (one element of TA array)
// ============================================================================
#define RESERVED_1_SIZE 28
#define RESERVED_2_SIZE \
(1024 - ( \
sizeof(TA_INFO) + \
sizeof(TA_STATE) + \
sizeof(TA_CONFIG) + \
sizeof(TA_INPUT) + \
sizeof(TA_OUTPUT) + \
sizeof(TA_DISPLAY) + \
sizeof(TA_STATUS) + \
sizeof(TA_CHANGE) + \
sizeof(TA_TIMER) + \
RESERVED_1_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
TA_STATUS status; // status structure
TA_CHANGE change; // change structure
TA_TIMER timer; // 16-bit timers
char reserved_1[RESERVED_1_SIZE];
TA_HOOK_TABLE hook_table; // hook table with functions pointers
char reserved_2[RESERVED_2_SIZE];
} TA;
#endif // __ROBO_TX_FW_H__
Reference in New Issue View Git Blame Copy Permalink