Systems Communication Interface. More...

Collaboration diagram for SCI: Systems Communication Interface:

Modules
	SCI: Byte Stuffing
	SCI byte stuffing definitions.

	SCI: Generic Command Definitions
	Generic Command Definitions.

	SCI: CRC8
	SCI CRC8 (Cyclic Redundancy Check)

	SCI: Data Link Layer
	SCI Data Link Layer.

	SCI: Data Frames
	SCI Data Frames.

	SCI: Handshaking
	SCI Handshaking Module.

Data Structures
struct	sci_frame_t
	Data buffer for outgoing frames. More...

struct	sci_frame_queue_t

Macros
#define	DEVICEID_DEFAULT 0

#define	DEVICEID_FIRST_VALID 1

#define	SCI_FRAME_SIZE 64

#define	SCI_FRAME_BUF_RX_CT 32

#define	SCI_FRAME_BUF_TX_CT 32

#define	SCI_TX_TIMEOUT_MSEC 1000

#define	SCI_FRAME_BUF_CT (SCI_FRAME_BUF_RX_CT + SCI_FRAME_BUF_TX_CT)

Typedefs
typedef uint8_t	sci_cmd_t

typedef uint32_t	sci_param_t

typedef void const *	sci_data_t

typedef uint8_t	sci_device_t

typedef status_t(*	sci_rx_cmd_fct_t) (sci_device_t deviceID, sci_frame_t *frame)
	Received command invocation function definition.

typedef status_t(*	sci_tx_cmd_fct_t) (sci_device_t deviceID, sci_frame_t *frame, sci_param_t param, sci_data_t data)
	Transmitting command function definition.

typedef status_t(*	sci_rx_cmd_cb_t) (sci_frame_t *frame)
	Callback function type for received SCI data frames.

typedef void(*	sci_error_cb_t) (status_t status)
	Callback function type for SCI error.

Enumerations
enum	StatusExplorer { ERROR_EXPLORER_UNINITIALIZED_DEVICE_ADDRESS = -200 }
	The Explorer application specific status and error return codes. More...

enum	StatusSCI { ERROR_SCI_UNKNOWN_COMMAND = -211 , ERROR_SCI_CMD_EXECUTION_FAILURE = -212 , ERROR_SCI_INVALID_CMD_CODE = -213 , ERROR_SCI_INVALID_CMD_PARAMETER = -214 , ERROR_SCI_CRC_FAILED = -215 , ERROR_SCI_BUFFER_FULL = -216 , ERROR_SCI_INVALID_START_BYTE = -217 , ERROR_SCI_INVALID_STOP_BYTE = -218 , ERROR_SCI_RX_BUFFER_FULL = -219 , ERROR_SCI_INVALID_ESCAPE_BYTE = -220 , ERROR_SCI_FRAME_TOO_SHORT = -221 , ERROR_SCI_FRAME_TOO_LONG = -222 , ERROR_SCI_TX_BUFFER_EXCEEDANCE = -223 }
	The SCI module specific status and error return codes. More...

Functions
status_t	SCI_Init (void)
	Initialize the SCI module.

void	SCI_SetRxCommandCallback (sci_rx_cmd_cb_t cb)
	Installs a callback routine for command received event.

void	SCI_RemoveRxCommandCallback (void)
	Removes the previously installed callback function.

void	SCI_SetErrorCallback (sci_error_cb_t cb)
	Installs a callback routine for the error event.

void	SCI_RemoveErrorCallback (void)
	Removes the previously installed callback function.

status_t	SCI_SendCommand (sci_device_t deviceID, sci_cmd_t cmd, sci_param_t param, sci_data_t data)
	Sends a command via the SCI module.

status_t	SCI_SetRxCommand (sci_cmd_t cmd, sci_rx_cmd_fct_t fct)
	Sets a Rx command function in the list of available commands.

status_t	SCI_SetPostRxCommand (sci_cmd_t cmd, sci_rx_cmd_fct_t rxfct, sci_rx_cmd_fct_t pfct)
	Sets Rx and post Rx command functions in the list of available commands.

status_t	SCI_SetTxCommand (sci_cmd_t cmd, sci_tx_cmd_fct_t txfct)
	Sets a Tx command function in the list of available commands.

status_t	SCI_SetRxTxCommand (sci_cmd_t cmd, sci_rx_cmd_fct_t rxfct, sci_tx_cmd_fct_t txfct)
	Sets the Rx and Tx command functions in the list of available commands.

