LSS Slave
CANopen_305

## Data Structures

struct | CO_LSSslave_t
| LSS slave object. More...

## Functions

CO_ReturnError_t | CO_LSSslave_init (CO_LSSslave_t *LSSslave, CO_LSS_address_t *lssAddress, uint16_t *pendingBitRate, uint8_t *pendingNodeID, CO_CANmodule_t *CANdevRx, uint16_t CANdevRxIdx, uint32_t CANidLssMaster, CO_CANmodule_t *CANdevTx, uint16_t CANdevTxIdx, uint32_t CANidLssSlave)
| Initialize LSS object. More...
bool_t | CO_LSSslave_process (CO_LSSslave_t *LSSslave)
| Process LSS communication. More...
static CO_LSS_state_t | CO_LSSslave_getState (CO_LSSslave_t *LSSslave)
| Get current LSS state. More...
void | CO_LSSslave_initCallbackPre (CO_LSSslave_t *LSSslave, void *object, void(*pFunctSignalPre)(void *object))
| Initialize LSSslaveRx callback function. More...
void | CO_LSSslave_initCheckBitRateCallback (CO_LSSslave_t *LSSslave, void *object, bool_t(*pFunctLSScheckBitRate)(void *object, uint16_t bitRate))
| Initialize verify bit rate callback. More...
void | CO_LSSslave_initActivateBitRateCallback (CO_LSSslave_t *LSSslave, void *object, void(*pFunctLSSactivateBitRate)(void *object, uint16_t delay))
| Initialize activate bit rate callback. More...
void | CO_LSSslave_initCfgStoreCallback (CO_LSSslave_t *LSSslave, void *object, bool_t(*pFunctLSScfgStore)(void *object, uint8_t id, uint16_t bitRate))
| Store configuration callback. More...

## Detailed Description

CANopen Layer Setting Service - slave protocol.

The slave provides 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 (bit rate and node ID)

After CAN module start, the LSS slave and NMT slave are started and then coexist alongside each other. To achieve this behaviour, the CANopen node startup process has to be controlled more detailed. Therefore, CO_LSSinit() must be invoked between CO_CANinit() and CO_CANopenInit() in the communication reset section.

Moreover, the LSS slave needs to pause the NMT slave initialization in case no valid node ID is available at start up. In that case CO_CANopenInit() skips initialization of other CANopen modules and CO_process() skips processing of other modules than LSS slave automatically.

Variables for CAN-bitrate and CANopen node-id must be initialized by application from non-volatile memory or dip switches. Pointers to them are passed to CO_LSSinit() function. Those variables represents pending values. If node-id is valid in the moment it enters CO_LSSinit(), it also becomes active node-id and the stack initialises normally. Otherwise, node-id must be configured by lss and after successful configuration stack passes reset communication autonomously.

Device with all threads can be normally initialized and running despite that node-id is not valid. Application must take care, because CANopen is not initialized. In that case CO_CANopenInit() returns error condition CO_ERROR_NODE_ID_UNCONFIGURED_LSS which must be handled properly. Status can also be checked with CO->nodeIdUnconfigured variable.

Some callback functions may be initialized by application with CO_LSSslave_initCheckBitRateCallback(), CO_LSSslave_initActivateBitRateCallback() and CO_LSSslave_initCfgStoreCallback().

## Function Documentation

## CO_LSSslave_init()

CO_ReturnError_t CO_LSSslave_init | ( | CO_LSSslave_t * | LSSslave,
|  | CO_LSS_address_t * | lssAddress,
|  | uint16_t * | pendingBitRate,
|  | uint8_t * | pendingNodeID,
|  | CO_CANmodule_t * | CANdevRx,
|  | uint16_t | CANdevRxIdx,
|  | uint32_t | CANidLssMaster,
|  | CO_CANmodule_t * | CANdevTx,
|  | uint16_t | CANdevTxIdx,
|  | uint32_t | CANidLssSlave
| ) |  |

Initialize LSS object.

Function must be called in the communication reset section.

pendingBitRate and pendingNodeID must be pointers to external variables. Both variables must be initialized on program startup (after CO_NMT_RESET_NODE) from non-volatile memory, dip switches or similar. They must not change during CO_NMT_RESET_COMMUNICATION. Both variables can be changed by CO_LSSslave_process(), depending on commands from the LSS master.

