AGHAF  4.5.1
Annecy electronique Generic Hardware Access Framework
LIN

API to use LIN on exxotest devices. More...

typedef void * AGHAF_LIN
 handle on a LIN bus
 
typedef void(* AGHAF_LIN_onMessageTx) (uint64_t timestamp, uint8_t fid, uint8_t datalen, uint8_t const *data, void *userContext)
 callback function called when a message is transmitted on a LIN bus More...
 
typedef void(* AGHAF_LIN_onMessageRx) (uint64_t timestamp, uint8_t fid, uint8_t datalen, uint8_t const *data, void *userContext)
 callback function called when a message is received on a LIN bus More...
 
typedef void(* AGHAF_LIN_onError) (uint64_t timestamp, AGHAF_LIN_Error error, void *userContext)
 callback called when an error happens on a bus LIN More...
 
typedef void(* AGHAF_LIN_onBusStateChanged) (uint64_t timestamp, AGHAF_LIN_BusState state, void *userContext)
 callback called when a wake up is received More...
 
typedef void(* AGHAF_LIN_onWakeUpSent) (uint64_t timestamp, void *userContext)
 callback called when a wake has been sent More...
 
void AGHAF_LIN_setOnMessageTxCallback (AGHAF_LIN lin, AGHAF_LIN_onMessageTx callback, void *userContext)
 Set the callback called on tx event. More...
 
void AGHAF_LIN_setOnMessageRxCallback (AGHAF_LIN lin, AGHAF_LIN_onMessageRx callback, void *userContext)
 Set the callback called on rx event. More...
 
void AGHAF_LIN_setOnErrorCallback (AGHAF_LIN lin, AGHAF_LIN_onError callback, void *userContext)
 Set the callback called on an error event. More...
 
void AGHAF_LIN_setOnBusStateChangedCallback (AGHAF_LIN lin, AGHAF_LIN_onBusStateChanged callback, void *userContext)
 Set the callback called on a bus state changed event. More...
 
void AGHAF_LIN_setOnWakeUpSentCallback (AGHAF_LIN lin, AGHAF_LIN_onWakeUpSent callback, void *userContext)
 Set the callback called on a wake up sent event. More...
 
AGHAF_LIN AGHAF_LIN_get (AGHAF_Device device, uint8_t index)
 Return the LIN bus at the index specified. More...
 
uint8_t AGHAF_LIN_getIndex (AGHAF_LIN lin)
 Return the index from a LIN. More...
 
uint8_t AGHAF_LIN_getCount (AGHAF_Device device)
 Return the number of LINs available on a device. More...
 
AGHAF_Status AGHAF_LIN_activate (AGHAF_LIN lin)
 Start the communication with the LIN. More...
 
AGHAF_Status AGHAF_LIN_deactivate (AGHAF_LIN lin)
 Stop the communication with the LIN. More...
 
AGHAF_Status AGHAF_LIN_isActivated (AGHAF_LIN lin, AGHAF_BOOL *isActivated)
 Allow to know if the communication on the LIN is started or not. More...
 
AGHAF_Status AGHAF_LIN_getParam (AGHAF_LIN lin, AGHAF_LIN_Param param, uint32_t *value)
 Get a parameter from a LIN. More...
 
AGHAF_Status AGHAF_LIN_setParam (AGHAF_LIN lin, AGHAF_LIN_Param param, uint32_t value)
 Set a parameter from a LIN. More...
 
AGHAF_Status AGHAF_LIN_sendHeader (AGHAF_LIN lin, uint8_t fid)
 Write header on the LIN. More...
 
AGHAF_Status AGHAF_LIN_updateFrame (AGHAF_LIN lin, uint8_t fid, uint8_t dataLen, uint8_t const *data)
 Update the datas associated to a frame identifier. More...
 
AGHAF_Status AGHAF_LIN_configureFrame (AGHAF_LIN lin, uint8_t fid, AGHAF_LIN_FrameKind kind, uint8_t publishFlags, uint8_t dataLen, uint8_t const *initialData)
 Configure the frame associated with the frame identifier. More...
 