status_t	SCI_SetCommand (sci_cmd_t cmd, sci_rx_cmd_fct_t rxfct, sci_tx_cmd_fct_t txfct, sci_rx_cmd_fct_t pfct)
	Sets the Rx and Tx command functions in the list of available commands.

status_t	SCI_UnsetCommand (sci_cmd_t cmd)
	Unsets a command from the list of available commands.

status_t	SCI_InvokeRxCommand (sci_frame_t *frame)
	Invokes the previously received user command.

Detailed Description

Systems Communication Interface.

The systems communication interface module provides a high level protocol for information exchange between several systems. Basically it is a two point interface containing a single master and a single slave device.

The protocol is a frame based hardware interface. Each data frame consists of a dedicate start and stop byte that determines the bounds of the frame. After the start byte, the first byte is considered to be the command identifier that specifies the following data. After that, an arbitrary number of data bytes can follow. In order to provide the full range per byte, the start and stop bytes are escaped and inverted by escape bytes. Thus the data bytes can have any value. Finally, the frame is finished with an 8-bit CRC value before the stop byte is send.

Apart from the CRC value, that assures the correct data integrity, there are acknowledge messages sent from the device in order to verify the correct receiving and execution of the commands within the slave system. I.e. every received command will cause either an acknowledge or an not-acknowledge with a corresponding status byte that informs the master about the error cause. On the other hand, the transmitted messages do not have to be acknowledged by the master.

Macro Definition Documentation

◆ DEVICEID_DEFAULT

#define DEVICEID_DEFAULT 0

The Device ID of the default device (usually the first device).

◆ DEVICEID_FIRST_VALID

#define DEVICEID_FIRST_VALID 1

The specific Device ID of the default device (the first device).

◆ SCI_FRAME_BUF_CT

#define SCI_FRAME_BUF_CT (SCI_FRAME_BUF_RX_CT + SCI_FRAME_BUF_TX_CT)

The total number of SCI data frames.

◆ SCI_FRAME_BUF_RX_CT

#define SCI_FRAME_BUF_RX_CT 32

The number of SCI data frames for RX.

◆ SCI_FRAME_BUF_TX_CT

#define SCI_FRAME_BUF_TX_CT 32

The number of SCI data frames for TX.

◆ SCI_FRAME_SIZE

#define SCI_FRAME_SIZE 64

Max. byte size of transmitting/receiving SCI data frames.

◆ SCI_TX_TIMEOUT_MSEC

#define SCI_TX_TIMEOUT_MSEC 1000

The timeout for a TX frame request in milliseconds.

Typedef Documentation

◆ sci_cmd_t

typedef uint8_t sci_cmd_t

The SCI command type identifier byte.

◆ sci_data_t

typedef void const* sci_data_t

The SCI data pointer type. An abstract void pointer to any data object.

◆ sci_device_t

typedef uint8_t sci_device_t

The SCI device ID type. A value of DEVICEID_DEFAULT will target the device assigned as default by the ExplorerApp. Any other value >0 up to a maximum defined by the ExplorerApp is a valid device.

◆ sci_error_cb_t

typedef void(* sci_error_cb_t) (status_t status)

Callback function type for SCI error.

Parameters

status The corresponding error code.

◆ sci_param_t

typedef uint32_t sci_param_t

The SCI parameter type. An abstract (integer) parameter to be used in the function.

◆ sci_rx_cmd_cb_t

typedef status_t(* sci_rx_cmd_cb_t) (sci_frame_t *frame)

Callback function type for received SCI data frames.

Parameters

frame Pointer to the received data frame.

Returns: Returns the status (STATUS_OK on success).

◆ sci_rx_cmd_fct_t

typedef status_t(* sci_rx_cmd_fct_t) (sci_device_t deviceID, sci_frame_t *frame)

Received command invocation function definition.

This function pointer represents a command that is invoked whenever the corresponding data frame has been received via the SCI module.

Parameters

deviceID	The ID (index) of the SPI device that should process the received frame.
frame	Pointer to the received data frame.

Returns: Returns the status (STATUS_OK on success).

◆ sci_tx_cmd_fct_t

typedef status_t(* sci_tx_cmd_fct_t) (sci_device_t deviceID, sci_frame_t *frame, sci_param_t param, sci_data_t data)

Transmitting command function definition.

This function pointer represents a command that is invoked whenever the corresponding data frame will be sent via the SCI module. It contains a pointer to the data that must serialized into the data frame structure.

Parameters

deviceID	The ID (index) of the SPI device that should process the received frame.
frame	Pointer to the data frame that will be transmitted.
param	An optional abstract parameter to be used in the command function.
data	An optional abstract pointer to the data to be serialize. The pointer van be null.

