CANopen Layer Setting Service - master protocol. More...

Collaboration diagram for LSS Master:

Data Structures
struct	CO_LSSmaster_t
	LSS master object. More...

struct	CO_LSSmaster_fastscan_t
	Parameters for LSS fastscan CO_LSSmaster_IdentifyFastscan. More...

Macros
#define	CO_LSSmaster_DEFAULT_TIMEOUT 1000U /* ms */
	Default timeout for LSS slave in ms.

Enumerations
enum	CO_LSSmaster_return_t { CO_LSSmaster_SCAN_FINISHED = 2 , CO_LSSmaster_WAIT_SLAVE = 1 , CO_LSSmaster_OK = 0 , CO_LSSmaster_TIMEOUT = -1 , CO_LSSmaster_ILLEGAL_ARGUMENT = -2 , CO_LSSmaster_INVALID_STATE = -3 , CO_LSSmaster_SCAN_NOACK = -4 , CO_LSSmaster_SCAN_FAILED = -5 , CO_LSSmaster_OK_ILLEGAL_ARGUMENT = -101 , CO_LSSmaster_OK_MANUFACTURER = -102 }
	Return values of LSS master functions. More...

enum	CO_LSSmaster_scantype_t { CO_LSSmaster_FS_SCAN = 0 , CO_LSSmaster_FS_SKIP = 1 , CO_LSSmaster_FS_MATCH = 2 }
	Scan type for CO_LSSmaster_fastscan_t scan. More...

Functions
CO_ReturnError_t	CO_LSSmaster_init (CO_LSSmaster_t LSSmaster, uint16_t timeout_ms, CO_CANmodule_t CANdevRx, uint16_t CANdevRxIdx, uint16_t CANidLssSlave, CO_CANmodule_t *CANdevTx, uint16_t CANdevTxIdx, uint16_t CANidLssMaster)
	Initialize LSS object.

void	CO_LSSmaster_changeTimeout (CO_LSSmaster_t *LSSmaster, uint16_t timeout_ms)
	Change LSS master timeout.

void	CO_LSSmaster_initCallbackPre (CO_LSSmaster_t LSSmaster, void object, void(pFunctSignal)(void object))
	Initialize LSSmasterRx callback function.

CO_LSSmaster_return_t	CO_LSSmaster_swStateSelect (CO_LSSmaster_t LSSmaster, uint32_t timeDifference_us, CO_LSS_address_t lssAddress)
	Request LSS switch state select.

CO_LSSmaster_return_t	CO_LSSmaster_swStateDeselect (CO_LSSmaster_t *LSSmaster)
	Request LSS switch state deselect.

CO_LSSmaster_return_t	CO_LSSmaster_configureBitTiming (CO_LSSmaster_t *LSSmaster, uint32_t timeDifference_us, uint16_t bit)
	Request LSS configure Bit Timing.

CO_LSSmaster_return_t	CO_LSSmaster_configureNodeId (CO_LSSmaster_t *LSSmaster, uint32_t timeDifference_us, uint8_t nodeId)
	Request LSS configure node ID.

CO_LSSmaster_return_t	CO_LSSmaster_configureStore (CO_LSSmaster_t *LSSmaster, uint32_t timeDifference_us)
	Request LSS store configuration.

CO_LSSmaster_return_t	CO_LSSmaster_ActivateBit (CO_LSSmaster_t *LSSmaster, uint16_t switchDelay_ms)
	Request LSS activate bit timing.

CO_LSSmaster_return_t	CO_LSSmaster_InquireLssAddress (CO_LSSmaster_t LSSmaster, uint32_t timeDifference_us, CO_LSS_address_t lssAddress)
	Request LSS inquire LSS address.

CO_LSSmaster_return_t	CO_LSSmaster_Inquire (CO_LSSmaster_t LSSmaster, uint32_t timeDifference_us, uint8_t lssInquireCs, uint32_t value)
	Request LSS inquire node ID or part of LSS address.

CO_LSSmaster_return_t	CO_LSSmaster_IdentifyFastscan (CO_LSSmaster_t LSSmaster, uint32_t timeDifference_us, CO_LSSmaster_fastscan_t fastscan)
	Select a node by LSS identify fastscan.

