Gateway ASCII mapping
CANopen_309

## Modules

| Command syntax

## Files

file | CO_gateway_ascii.h
| CANopen access from other networks - ASCII mapping (CiA 309-3 DS v3.0.0)

## Data Structures

struct | CO_GTWA_t
| CANopen Gateway-ascii object. More...

## Macros

#define | CO_GTWA_RESP_BUF_SIZE 200
| Size of response string buffer. More...
#define | CO_GTWA_STATE_TIMEOUT_TIME_US 1200000
| Timeout time in microseconds for some internal states.

## Enumerations

enum

CO_GTWA_respErrorCode_t {
CO_GTWA_respErrorNone = 0, CO_GTWA_respErrorReqNotSupported = 100, CO_GTWA_respErrorSyntax = 101, CO_GTWA_respErrorInternalState = 102,
CO_GTWA_respErrorTimeOut = 103, CO_GTWA_respErrorNoDefaultNetSet = 104, CO_GTWA_respErrorNoDefaultNodeSet = 105, CO_GTWA_respErrorUnsupportedNet = 106,
CO_GTWA_respErrorUnsupportedNode = 107, CO_GTWA_respErrorLostGuardingMessage = 200, CO_GTWA_respErrorLostConnection = 201, CO_GTWA_respErrorHeartbeatStarted = 202,
CO_GTWA_respErrorHeartbeatLost = 203, CO_GTWA_respErrorWrongNMTstate = 204, CO_GTWA_respErrorBootUp = 205, CO_GTWA_respErrorErrorPassive = 300,
CO_GTWA_respErrorBusOff = 301, CO_GTWA_respErrorCANbufferOverflow = 303, CO_GTWA_respErrorCANinit = 304, CO_GTWA_respErrorCANactive = 305,
CO_GTWA_respErrorPDOalreadyUsed = 400, CO_GTWA_respErrorPDOlengthExceeded = 401, CO_GTWA_respErrorLSSmanufacturer = 501, CO_GTWA_respErrorLSSnodeIdNotSupported = 502,
CO_GTWA_respErrorLSSbitRateNotSupported = 503, CO_GTWA_respErrorLSSparameterStoringFailed = 504, CO_GTWA_respErrorLSSmediaError = 505, CO_GTWA_respErrorRunningOutOfMemory = 600
}

| Response error codes as specified by CiA 309-3. More...

enum

CO_GTWA_state_t {
CO_GTWA_ST_IDLE = 0x00U, CO_GTWA_ST_READ = 0x10U, CO_GTWA_ST_WRITE = 0x11U, CO_GTWA_ST_WRITE_ABORTED = 0x12U,
CO_GTWA_ST_LSS_SWITCH_GLOB = 0x20U, CO_GTWA_ST_LSS_SWITCH_SEL = 0x21U, CO_GTWA_ST_LSS_SET_NODE = 0x22U, CO_GTWA_ST_LSS_CONF_BITRATE = 0x23U,
CO_GTWA_ST_LSS_STORE = 0x24U, CO_GTWA_ST_LSS_INQUIRE = 0x25U, CO_GTWA_ST_LSS_INQUIRE_ADDR_ALL = 0x26U, CO_GTWA_ST__LSS_FASTSCAN = 0x30U,
CO_GTWA_ST_LSS_ALLNODES = 0x31U, CO_GTWA_ST_LOG = 0x80U, CO_GTWA_ST_HELP = 0x81U, CO_GTWA_ST_LED = 0x82U
}

| Internal states of the Gateway-ascii state machine. More...

## Functions

CO_ReturnError_t | CO_GTWA_init (CO_GTWA_t *gtwa, CO_SDOclient_t *SDO_C, uint16_t SDOclientTimeoutTime_ms, bool_t SDOclientBlockTransfer, CO_NMT_t *NMT, CO_LSSmaster_t *LSSmaster, CO_LEDs_t *LEDs, uint8_t dummy)
| Initialize Gateway-ascii object. More...
void | CO_GTWA_initRead (CO_GTWA_t *gtwa, size_t(*readCallback)(void *object, const char *buf, size_t count, uint8_t *connectionOK), void *readCallbackObject)
| Initialize read callback in Gateway-ascii object. More...
static size_t | CO_GTWA_write_getSpace (CO_GTWA_t *gtwa)
| Get free write buffer space. More...
static size_t | CO_GTWA_write (CO_GTWA_t *gtwa, const char *buf, size_t count)
| Write command into CO_GTWA_t object. More...
void | CO_GTWA_log_print (CO_GTWA_t *gtwa, const char *message)
| Print message log string into fifo buffer. More...
void | CO_GTWA_process (CO_GTWA_t *gtwa, bool_t enable, uint32_t timeDifference_us, uint32_t *timerNext_us)
| Process Gateway-ascii object. More...