Returns: Returns the status (STATUS_OK on success).

Enumeration Type Documentation

◆ StatusExplorer

enum StatusExplorer

The Explorer application specific status and error return codes.

Enumerator
ERROR_EXPLORER_UNINITIALIZED_DEVICE_ADDRESS	Invalid/not initialized device address.

◆ StatusSCI

enum StatusSCI

The SCI module specific status and error return codes.

Enumerator
ERROR_SCI_UNKNOWN_COMMAND	Unknown/not initialized command.
ERROR_SCI_CMD_EXECUTION_FAILURE	The execution of a command returned status != STATUS_OK.
ERROR_SCI_INVALID_CMD_CODE	Invalid command code: e.g. is not tx/rx command.
ERROR_SCI_INVALID_CMD_PARAMETER	Invalid command parameters/data/decoding failed.
ERROR_SCI_CRC_FAILED	CRC failed -> frame invalid.
ERROR_SCI_BUFFER_FULL	Status for buffer full.
ERROR_SCI_INVALID_START_BYTE	Received a start byte when no one has been expected.
ERROR_SCI_INVALID_STOP_BYTE	Received a stop byte when no one has been expected.
ERROR_SCI_RX_BUFFER_FULL	Status for buffer full.
ERROR_SCI_INVALID_ESCAPE_BYTE	Received wrong escape byte.
ERROR_SCI_FRAME_TOO_SHORT	Frame too short, i.e. too less data received for the corresponding message.
ERROR_SCI_FRAME_TOO_LONG	Frame too long, i.e. too much data received for the corresponding message.
ERROR_SCI_TX_BUFFER_EXCEEDANCE	The data that was requested to be sent exceeds the maximum output data buffers size.

Function Documentation

◆ SCI_Init()

status_t SCI_Init ( void )

Initialize the SCI module.

Returns: Returns the status (STATUS_OK on success).

Indicator whether the last transmission was in new protocol mode. *‍/ static bool SCI_isNewProtocolMode = false;