Detailed Description

CANopen Layer Setting Service - master protocol.

The client/master can use the following services

node selection via LSS address
node selection via LSS fastscan
Inquire LSS address of currently selected node
Inquire node ID
Configure bit timing
Configure node ID
Activate bit timing parameters
Store configuration

The LSS master is initalized during the CANopenNode initialization process. Except for enabling the LSS master in the configurator, no further run-time configuration is needed for basic operation. The LSS master does basic checking of commands and command sequence.

Usage

Usage of the CANopen LSS master is demonstrated in file 309/CO_gateway_ascii.c

It essentially is always as following:

select node(s)
call master command(s)
evaluate return value
deselect nodes

All commands need to be run cyclically, e.g. like this

interval = 0;
do {
    ret = CO_LSSmaster_InquireNodeId(LSSmaster, interval, &outval);
 
    interval = 1;
    ms sleep(interval);
} while (ret == CO_LSSmaster_WAIT_SLAVE);

A more advanced implementation can make use of the callback function to shorten waiting times.

Macro Definition Documentation

◆ CO_LSSmaster_DEFAULT_TIMEOUT

#define CO_LSSmaster_DEFAULT_TIMEOUT 1000U /* ms */

Default timeout for LSS slave in ms.

This is the same as for SDO. For more info about LSS timeout see CO_LSSmaster_changeTimeout()

Enumeration Type Documentation

◆ CO_LSSmaster_return_t

enum CO_LSSmaster_return_t

Return values of LSS master functions.

Enumerator
CO_LSSmaster_SCAN_FINISHED	Scanning finished successful.
CO_LSSmaster_WAIT_SLAVE	No response arrived from slave yet.
CO_LSSmaster_OK	Success, end of communication.
CO_LSSmaster_TIMEOUT	No reply received.
CO_LSSmaster_ILLEGAL_ARGUMENT	Invalid argument.
CO_LSSmaster_INVALID_STATE	State machine not ready or already processing a request.
CO_LSSmaster_SCAN_NOACK	No node found that matches scan request.
CO_LSSmaster_SCAN_FAILED	An error occurred while scanning. Try again
CO_LSSmaster_OK_ILLEGAL_ARGUMENT	LSS success, node rejected argument because of non-supported value.
CO_LSSmaster_OK_MANUFACTURER	LSS success, node rejected argument with manufacturer error code.

◆ CO_LSSmaster_scantype_t

enum CO_LSSmaster_scantype_t

Scan type for CO_LSSmaster_fastscan_t scan.

Enumerator
CO_LSSmaster_FS_SCAN	Do full 32 bit scan.
CO_LSSmaster_FS_SKIP	Skip this value.
CO_LSSmaster_FS_MATCH	Full 32 bit value is given as argument, just verify.

Function Documentation

◆ CO_LSSmaster_init()

CO_ReturnError_t CO_LSSmaster_init	(	CO_LSSmaster_t *	LSSmaster,
		uint16_t	timeout_ms,
		CO_CANmodule_t *	CANdevRx,
		uint16_t	CANdevRxIdx,
		uint16_t	CANidLssSlave,
		CO_CANmodule_t *	CANdevTx,
		uint16_t	CANdevTxIdx,
		uint16_t	CANidLssMaster )

Initialize LSS object.

Function must be called in the communication reset section.

Parameters

LSSmaster	This object will be initialized.
timeout_ms	slave response timeout in ms, for more detail see CO_LSSmaster_changeTimeout()
CANdevRx	CAN device for LSS master reception.
CANdevRxIdx	Index of receive buffer in the above CAN device.
CANidLssSlave	COB ID for reception.
CANdevTx	CAN device for LSS master transmission.
CANdevTxIdx	Index of transmit buffer in the above CAN device.
CANidLssMaster	COB ID for transmission.

Returns: CO_ReturnError_t: CO_ERROR_NO or CO_ERROR_ILLEGAL_ARGUMENT.

◆ CO_LSSmaster_changeTimeout()

void CO_LSSmaster_changeTimeout	(	CO_LSSmaster_t *	LSSmaster,
		uint16_t	timeout_ms )