If pendingNodeID is valid (1 <= pendingNodeID <= 0x7F), then this becomes valid active nodeId just after exit of this function. In that case all other CANopen objects may be initialized and processed in run time.

If pendingNodeID is not valid (pendingNodeID == 0xFF), then only LSS slave is initialized and processed in run time. In that state pendingNodeID can be configured and after successful configuration reset communication with all CANopen object is activated automatically.

Remarks
  The LSS address needs to be unique on the network. For this, the 128 bit wide identity object (1018h) is used. Therefore, this object has to be fully initialized before passing it to this function (vendorID, product code, revisionNo, serialNo are set to 0 by default). Otherwise, if non-configured devices are present on CANopen network, LSS configuration may behave unpredictable.

Parameters

  | LSSslave | This object will be initialized.
  | lssAddress | LSS address
  [in,out] | pendingBitRate | Pending bit rate of the CAN interface
  [in,out] | pendingNodeID | Pending node ID or 0xFF - invalid
  | CANdevRx | CAN device for LSS slave reception.
  | CANdevRxIdx | Index of receive buffer in the above CAN device.
  | CANidLssMaster | COB ID for reception.
  | CANdevTx | CAN device for LSS slave transmission.
  | CANdevTxIdx | Index of transmit buffer in the above CAN device.
  | CANidLssSlave | COB ID for transmission.

Returns
  CO_ReturnError_t: CO_ERROR_NO or CO_ERROR_ILLEGAL_ARGUMENT.

## CO_LSSslave_process()

bool_t CO_LSSslave_process | ( | CO_LSSslave_t * | LSSslave | ) |

Process LSS communication.

Object is partially pre-processed after LSS message received. Further processing is inside this function.

In case that Node-Id is unconfigured, then this function may request CANopen communication reset. This happens, when valid node-id is configured by LSS master.

Parameters

  LSSslave | This object.

Returns
  True, if CO_NMT_RESET_COMMUNICATION is requested

## CO_LSSslave_getState()

static CO_LSS_state_t CO_LSSslave_getState | ( | CO_LSSslave_t * | LSSslave | ) |

inlinestatic

Get current LSS state.

Parameters

  LSSslave | This object.

Returns
  CO_LSS_state_t

## CO_LSSslave_initCallbackPre()

void CO_LSSslave_initCallbackPre | ( | CO_LSSslave_t * | LSSslave,
|  | void * | object,
|  | void(*)(void *object) | pFunctSignalPre
| ) |  |

Initialize LSSslaveRx 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

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

## CO_LSSslave_initCheckBitRateCallback()

void CO_LSSslave_initCheckBitRateCallback | ( | CO_LSSslave_t * | LSSslave,
|  | void * | object,
|  | bool_t(*)(void *object, uint16_t bitRate) | pFunctLSScheckBitRate
| ) |  |

Initialize verify bit rate callback.

Function initializes callback function, which is called when "config bit timing parameters" is used. The callback function needs to check if the new bit rate is supported by the CANopen device. Callback returns "true" if supported. When no callback is set the LSS slave will no-ack the request, indicating to the master that bit rate change is not supported.

Parameters

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

## CO_LSSslave_initActivateBitRateCallback()

void CO_LSSslave_initActivateBitRateCallback | ( | CO_LSSslave_t * | LSSslave,
|  | void * | object,
|  | void(*)(void *object, uint16_t delay) | pFunctLSSactivateBitRate
| ) |  |

Initialize activate bit rate callback.

Function initializes callback function, which is called when "activate bit timing parameters" is used. The callback function gives the user an event to allow setting a timer or do calculations based on the exact time the request arrived. According to DSP 305 6.4.4, the delay has to be applied once before and once after switching bit rates. During this time, a device mustn't send any messages.

Parameters

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

## CO_LSSslave_initCfgStoreCallback()

void CO_LSSslave_initCfgStoreCallback | ( | CO_LSSslave_t * | LSSslave,
|  | void * | object,
|  | bool_t(*)(void *object, uint8_t id, uint16_t bitRate) | pFunctLSScfgStore
| ) |  |

Store configuration callback.

Function initializes callback function, which is called when "store configuration" is used. The callback function gives the user an event to store the corresponding node id and bit rate to NVM. Those values have to be supplied to the init function as "persistent values" after reset. If callback returns "true", success is send to the LSS master. When no callback is set the LSS slave will no-ack the request, indicating to the master that storing is not supported.

Parameters

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