/******************************************************************************* Code

◆ SCI_InvokeRxCommand()

status_t SCI_InvokeRxCommand ( sci_frame_t * frame )

Invokes the previously received user command.

Parses and executes the previously received command. To be called after Command Received Handler has been invoked.

Parameters

frame The previously received SCI frame (parameter of "RxFrameCallback") with the command code and parameter buffer.

Returns: Returns the status (STATUS_OK on success).

◆ SCI_RemoveErrorCallback()

void SCI_RemoveErrorCallback ( void )

Removes the previously installed callback function.

◆ SCI_RemoveRxCommandCallback()

void SCI_RemoveRxCommandCallback ( void )

Removes the previously installed callback function.

◆ SCI_SendCommand()

status_t SCI_SendCommand	(	sci_device_t	deviceID,
		sci_cmd_t	cmd,
		sci_param_t	param,
		sci_data_t	data
	)

Sends a command via the SCI module.

The corresponding command function will be called in order to serialize the data from into a data frame. The frame is sent afterwards.

Parameters

deviceID	deviceID to which this frame belongs to.
cmd	The command code / keyword.
param	An optional abstract parameter to be used in the command function.
data	An optional abstract pointer to the data to be serialize. The pointer can be null.

Returns: Returns the status (STATUS_OK on success).

◆ SCI_SetCommand()

status_t SCI_SetCommand	(	sci_cmd_t	cmd,
		sci_rx_cmd_fct_t	rxfct,
		sci_tx_cmd_fct_t	txfct,
		sci_rx_cmd_fct_t	pfct
	)

Sets the Rx and Tx command functions in the list of available commands.

Registers the command code to the SCI module. If already set, the corresponding Tx and Rx functions are replaced by the specified ones.

An optional post RX function can be passed that will be called after the RX command has finished. This is after the ACK has been sent and the TX line has become idle. Note that this might block the MCU for some time.

Parameters

cmd	The command code / keyword.
rxfct	The function to be called when a command is received.
txfct	The function to be called when a command is sent.
pfct	The function to be called when a command is received but after the ACK/NAK has been invoked.

Returns: Returns the status (STATUS_OK on success).

◆ SCI_SetErrorCallback()

void SCI_SetErrorCallback ( sci_error_cb_t cb )

Installs a callback routine for the error event.

Installs a callback function that will be called after an error has occurred.

Warning: The callback function is called from the interrupt service routine and should return within an appropriate time!

Parameters

cb	The callback functions to be called

◆ SCI_SetPostRxCommand()

status_t SCI_SetPostRxCommand	(	sci_cmd_t	cmd,
		sci_rx_cmd_fct_t	rxfct,
		sci_rx_cmd_fct_t	pfct
	)

Sets Rx and post Rx command functions in the list of available commands.

Registers the command code to the SCI module. If already set, the corresponding Rx function is replaced by the specified one. The Tx function will not be changed.

An optional post RX function can be passed that will be called after the RX command has finished. This is after the ACK has been sent and the TX line has become idle. Note that this might block the MCU for some time.

Parameters

cmd	The command code / keyword.
rxfct	The function to be called when a command is received.
pfct	The function to be called when a command is received but after the ACK/NAK has been invoked.

Returns: Returns the status (STATUS_OK on success).

◆ SCI_SetRxCommand()

status_t SCI_SetRxCommand	(	sci_cmd_t	cmd,
		sci_rx_cmd_fct_t	fct
	)

Sets a Rx command function in the list of available commands.

Registers the command code to the SCI module. If already set, the corresponding Rx function is replaced by the specified one. The Tx function will not be changed.

Parameters

cmd	The command code / keyword.
fct	The function to be called when a command is received.

Returns: Returns the status (STATUS_OK on success).

◆ SCI_SetRxCommandCallback()

void SCI_SetRxCommandCallback ( sci_rx_cmd_cb_t cb )

Installs a callback routine for command received event.

Installs a callback function that will be called after a command has been received successfully. This call is determined to inform about an new Rx data frame has been received and the corresponding command shall be invoked. Thus, after the callback, invoke the SCI_InvokeRxCommand() function.

If no callback is set, the commands are invoked directly from the interrupt services routine. Therefore, it is highly recommended to install a callback and invoke the commands from the main thread/task.

Warning: The callback function is called from the interrupt service routine and should return within an appropriate time!

Parameters

cb	The callback functions to be called

◆ SCI_SetRxTxCommand()

status_t SCI_SetRxTxCommand	(	sci_cmd_t	cmd,
		sci_rx_cmd_fct_t	rxfct,
		sci_tx_cmd_fct_t	txfct
	)

Sets the Rx and Tx command functions in the list of available commands.

Registers the command code to the SCI module. If already set, the corresponding Tx and Rx functions are replaced by the specified ones.

Parameters

cmd	The command code / keyword.
rxfct	The function to be called when a command is received.
txfct	The function to be called when a command is sent.

Returns: Returns the status (STATUS_OK on success).

◆ SCI_SetTxCommand()

status_t SCI_SetTxCommand	(	sci_cmd_t	cmd,
		sci_tx_cmd_fct_t	txfct
	)

Sets a Tx command function in the list of available commands.

Registers the command code to the SCIs module. If already set, the corresponding Tx function is replaced by the specified one. The Rx function will not be changed.

Parameters

cmd	The command code / keyword.
txfct	The function to be called when a command is sent.

Returns: Returns the status (STATUS_OK on success).

◆ SCI_UnsetCommand()

status_t SCI_UnsetCommand ( sci_cmd_t cmd )

Unsets a command from the list of available commands.

Removes the command code from the SCI module, i.e. it deletes the corresponding Tx and Rx functions. If not set, the function returns with ERROR_SCI_UNKNOWN_COMMAND.

Parameters

cmd	The command code / keyword.

Returns: Returns the status (STATUS_OK on success).

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ DEVICEID_DEFAULT

◆ DEVICEID_FIRST_VALID

◆ SCI_FRAME_BUF_CT

◆ SCI_FRAME_BUF_RX_CT

◆ SCI_FRAME_BUF_TX_CT

◆ SCI_FRAME_SIZE

◆ SCI_TX_TIMEOUT_MSEC

Typedef Documentation

◆ sci_cmd_t

◆ sci_data_t

◆ sci_device_t

◆ sci_error_cb_t

◆ sci_param_t

◆ sci_rx_cmd_cb_t

◆ sci_rx_cmd_fct_t

◆ sci_tx_cmd_fct_t

Enumeration Type Documentation

◆ StatusExplorer

◆ StatusSCI

Function Documentation

◆ SCI_Init()

◆ SCI_InvokeRxCommand()

◆ SCI_RemoveErrorCallback()

◆ SCI_RemoveRxCommandCallback()

◆ SCI_SendCommand()

◆ SCI_SetCommand()

◆ SCI_SetErrorCallback()

◆ SCI_SetPostRxCommand()

◆ SCI_SetRxCommand()

◆ SCI_SetRxCommandCallback()

◆ SCI_SetRxTxCommand()

◆ SCI_SetTxCommand()

◆ SCI_UnsetCommand()