## Detailed Description

CANopen access from other networks - ASCII mapping (CiA 309-3 DSP v3.0.0)

This module enables ascii command interface (CAN gateway), which can be used for master interaction with CANopen network. Some sort of string input/output stream can be used, for example serial port + terminal on microcontroller or stdio in OS or sockets, etc.

For example, one wants to read 'Heartbeat producer time' parameter (0x1017,0) on remote node (with id=4). Parameter is 16-bit integer. He can can enter command string: `[1] 4 read 0x1017 0 i16`. CANopenNode will use SDO client, send request to remote node via CAN, wait for response via CAN and prints `[1] OK` to output stream on success.

This module is usually initialized and processed in CANopen.c file. Application should register own callback function for reading the output stream. Application writes new commands with CO_GTWA_write().

## Macro Definition Documentation

## CO_GTWA_RESP_BUF_SIZE

#define CO_GTWA_RESP_BUF_SIZE 200

Size of response string buffer.

This is intermediate buffer. If there is larger amount of data to transfer, then multiple transfers will occur.

## Enumeration Type Documentation

## CO_GTWA_respErrorCode_t

enum CO_GTWA_respErrorCode_t

Response error codes as specified by CiA 309-3.

Values less or equal to 0 are used for control for some functions and are not part of the standard.

Enumerator
CO_GTWA_respErrorNone | 0 - No error or idle
CO_GTWA_respErrorReqNotSupported | 100 - Request not supported
CO_GTWA_respErrorSyntax | 101 - Syntax error
CO_GTWA_respErrorInternalState | 102 - Request not processed due to internal state
CO_GTWA_respErrorTimeOut | 103 - Time-out (where applicable)
CO_GTWA_respErrorNoDefaultNetSet | 104 - No default net set
CO_GTWA_respErrorNoDefaultNodeSet | 105 - No default node set
CO_GTWA_respErrorUnsupportedNet | 106 - Unsupported net
CO_GTWA_respErrorUnsupportedNode | 107 - Unsupported node
CO_GTWA_respErrorLostGuardingMessage | 200 - Lost guarding message
CO_GTWA_respErrorLostConnection | 201 - Lost connection
CO_GTWA_respErrorHeartbeatStarted | 202 - Heartbeat started
CO_GTWA_respErrorHeartbeatLost | 203 - Heartbeat lost
CO_GTWA_respErrorWrongNMTstate | 204 - Wrong NMT state
CO_GTWA_respErrorBootUp | 205 - Boot-up
CO_GTWA_respErrorErrorPassive | 300 - Error passive
CO_GTWA_respErrorBusOff | 301 - Bus off
CO_GTWA_respErrorCANbufferOverflow | 303 - CAN buffer overflow
CO_GTWA_respErrorCANinit | 304 - CAN init
CO_GTWA_respErrorCANactive | 305 - CAN active (at init or start-up)
CO_GTWA_respErrorPDOalreadyUsed | 400 - PDO already used
CO_GTWA_respErrorPDOlengthExceeded | 401 - PDO length exceeded
CO_GTWA_respErrorLSSmanufacturer | 501 - LSS implementation- / manufacturer-specific error
CO_GTWA_respErrorLSSnodeIdNotSupported | 502 - LSS node-ID not supported
CO_GTWA_respErrorLSSbitRateNotSupported | 503 - LSS bit-rate not supported
CO_GTWA_respErrorLSSparameterStoringFailed | 504 - LSS parameter storing failed
CO_GTWA_respErrorLSSmediaError | 505 - LSS command failed because of media error
CO_GTWA_respErrorRunningOutOfMemory | 600 - Running out of memory

## CO_GTWA_state_t

enum CO_GTWA_state_t

Internal states of the Gateway-ascii state machine.

Enumerator
CO_GTWA_ST_IDLE | Gateway is idle, no command is processing. This state is starting point for new commands, which are parsed here.
CO_GTWA_ST_READ | SDO 'read' (upload)
CO_GTWA_ST_WRITE | SDO 'write' (download)
CO_GTWA_ST_WRITE_ABORTED | SDO 'write' (download) - aborted, purging remaining data.
CO_GTWA_ST_LSS_SWITCH_GLOB | LSS 'lss_switch_glob'.
CO_GTWA_ST_LSS_SWITCH_SEL | LSS 'lss_switch_sel'.
CO_GTWA_ST_LSS_SET_NODE | LSS 'lss_set_node'.
CO_GTWA_ST_LSS_CONF_BITRATE | LSS 'lss_conf_bitrate'.
CO_GTWA_ST_LSS_STORE | LSS 'lss_store'.
CO_GTWA_ST_LSS_INQUIRE | LSS 'lss_inquire_addr' or 'lss_get_node'.
CO_GTWA_ST_LSS_INQUIRE_ADDR_ALL | LSS 'lss_inquire_addr', all parameters.
CO_GTWA_ST__LSS_FASTSCAN | LSS '_lss_fastscan'.
CO_GTWA_ST_LSS_ALLNODES | LSS 'lss_allnodes'.
CO_GTWA_ST_LOG | print message 'log'
CO_GTWA_ST_HELP | print 'help' text
CO_GTWA_ST_LED | print 'status' of the node