Change LSS master timeout.

On LSS, a "negative ack" is signaled by the slave not answering. Because of that, a low timeout value can significantly increase protocol speed in some cases (e.g. fastscan). However, as soon as there is activity on the bus, LSS messages can be delayed because of their low CAN network priority (see Default CANopen identifiers).

Remarks: Be aware that a "late response" will seriously mess up LSS, so this value must be selected "as high as necessary and as low as possible". CiA does neither specify nor recommend a value.; This timeout is per-transfer. If a command internally needs multiple transfers to complete, this timeout is applied on each transfer.

Parameters

LSSmaster	This object.
timeout_ms	timeout value in ms

◆ CO_LSSmaster_initCallbackPre()

void CO_LSSmaster_initCallbackPre	(	CO_LSSmaster_t *	LSSmaster,
		void *	object,
		void(*	pFunctSignal )(void *object) )

Initialize LSSmasterRx callback function.

Function initializes optional callback function, which should immediately start further LSS processing. Callback is called after LSS message is received from the CAN bus. It should signal the RTOS to resume corresponding task.

Parameters

LSSmaster	This object.
object	Pointer to object, which will be passed to pFunctSignal(). Can be NULL
pFunctSignal	Pointer to the callback function. Not called if NULL.

◆ CO_LSSmaster_swStateSelect()

CO_LSSmaster_return_t CO_LSSmaster_swStateSelect	(	CO_LSSmaster_t *	LSSmaster,
		uint32_t	timeDifference_us,
		CO_LSS_address_t *	lssAddress )

Request LSS switch state select.

This function can select one specific or all nodes.

Function must be called cyclically until it returns != CO_LSSmaster_WAIT_SLAVE Function is non-blocking.

Remarks: Only one selection can be active at any time.

Parameters

LSSmaster	This object.
timeDifference_us	Time difference from previous function call in [microseconds]. Zero when request is started.
lssAddress	LSS target address. If NULL, all nodes are selected

Returns: CO_LSSmaster_ILLEGAL_ARGUMENT, CO_LSSmaster_INVALID_STATE, CO_LSSmaster_WAIT_SLAVE, CO_LSSmaster_OK, CO_LSSmaster_TIMEOUT

◆ CO_LSSmaster_swStateDeselect()

CO_LSSmaster_return_t CO_LSSmaster_swStateDeselect ( CO_LSSmaster_t * LSSmaster )

Request LSS switch state deselect.

This function deselects all nodes, so it doesn't matter if a specific node is selected.

This function also resets the LSS master state machine to a clean state

Parameters

LSSmaster This object.

Returns: CO_LSSmaster_ILLEGAL_ARGUMENT, CO_LSSmaster_INVALID_STATE, CO_LSSmaster_OK

◆ CO_LSSmaster_configureBitTiming()

CO_LSSmaster_return_t CO_LSSmaster_configureBitTiming	(	CO_LSSmaster_t *	LSSmaster,
		uint32_t	timeDifference_us,
		uint16_t	bit )

Request LSS configure Bit Timing.

The new bit rate is set as new pending value.

This function needs one specific node to be selected.

Function must be called cyclically until it returns != CO_LSSmaster_WAIT_SLAVE. Function is non-blocking.

Parameters

LSSmaster	This object.
timeDifference_us	Time difference from previous function call in [microseconds]. Zero when request is started.
bit	new bit rate

Returns: CO_LSSmaster_ILLEGAL_ARGUMENT, CO_LSSmaster_INVALID_STATE, CO_LSSmaster_WAIT_SLAVE, CO_LSSmaster_OK, CO_LSSmaster_TIMEOUT, CO_LSSmaster_OK_MANUFACTURER, CO_LSSmaster_OK_ILLEGAL_ARGUMENT

◆ CO_LSSmaster_configureNodeId()

CO_LSSmaster_return_t CO_LSSmaster_configureNodeId	(	CO_LSSmaster_t *	LSSmaster,
		uint32_t	timeDifference_us,
		uint8_t	nodeId )

Request LSS configure node ID.

The new node id is set as new pending node ID.

