LSS Master
CANopen_305

## 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. More...

## 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, uint32_t CANidLssSlave, CO_CANmodule_t *CANdevTx, uint16_t CANdevTxIdx, uint32_t CANidLssMaster)
| Initialize LSS object. More...
void | CO_LSSmaster_changeTimeout (CO_LSSmaster_t *LSSmaster, uint16_t timeout_ms)
| Change LSS master timeout. More...
void | CO_LSSmaster_initCallbackPre (CO_LSSmaster_t *LSSmaster, void *object, void(*pFunctSignal)(void *object))
| Initialize LSSmasterRx callback function. More...
CO_LSSmaster_return_t | CO_LSSmaster_switchStateSelect (CO_LSSmaster_t *LSSmaster, uint32_t timeDifference_us, CO_LSS_address_t *lssAddress)
| Request LSS switch state select. More...
CO_LSSmaster_return_t | CO_LSSmaster_switchStateDeselect (CO_LSSmaster_t *LSSmaster)
| Request LSS switch state deselect. More...
CO_LSSmaster_return_t | CO_LSSmaster_configureBitTiming (CO_LSSmaster_t *LSSmaster, uint32_t timeDifference_us, uint16_t bit)
| Request LSS configure Bit Timing. More...
CO_LSSmaster_return_t | CO_LSSmaster_configureNodeId (CO_LSSmaster_t *LSSmaster, uint32_t timeDifference_us, uint8_t nodeId)
| Request LSS configure node ID. More...
CO_LSSmaster_return_t | CO_LSSmaster_configureStore (CO_LSSmaster_t *LSSmaster, uint32_t timeDifference_us)
| Request LSS store configuration. More...
CO_LSSmaster_return_t | CO_LSSmaster_ActivateBit (CO_LSSmaster_t *LSSmaster, uint16_t switchDelay_ms)
| Request LSS activate bit timing. More...
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. More...
CO_LSSmaster_return_t | CO_LSSmaster_Inquire (CO_LSSmaster_t *LSSmaster, uint32_t timeDifference_us, CO_LSS_cs_t lssInquireCs, uint32_t *value)
| Request LSS inquire node ID or part of LSS address. More...
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. More...

## 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 CANopenSocket application, see CO_LSS_master.c / CO_LSS_master.h files.

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,
|  | uint32_t | CANidLssSlave,
|  | CO_CANmodule_t * | CANdevTx,
|  | uint16_t | CANdevTxIdx,
|  | uint32_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 CO_Default_CAN_ID_t).

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(*)(void *object) | pFunctSignal
| ) |  |

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_switchStateSelect()

CO_LSSmaster_return_t CO_LSSmaster_switchStateSelect | ( | 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_switchStateDeselect()

CO_LSSmaster_return_t CO_LSSmaster_switchStateDeselect | ( | 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,
|  | CO_LSS_cs_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_cs_t.
  [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

CO_LSSmaster_fastscan_t::scan
CO_LSSmaster_scantype_t scan[4]
Scan type for each part of the LSS address.
Definition: CO_LSSmaster.h:408
CO_LSSmaster_WAIT_SLAVE
@ CO_LSSmaster_WAIT_SLAVE
No response arrived from slave yet.
Definition: CO_LSSmaster.h:93
CO_LSSmaster_fastscan_t
Parameters for LSS fastscan CO_LSSmaster_IdentifyFastscan.
Definition: CO_LSSmaster.h:407
CO_LSS_FASTSCAN_SERIAL
@ CO_LSS_FASTSCAN_SERIAL
Serial number.
Definition: CO_LSS.h:153
CO_LSSmaster_FS_SKIP
@ CO_LSSmaster_FS_SKIP
Skip this value.
Definition: CO_LSSmaster.h:400
CO_LSS_FASTSCAN_REV
@ CO_LSS_FASTSCAN_REV
Revision number.
Definition: CO_LSS.h:152
CO_LSSmaster_FS_MATCH
@ CO_LSSmaster_FS_MATCH
Full 32 bit value is given as argument, just verify.
Definition: CO_LSSmaster.h:401
CO_LSSmaster_FS_SCAN
@ CO_LSSmaster_FS_SCAN
Do full 32 bit scan.
Definition: CO_LSSmaster.h:399
CO_LSS_FASTSCAN_PRODUCT
@ CO_LSS_FASTSCAN_PRODUCT
Product code.
Definition: CO_LSS.h:151
CO_LSSmaster_fastscan_t::match
CO_LSS_address_t match
Value to match in case of CO_LSSmaster_FS_MATCH.
Definition: CO_LSSmaster.h:409
CO_LSS_FASTSCAN_VENDOR_ID
@ CO_LSS_FASTSCAN_VENDOR_ID
Vendor ID.
Definition: CO_LSS.h:150