AGHAF_Status AGHAF_LIN_wakeUp (AGHAF_LIN lin)
 Send a wake up request on the bus LIN. More...
 
AGHAF_Status AGHAF_LIN_SCHEDULE_clearDatas (AGHAF_LIN lin, uint8_t scheduleIndex)
 Clear the datas associated to a schedule index. More...
 
AGHAF_Status AGHAF_LIN_SCHEDULE_addUnconditional (AGHAF_LIN lin, uint8_t scheduleIndex, uint8_t fid, uint8_t timeBaseCount)
 Add an unconditionale frame in a schedule. More...
 
AGHAF_Status AGHAF_LIN_SCHEDULE_addSporadic (AGHAF_LIN lin, uint8_t scheduleIndex, uint8_t timeBaseCount, uint8_t nbSpo, uint8_t *idList)
 Add a sporadic frame in a schedule. More...
 
AGHAF_Status AGHAF_LIN_SCHEDULE_addEventTriggered (AGHAF_LIN lin, uint8_t scheduleIndex, uint8_t timeBaseCount, uint8_t eventTriggerId, uint8_t collisionTable)
 Add an event triggered in a schedule. More...
 
AGHAF_Status AGHAF_LIN_SCHEDULE_addWakeUp (AGHAF_LIN lin, uint8_t scheduleIndex, uint8_t timeBaseCount)
 Add a wake in a schedule. More...
 
AGHAF_Status AGHAF_LIN_SCHEDULE_configure (AGHAF_LIN lin, uint8_t scheduleIndex, AGHAF_LIN_ScheduleKind kind)
 AGHAF_LIN_SCHEDULE_configure. More...
 
AGHAF_Status AGHAF_LIN_SCHEDULE_start (AGHAF_LIN lin, uint8_t scheduleIndex)
 Start a schedule. More...
 
AGHAF_Status AGHAF_LIN_SCHEDULE_stop (AGHAF_LIN lin)
 Stop the schedule currently executed on the LIN. More...
 
AGHAF_Status AGHAF_LIN_SCHEDULE_getCount (AGHAF_LIN lin, uint8_t *count)
 Number of LIN schedule that can be configured. More...
 

Detailed Description

API to use LIN on exxotest devices.

LIN

Introduction

The LIN protocol is described in ISO 17987. It allows to make low cost devices with a master/slave way of working. The master initiates the communication through the emission of a header. Then the slaves react according to the configuration.

Configurations

Three frame configurations are possible for master and slave:

If the master is in "publish" for a frame identifier, then it sends the header and the datas associated. The slaves must be configured in "subscribe" if they want to receive the datas or "ignore" if they are not interested in the frame identifier.