This function needs one specific node to be selected.

Function must be called cyclically until it returns != CO_LSSmaster_WAIT_SLAVE. Function is non-blocking.

Parameters

LSSmaster	This object.
timeDifference_us	Time difference from previous function call in [microseconds]. Zero when request is started.
nodeId	new node ID. Special value CO_LSS_NODE_ID_ASSIGNMENT can be used to invalidate node ID.

Returns: CO_LSSmaster_ILLEGAL_ARGUMENT, CO_LSSmaster_INVALID_STATE, CO_LSSmaster_WAIT_SLAVE, CO_LSSmaster_OK, CO_LSSmaster_TIMEOUT, CO_LSSmaster_OK_MANUFACTURER, CO_LSSmaster_OK_ILLEGAL_ARGUMENT

◆ CO_LSSmaster_configureStore()

CO_LSSmaster_return_t CO_LSSmaster_configureStore	(	CO_LSSmaster_t *	LSSmaster,
		uint32_t	timeDifference_us )

Request LSS store configuration.

The current "pending" values for bit rate and node ID in LSS slave are stored as "permanent" values.

This function needs one specific node to be selected.

Function must be called cyclically until it returns != CO_LSSmaster_WAIT_SLAVE. Function is non-blocking.

Parameters

LSSmaster	This object.
timeDifference_us	Time difference from previous function call in [microseconds]. Zero when request is started.

Returns: CO_LSSmaster_ILLEGAL_ARGUMENT, CO_LSSmaster_INVALID_STATE, CO_LSSmaster_WAIT_SLAVE, CO_LSSmaster_OK, CO_LSSmaster_TIMEOUT, CO_LSSmaster_OK_MANUFACTURER, CO_LSSmaster_OK_ILLEGAL_ARGUMENT

◆ CO_LSSmaster_ActivateBit()

CO_LSSmaster_return_t CO_LSSmaster_ActivateBit	(	CO_LSSmaster_t *	LSSmaster,
		uint16_t	switchDelay_ms )

Request LSS activate bit timing.

The current "pending" bit rate in LSS slave is applied.

Be aware that changing the bit rate is a critical step for the network. A failure will render the network unusable! Therefore, this function only should be called if the following conditions are met:

all nodes support changing bit timing
new bit timing is successfully set as "pending" in all nodes
all nodes have to activate the new bit timing roughly at the same time. Therefore this function needs all nodes to be selected.

Parameters

LSSmaster	This object.
switchDelay_ms	delay that is applied by the slave once before and once after switching in ms.

Returns: CO_LSSmaster_ILLEGAL_ARGUMENT, CO_LSSmaster_INVALID_STATE, CO_LSSmaster_OK

◆ CO_LSSmaster_InquireLssAddress()

CO_LSSmaster_return_t CO_LSSmaster_InquireLssAddress	(	CO_LSSmaster_t *	LSSmaster,
		uint32_t	timeDifference_us,
		CO_LSS_address_t *	lssAddress )

Request LSS inquire LSS address.

The LSS address value is read from the node. This is useful when the node was selected by fastscan.

This function needs one specific node to be selected.

Function must be called cyclically until it returns != CO_LSSmaster_WAIT_SLAVE. Function is non-blocking.

Parameters

	LSSmaster	This object.
	timeDifference_us	Time difference from previous function call in [microseconds]. Zero when request is started.
[out]	lssAddress	read result when function returns successfully

Returns: CO_LSSmaster_ILLEGAL_ARGUMENT, CO_LSSmaster_INVALID_STATE, CO_LSSmaster_WAIT_SLAVE, CO_LSSmaster_OK, CO_LSSmaster_TIMEOUT

◆ CO_LSSmaster_Inquire()

CO_LSSmaster_return_t CO_LSSmaster_Inquire	(	CO_LSSmaster_t *	LSSmaster,
		uint32_t	timeDifference_us,
		uint8_t	lssInquireCs,
		uint32_t *	value )

Request LSS inquire node ID or part of LSS address.

The node-ID, identity vendor-ID, product-code, revision-number or serial-number value is read from the node.

This function needs one specific node to be selected.