## Function Documentation

## CO_GTWA_init()

CO_ReturnError_t CO_GTWA_init | ( | CO_GTWA_t * | gtwa,
|  | CO_SDOclient_t * | SDO_C,
|  | uint16_t | SDOclientTimeoutTime_ms,
|  | bool_t | SDOclientBlockTransfer,
|  | CO_NMT_t * | NMT,
|  | CO_LSSmaster_t * | LSSmaster,
|  | CO_LEDs_t * | LEDs,
|  | uint8_t | dummy
| ) |  |

Initialize Gateway-ascii object.

Parameters

  gtwa | This object will be initialized
  SDO_C | SDO client object
  SDOclientTimeoutTime_ms | Default timeout in milliseconds, 500 typically
  SDOclientBlockTransfer | If true, block transfer will be set by default
  NMT | NMT object
  LSSmaster | LSS master object
  LEDs | LEDs object
  dummy | dummy argument, set to 0

Returns
  CO_ReturnError_t: CO_ERROR_NO or CO_ERROR_ILLEGAL_ARGUMENT

## CO_GTWA_initRead()

void CO_GTWA_initRead | ( | CO_GTWA_t * | gtwa,
|  | size_t(*)(void *object, const char *buf, size_t count, uint8_t *connectionOK) | readCallback,
|  | void * | readCallbackObject
| ) |  |

Initialize read callback in Gateway-ascii object.

Callback will be used for transfer data to output stream of the application. It will be called from CO_GTWA_process() zero or multiple times, depending on the data available. If readCallback is uninitialized or NULL, then output data will be purged.

Parameters

  gtwa | This object will be initialized
  readCallback | Pointer to external function for reading response from Gateway-ascii object. See CO_GTWA_t for parameters.
  readCallbackObject | Pointer to object, which will be used inside readCallback

## CO_GTWA_write_getSpace()

static size_t CO_GTWA_write_getSpace | ( | CO_GTWA_t * | gtwa | ) |

inlinestatic

Get free write buffer space.

Parameters

  gtwa | This object

Returns
  number of available bytes

## CO_GTWA_write()

static size_t CO_GTWA_write | ( | CO_GTWA_t * | gtwa,
|  | const char * | buf,
|  | size_t | count
| ) |  |

inlinestatic

Write command into CO_GTWA_t object.

This function copies ascii command from buf into internal fifo buffer. Command must be closed with '
' character. Function returns number of bytes successfully copied. If there is not enough space in destination, not all bytes will be copied and data can be refilled later (in case of large SDO download).

Parameters

  gtwa | This object
  buf | Buffer which will be copied
  count | Number of bytes in buf

Returns
  number of bytes actually written.

## CO_GTWA_log_print()

void CO_GTWA_log_print | ( | CO_GTWA_t * | gtwa,
|  | const char * | message
| ) |  |

Print message log string into fifo buffer.

This function enables recording of system log messages including CANopen events. Function can be called by application for recording any message. Message is copied to internal fifo buffer. In case fifo is full, old messages will be owerwritten. Message log fifo can be read with non-standard command "log". After log is read, it is emptied.

Parameters

  gtwa | This object
  message | Null terminated string

## CO_GTWA_process()

void CO_GTWA_process | ( | CO_GTWA_t * | gtwa,
|  | bool_t | enable,
|  | uint32_t | timeDifference_us,
|  | uint32_t * | timerNext_us
| ) |  |

Process Gateway-ascii object.

This is non-blocking function and must be called cyclically

Parameters

  | gtwa | This object will be initialized.
  | enable | If true, gateway operates normally. If false, gateway is completely disabled and no command interaction is possible. Can be connected to hardware switch, for example.
  | timeDifference_us | Time difference from previous function call in [microseconds].
  [out] | timerNext_us | info to OS - see CO_process().

Returns
  CO_ReturnError_t: CO_ERROR_NO on success or CO_ERROR_ILLEGAL_ARGUMENT