If the master is in "subscribe" for a frame identifier, then it sends the header and waits for the datas coming from slaves. The slaves must be configured in "publish" to send the datas associated to the frame identifier ("ignore" if they don't answer to this frame identifier).

If the master is in "ignore" for a frame identifier, then it sends the header but does read the datas answered. The slaves exchange data, one con be in "subscribe" and the other in "publish".

The datas contained in a frame can be updated with AGHAF_LIN_updateFrame during the work.

Schedules

LIN has a deterministic behavior. In this aim, schedules are provided to give a list of events to execute. After each event, the schedule waits for timeBaseCount * AGHAF_LIN_PARAM_TIME_BASE before executing the next event.

Three kind of events are possible:

Unconditional is a frame identifier with a time that will be waited before the next event in the schedule table.

Sporadic consists in a list of frame identifier. If none has changed, nothing is emitted. If one has changed, then it is emitted. If two ids have changed in the list, only one will be sent. The other will be sent at the next sporadic execution if no others with higher priority has changed. The priority of the identifier is the order in the list provided.

Event triggered is an id on which can happen conflicts due to simultaneous answers from slaves. A second schedule table must be programmed to solve the conflict: sending differents ids for each slave. The second schedule table is called the collision table, it does not need to be started only configured. The kind of the collision table must be once. In deed, it will be executed only once when a conflict happens.

Bus State

LIN has a wake up function. The callback onBusStateChanged is called when the transceiver LIN from the device wakes up. It means, the callback is not called if a wake up is transmitted while the transceiver is working. The callback onBusStateChanged is called if the transceiver goes into sleep mode too. Wake up re-transmission can be configured with AGHAF_LIN_PARAM_WAKEUP_COUNT and AGHAF_LIN_PARAM_WAKEUP_DELAY.

Usage Example

Call order and priority

Device is in "init" state at startup.

The following section describes state management:


Symbol Description
Forbidden
Authorized
Next status


Function Config Active
AGHAF_LIN_setOnMessageTxCallback
AGHAF_LIN_setOnMessageRxCallback
AGHAF_LIN_setOnErrorCallback
AGHAF_LIN_setOnBusStateChangedCallback
AGHAF_LIN_get
AGHAF_LIN_getIndex
AGHAF_LIN_getCount
AGHAF_LIN_getParam
AGHAF_LIN_setParam
AGHAF_LIN_activate
AGHAF_LIN_deactivate
AGHAF_LIN_isActivated
AGHAF_LIN_sendHeader
AGHAF_LIN_updateFrame
AGHAF_LIN_configureFrame
AGHAF_LIN_wakeUp
AGHAF_LIN_SCHEDULE_clearDatas
AGHAF_LIN_SCHEDULE_addUnconditional
AGHAF_LIN_SCHEDULE_addSporadic
AGHAF_LIN_SCHEDULE_addEventTriggered
AGHAF_LIN_SCHEDULE_addWakeUp
AGHAF_LIN_SCHEDULE_configure
AGHAF_LIN_SCHEDULE_start
AGHAF_LIN_SCHEDULE_stop
AGHAF_LIN_SCHEDULE_getCount

Typedef Documentation

◆ AGHAF_LIN_onBusStateChanged

typedef void(* AGHAF_LIN_onBusStateChanged) (uint64_t timestamp, AGHAF_LIN_BusState state, void *userContext)

callback called when a wake up is received

Parameters
timestamptimestamp of the event
statenew state from the LIN: AGHAF_LIN_BusState
userContextcontext given when setting the callabck in the system

◆ AGHAF_LIN_onError

typedef void(* AGHAF_LIN_onError) (uint64_t timestamp, AGHAF_LIN_Error error, void *userContext)

callback called when an error happens on a bus LIN

Parameters
timestamptimestamp of the event
errorvalue of the error
userContextcontext given when setting the callback in the system

◆ AGHAF_LIN_onMessageRx

typedef void(* AGHAF_LIN_onMessageRx) (uint64_t timestamp, uint8_t fid, uint8_t datalen, uint8_t const *data, void *userContext)

callback function called when a message is received on a LIN bus

Parameters
timestamptimestamp of the event
fidframe identifier received
datalenlength of the datas received
datadatas received
userContextcontext given when setting the callabck in the system

◆ AGHAF_LIN_onMessageTx

typedef void(* AGHAF_LIN_onMessageTx) (uint64_t timestamp, uint8_t fid, uint8_t datalen, uint8_t const *data, void *userContext)

callback function called when a message is transmitted on a LIN bus

Warning
data is nullptr by default. It contains data sent according to AGHAF_LIN_PARAM_EVENT value.
Parameters
timestamptimestamp of the event
fidframe identifier transmitted
datalenlength of the datas transmitted
datadatas transmitted
userContextcontext given when setting the callabck in the system

◆ AGHAF_LIN_onWakeUpSent

typedef void(* AGHAF_LIN_onWakeUpSent) (uint64_t timestamp, void *userContext)

callback called when a wake has been sent

Parameters
timestamptimestamp of the event
userContextcontext given when setting the callabck in the system

Function Documentation

◆ AGHAF_LIN_activate()

AGHAF_Status AGHAF_LIN_activate ( AGHAF_LIN  lin)

Start the communication with the LIN.

Parameters
linhandle on the LIN
Returns
status request information
Examples
LIN_EventTriggered/main.cpp, LIN_Sporadic/main.cpp, and LIN_UnconditionalFrame/main.cpp.

◆ AGHAF_LIN_configureFrame()

AGHAF_Status AGHAF_LIN_configureFrame ( AGHAF_LIN  lin,
uint8_t  fid,
AGHAF_LIN_FrameKind  kind,
uint8_t  publishFlags,
uint8_t  dataLen,
uint8_t const *  initialData 
)

Configure the frame associated with the frame identifier.

Note
must be used before LIN activation
Parameters
linhandle on the LIN
fidframe identifier
kindKind of configuration: Ignore, Publish or Subscribe
publishFlagsflags that can be used when kind set to AGHAF_LIN_FRAME_KIND_PUBLISH : AGHAF_LIN_PUBLISH_FLAGS
dataLenlength of the datas
initialDatainitial data of the frame
Returns
status request information
Examples
LIN_EventTriggered/main.cpp, LIN_Sporadic/main.cpp, and LIN_UnconditionalFrame/main.cpp.

◆ AGHAF_LIN_deactivate()

AGHAF_Status AGHAF_LIN_deactivate ( AGHAF_LIN  lin)

Stop the communication with the LIN.

Parameters
linhandle on the LIN
Returns
status request information
Examples
LIN_EventTriggered/main.cpp, LIN_Sporadic/main.cpp, and LIN_UnconditionalFrame/main.cpp.

◆ AGHAF_LIN_get()

AGHAF_LIN AGHAF_LIN_get ( AGHAF_Device  device,
uint8_t  index 
)

Return the LIN bus at the index specified.

Parameters
devicehandle on the device
indexindex from the LIN
Returns
handle on the LIN (NULL if index invalid)
Examples
LIN_EventTriggered/main.cpp, LIN_Sporadic/main.cpp, and LIN_UnconditionalFrame/main.cpp.

◆ AGHAF_LIN_getCount()

uint8_t AGHAF_LIN_getCount ( AGHAF_Device  device)

Return the number of LINs available on a device.

Parameters
devicehandle on the device
Returns
number of LINs available
Examples
LIN_EventTriggered/main.cpp, LIN_Sporadic/main.cpp, and LIN_UnconditionalFrame/main.cpp.

◆ AGHAF_LIN_getIndex()

uint8_t AGHAF_LIN_getIndex ( AGHAF_LIN  lin)

Return the index from a LIN.

Parameters
linhandle on the LIN
Returns
index from the LIN

◆ AGHAF_LIN_getParam()

AGHAF_Status AGHAF_LIN_getParam ( AGHAF_LIN  lin,
AGHAF_LIN_Param  param,
uint32_t *  value 
)

Get a parameter from a LIN.

Parameters
linhandle on the LIN
paramparameter to get
valuevalue to get
Returns
status request information

◆ AGHAF_LIN_isActivated()

AGHAF_Status AGHAF_LIN_isActivated ( AGHAF_LIN  lin,
AGHAF_BOOL isActivated 
)

Allow to know if the communication on the LIN is started or not.

Parameters
linhandle on the LIN
isActivatedboolean to know if the communication is started or not
Returns
status request information

◆ AGHAF_LIN_SCHEDULE_addEventTriggered()

AGHAF_Status AGHAF_LIN_SCHEDULE_addEventTriggered ( AGHAF_LIN  lin,
uint8_t  scheduleIndex,
uint8_t  timeBaseCount,
uint8_t  eventTriggerId,
uint8_t  collisionTable 
)

Add an event triggered in a schedule.

Parameters
linhandle on the LIN
scheduleIndexindex from the schedule
timeBaseCountnumber of time base parameter that will be waited before the next event
eventTriggerIdframe id associated to the event
collisionTabletable to be used in case of collision
Returns
status request information
Examples
LIN_EventTriggered/main.cpp.

◆ AGHAF_LIN_SCHEDULE_addSporadic()

AGHAF_Status AGHAF_LIN_SCHEDULE_addSporadic ( AGHAF_LIN  lin,
uint8_t  scheduleIndex,
uint8_t  timeBaseCount,
uint8_t  nbSpo,
uint8_t *  idList 
)

Add a sporadic frame in a schedule.

Parameters
linhandle on the LIN
scheduleIndexindex from the schedule
timeBaseCountnumber of time base parameter that will be waited before the next event
nbSponumber of sporadic in the list
idListlist of sporadic ids
Returns
status request information
Examples
LIN_Sporadic/main.cpp.

◆ AGHAF_LIN_SCHEDULE_addUnconditional()

AGHAF_Status AGHAF_LIN_SCHEDULE_addUnconditional ( AGHAF_LIN  lin,
uint8_t  scheduleIndex,
uint8_t  fid,
uint8_t  timeBaseCount 
)

Add an unconditionale frame in a schedule.

Parameters
linhandle on the LIN
scheduleIndexindex from the schedule
fidframe identifier
timeBaseCountnumber of time base parameter that will be waited before the next event
Returns
status request information
Examples
LIN_EventTriggered/main.cpp, and LIN_UnconditionalFrame/main.cpp.

◆ AGHAF_LIN_SCHEDULE_addWakeUp()

AGHAF_Status AGHAF_LIN_SCHEDULE_addWakeUp ( AGHAF_LIN  lin,
uint8_t  scheduleIndex,
uint8_t  timeBaseCount 
)

Add a wake in a schedule.

Parameters
linhandle on the LIN
scheduleIndexindex from the schedule
timeBaseCountnumber of time base parameter that will be waited before the next event
Returns
status request information

◆ AGHAF_LIN_SCHEDULE_clearDatas()

AGHAF_Status AGHAF_LIN_SCHEDULE_clearDatas ( AGHAF_LIN  lin,
uint8_t  scheduleIndex 
)

Clear the datas associated to a schedule index.

Parameters
linhandle on the LIN
scheduleIndexindex from the schedule
Returns
status request information

◆ AGHAF_LIN_SCHEDULE_configure()

AGHAF_Status AGHAF_LIN_SCHEDULE_configure ( AGHAF_LIN  lin,
uint8_t  scheduleIndex,
AGHAF_LIN_ScheduleKind  kind 
)

AGHAF_LIN_SCHEDULE_configure.

Parameters
linhandle on the LIN
scheduleIndexindex from the schedule
kindkind of schedule: AGHAF_LIN_ScheduleKind
Returns
status request information
Examples
LIN_EventTriggered/main.cpp, LIN_Sporadic/main.cpp, and LIN_UnconditionalFrame/main.cpp.

◆ AGHAF_LIN_SCHEDULE_getCount()

AGHAF_Status AGHAF_LIN_SCHEDULE_getCount ( AGHAF_LIN  lin,
uint8_t *  count 
)

Number of LIN schedule that can be configured.

Parameters
linhandle on the LIN
countpointer to be filled with the number of schedule configurable.
Returns
status request information

◆ AGHAF_LIN_SCHEDULE_start()

AGHAF_Status AGHAF_LIN_SCHEDULE_start ( AGHAF_LIN  lin,
uint8_t  scheduleIndex 
)

Start a schedule.

Warning
Only one schedule can be started at the same time.
Parameters
linhandle on the LIN
scheduleIndexindex from the schedule
Returns
status request information
Examples
LIN_EventTriggered/main.cpp, LIN_Sporadic/main.cpp, and LIN_UnconditionalFrame/main.cpp.

◆ AGHAF_LIN_SCHEDULE_stop()

AGHAF_Status AGHAF_LIN_SCHEDULE_stop ( AGHAF_LIN  lin)

Stop the schedule currently executed on the LIN.

Parameters
linhandle on the LIN
Returns
status request information
Examples
LIN_EventTriggered/main.cpp, LIN_Sporadic/main.cpp, and LIN_UnconditionalFrame/main.cpp.

◆ AGHAF_LIN_sendHeader()

AGHAF_Status AGHAF_LIN_sendHeader ( AGHAF_LIN  lin,
uint8_t  fid 
)

Write header on the LIN.

Warning
must be used only in master mode
Parameters
linhandle on the LIN
fidframe identifier
Returns
status request information

◆ AGHAF_LIN_setOnBusStateChangedCallback()

void AGHAF_LIN_setOnBusStateChangedCallback ( AGHAF_LIN  lin,
AGHAF_LIN_onBusStateChanged  callback,
void *  userContext 
)

Set the callback called on a bus state changed event.

Parameters
linhandle on the LIN
callbackcallback to be used for the event
userContextcontext provided by the user for custom datas

◆ AGHAF_LIN_setOnErrorCallback()

void AGHAF_LIN_setOnErrorCallback ( AGHAF_LIN  lin,
AGHAF_LIN_onError  callback,
void *  userContext 
)

Set the callback called on an error event.

Parameters
linhandle on the LIN
callbackcallback to be used for the event
userContextcontext provided by the user for custom datas
Examples
LIN_EventTriggered/main.cpp, LIN_Sporadic/main.cpp, and LIN_UnconditionalFrame/main.cpp.

◆ AGHAF_LIN_setOnMessageRxCallback()

void AGHAF_LIN_setOnMessageRxCallback ( AGHAF_LIN  lin,
AGHAF_LIN_onMessageRx  callback,
void *  userContext 
)

Set the callback called on rx event.

Parameters
linhandle on the LIN
callbackcallback to be used for the event
userContextcontext provided by the user for custom datas
Examples
LIN_EventTriggered/main.cpp, LIN_Sporadic/main.cpp, and LIN_UnconditionalFrame/main.cpp.

◆ AGHAF_LIN_setOnMessageTxCallback()

void AGHAF_LIN_setOnMessageTxCallback ( AGHAF_LIN  lin,
AGHAF_LIN_onMessageTx  callback,
void *  userContext 
)

Set the callback called on tx event.

Parameters
linhandle on the LIN
callbackcallback to be used for the event
userContextcontext provided by the user for custom datas
Examples
LIN_EventTriggered/main.cpp, LIN_Sporadic/main.cpp, and LIN_UnconditionalFrame/main.cpp.

◆ AGHAF_LIN_setOnWakeUpSentCallback()

void AGHAF_LIN_setOnWakeUpSentCallback ( AGHAF_LIN  lin,
AGHAF_LIN_onWakeUpSent  callback,
void *  userContext 
)

Set the callback called on a wake up sent event.

Parameters
linhandle on the LIN
callbackcallback to be used for the event
userContextcontext provided by the user for custom datas

◆ AGHAF_LIN_setParam()

AGHAF_Status AGHAF_LIN_setParam ( AGHAF_LIN  lin,
AGHAF_LIN_Param  param,
uint32_t  value 
)

Set a parameter from a LIN.

Parameters
linhandle on the LIN
paramparameter to set
valuevalue to set
Returns
status request information
Examples
LIN_EventTriggered/main.cpp, LIN_Sporadic/main.cpp, and LIN_UnconditionalFrame/main.cpp.

◆ AGHAF_LIN_updateFrame()

AGHAF_Status AGHAF_LIN_updateFrame ( AGHAF_LIN  lin,
uint8_t  fid,
uint8_t  dataLen,
uint8_t const *  data 
)

Update the datas associated to a frame identifier.

Note
must be used after LIN activation
Parameters
linhandle on the LIN
fidframe identifier
dataLenlength of the datas
datadatas to write
Returns
status request information
Examples
LIN_EventTriggered/main.cpp, and LIN_Sporadic/main.cpp.

◆ AGHAF_LIN_wakeUp()

AGHAF_Status AGHAF_LIN_wakeUp ( AGHAF_LIN  lin)

Send a wake up request on the bus LIN.

Parameters
linhandle on the LIN
Returns
status request information