Function must be called cyclically until it returns != CO_LSSmaster_WAIT_SLAVE. Function is non-blocking.

Parameters

	LSSmaster	This object.
	timeDifference_us	Time difference from previous function call in [microseconds]. Zero when request is started.
	lssInquireCs	One of CO_LSS_INQUIRE_xx commands from CO_LSS command specifiers.
[out]	value	read result when function returns successfully

Returns: CO_LSSmaster_ILLEGAL_ARGUMENT, CO_LSSmaster_INVALID_STATE, CO_LSSmaster_WAIT_SLAVE, CO_LSSmaster_OK, CO_LSSmaster_TIMEOUT

◆ CO_LSSmaster_IdentifyFastscan()

CO_LSSmaster_return_t CO_LSSmaster_IdentifyFastscan	(	CO_LSSmaster_t *	LSSmaster,
		uint32_t	timeDifference_us,
		CO_LSSmaster_fastscan_t *	fastscan )

Select a node by LSS identify fastscan.

This initiates searching for a unconfigured node by the means of LSS fastscan mechanism. When this function is finished

a (more or less) arbitrary node is selected and ready for node ID assingment
no node is selected because the given criteria do not match a node
no node is selected because all nodes are already configured

There are multiple ways to scan for a node. Depending on those, the scan will take different amounts of time:

full scan
partial scan
verification

Most of the time, those are used in combination. Consider the following example:

Vendor ID and product code are known
Software version doesn't matter
Serial number is unknown

In this case, the fastscan structure should be set up as following:

CO_LSSmaster_fastscan_t fastscan;
fastscan.scan[CO_LSS_FASTSCAN_VENDOR_ID] = CO_LSSmaster_FS_MATCH;
fastscan.match.vendorID = YOUR_VENDOR_ID;
fastscan.scan[CO_LSS_FASTSCAN_PRODUCT] = CO_LSSmaster_FS_MATCH;
fastscan.match.productCode = YOUR_PRODUCT_CODE;
fastscan.scan[CO_LSS_FASTSCAN_REV] = CO_LSSmaster_FS_SKIP;
fastscan.scan[CO_LSS_FASTSCAN_SERIAL] = CO_LSSmaster_FS_SCAN;

This example will take 2 scan cyles for verifying vendor ID and product code and 33 scan cycles to find the serial number.

For scanning, the following limitations apply:

No more than two values can be skipped
Vendor ID cannot be skipped

Remarks: When doing partial scans, it is in the responsibility of the user that the LSS address is unique.

This function needs that no node is selected when starting the scan process.

Function must be called cyclically until it returns != CO_LSSmaster_WAIT_SLAVE. Function is non-blocking.

Parameters

LSSmaster	This object.
timeDifference_us	Time difference from previous function call in [microseconds]. Zero when request is started.
fastscan	struct according to CO_LSSmaster_fastscan_t.

Returns: CO_LSSmaster_ILLEGAL_ARGUMENT, CO_LSSmaster_INVALID_STATE, CO_LSSmaster_WAIT_SLAVE, CO_LSSmaster_SCAN_FINISHED, CO_LSSmaster_SCAN_NOACK, CO_LSSmaster_SCAN_FAILED

Data Structures

Macros

Enumerations

Functions

Detailed Description

Usage

Macro Definition Documentation

◆ CO_LSSmaster_DEFAULT_TIMEOUT

Enumeration Type Documentation

◆ CO_LSSmaster_return_t

◆ CO_LSSmaster_scantype_t

Function Documentation

◆ CO_LSSmaster_init()

◆ CO_LSSmaster_changeTimeout()

◆ CO_LSSmaster_initCallbackPre()

◆ CO_LSSmaster_swStateSelect()

◆ CO_LSSmaster_swStateDeselect()

◆ CO_LSSmaster_configureBitTiming()

◆ CO_LSSmaster_configureNodeId()

◆ CO_LSSmaster_configureStore()

◆ CO_LSSmaster_ActivateBit()

◆ CO_LSSmaster_InquireLssAddress()

◆ CO_LSSmaster_Inquire()

◆ CO_LSSmaster_IdentifyFastscan()