NHS31xx SW API
msg: Message Handler

Detailed Description

The message handler is a module which provides a command - response message mechanism to help an upper layer to communicate with an external device. It is purely a software implementation without any direct dependency on hardware or transport layer. Using the message handler module, the upper layer can easily add or remove commands and responses, both at compile time and at runtime - by tweaking the diversity settings the module offers. At all times, the upper layer retains full control on what is received, what is parsed, what is generated and what is sent.

Definitions
A few definitions make the explanations below more clear:
Command
A sequence of bytes following a Protocol that is given to the message handler module that forms an instruction to perform an action.
When looking at system level, commands are typically sent by the tag reader via the NFC interface. On a few occasions, the application may generate commands itself, based on some events or interrupts, and then feed that to the message handler module.
Response
A sequence of bytes following a Protocol that is generated to partially or fully complete the action(s) requested by a previously received command and that is to be sent out via any transport layer.
When looking at system level, responses are always generated by some handler function, called by the message handler module. When generated, the message handler module will present it to the application, who then typically wraps them in an NDEF message and copied it to the NFC shared memory. On a few occasions, the application may decide to not forward the response, or to hold off forwarding the response to a later time.
Message
A command or a response. A more generic term when the directionality of the communication path is not important.
Command generator
A part of the upper layer that somehow gets hold of a command. That command may be originating from a phone, who has copied data to the NFC shared memory, which is then in turn copied by the firmware application to eventually feed it to the message handler module. The module does not know nor care: the part of the application that feeds the commands to the message handler module is designated as the 'command generator'.
Command handler
A function, either part of the message handler module or the upper layer, that interprets the content enclosed in a specific command, takes the appropriate actions and generates the corresponding responses. The output of the command handler, the response, is given back to the message handler module who is responsible for further distribution.
The message handler module has built-in support for handling commands that are deemed not specific for an application. For example MSG_ID_GETVERSION. Others can be enabled or disabled at compile time
Response handler
A part of the upper layer that receives responses via a designated callback, and that is responsible for sending out the generated responses to the originator of the corresponding command. The response handler is called by the message handler module.
Immediate response
The message handler module will ensure that for every command it receives, at least one response is generated and returned to the upper layer (*). This first guaranteed response will become available in a synchronous way, i.e. before the call has ended, and will be made available to the upper layer in the same CPU context as where the command has been given. This means that in case a specific command handler does not create a response - one may not be available or the designated message handler may reject generating any response - the message handler module will create one on that specific command handler's behalf. This first guaranteed response is called the immediate response. Additional responses may or may not be generated immediately or later - this is command and application specific.
Response generator
Either the message module itself, or the designated command handler. The block that will generate the immediate response.
Directionality
Each message requires the presence of a directionality field as part of the Protocol.
Overview
The message handler module does not run in its own thread and will not react to interrupts: it has to be explicitly triggered to do something.

When the upper layer delivers a sequence of bytes to the message handler module, i.e. the upper layer acts as a Command generator, the message handler module tries to interpret this as a command. Each sequence of bytes is supposed to constitute one command.

The message handler module maintains a list of known commands and tries to match the incoming command with this list. If a match is found, i.e. there is a Command handler for this specific command, the corresponding handler is called. At that point either the handler generates at least one response, i.e. it is also the response generator, after which the message handler module considers the command handling complete; or no response is generated, after which the message handler module will generate an immediate response itself, i.e. the message handler module will take over the role of Response generator.

Protocol
The message handler module uses the following communication protocol for commands and responses. The first byte shall indicate the message id. The second byte shall indicate the direction of transfer as mentioned below:
  • value of 0x0 for commands coming into message mod
  • value of 0x1 for responses going out from message mod
This is followed by the optional payload specific for each command/response. Details of the commands and responses are captured in the following sections.
Note
The NTAG SmartSensor family uses the NFC as a bi-directional communication path. But using the NFC technology it is not possible to flag the presence of new data to the tag reader: it is up to the tag reader to decide when to read. Waiting too long slows down communication, waiting a too short time results in reading out the previous data, likely the command bytes that the tag reader itself wrote in the NFC memory. Since it is possible that the exact same bytes constitute the response from the tag, the directionality byte is added as a means to distinguish commands from responses unambiguously. This byte is added as an aid for the tag reader: the tag itself has sufficient interrupt option at his disposal to know when a new message was written by the tag.
Commands
A command can be any sequence of bytes, that adheres to the Protocol.
Handlers
The message handler module has a default list of commands and corresponding command handlers - which can be enabled and disabled at compile time. The upper layer can at compile time add handlers for specific commands, or it can make use of a catch-all command handler to dynamically change the way it handles commands at runtime.
Apart from some minimal rules, no predefined formats exist, leaving the application with full freedom how to implement and handle its own specific commands.

A handler can be any function whose prototype match pMsg_CmdHandler_t. See MSG_APP_HANDLERS and MSG_CATCHALL_HANDLER for more information.

Responses
Responses are typically generated in a command handler. Generated responses are given to the message handler module, which then attempts to have them sent by calling a designated callback. That callback can either immediately send the response over the transport layer of its choosing back to the originator of the command; or reject the response. When rejected, the message handler module will store the response in its internal buffer; a special command is available to retrieve them at a later time.
Note
The device(s), layer(s) or block(s) that creates commands and handles responses can be considered to be the counter-part of the message handler module. The limitations imposed by the message handler module and the precise format of each command and response must be known by respected by that counter-part. Changes made to this on one side must be made as well on the other side.

Note
All commands generate one immediate response. This includes a response for the MSG_ID_RESET command, but a subsequent reset will re-initialize all peripherals, including the NFC controller and it NFC shared memory. All commands may subsequently generate zero, one or multiple additional responses at a later time.
Some commands are asynchronous in nature: in that case a response still must be immediately returned, denoting only the acceptance of the command, and subsequent responses provide the requested result.



Sequence diagrams
The following example sequence diagrams provide a quick insight in the different interactions.
Basic example

A very basic example, where each call returns success:

msc_inline_mscgraph_4

Holding back a response

In case the response handler is at first 'incapable of handling the response', i.e. of sending out the response immediately, the response can be retrieved at a later more convenient time:

msc_inline_mscgraph_5

Multiple responses per command

Some commands take time to complete, or cause the generation of multiple responses:

msc_inline_mscgraph_6

Including the transport layer

In practice, the role of command generator and response handler may both be taken up by 'the application'. The sequence diagram below now also an SPI block, to make clear it does not come into direct contact with the message handler module.

msc_inline_mscgraph_7
Note
The message handler module only expects full commands: it is either up to the upper layer or up to the specific command handler functions to guard against missing or superfluous bytes.

As can be seen, it is the application - your code - that sits between the communication channel and the message handling. This can be as thin as a simple pass-through: then the only benefit is a functionality isolation at the cost of a small overhead.
But the application can do more: it can encapsulate the responses, i.e. adding a CRC over an unreliable communication channel, or creating an NDEF message to send the response as a MIME type NDEFt2t record; and likewise it may need to validate the incoming commands by checking the CRC, or extracting every record from an NDEF multi-record message. This also provides a good debugging point, as the entire command/response flow can be easily logged or printed out over a debug line.

Internal messages / custom messages
A number of commands and corresponding responses have been predefined by the message handler module. They can be found in the enumeration MSG_ID_T. By default only one of them is compiled in to save code space: MSG_ID_GETVERSION.

Each command has a corresponding command structure MSG_CMD_xxxx_T that describes the fields which are packed into the command payload, and one or possibly two response structures MSG_RESPONSE_xxxx_T that describe which fields to expect in return, as part of the response payload.

By default, there exist no custom messages: it is up to the application to define and implement them, and to connect them at compile time.

You can add custom messages them by properly defining both MSG_APP_HANDLERS_COUNT and MSG_APP_HANDLERS", and/or by defining MSG_RESPONSE_DISCARDED_CB. There is no obligation to create structures for each custom command and corresponding responses: all is well as long as the custom handlers generate the expected responses.

Diversity
This module supports a number of diversity flags. Check the Message handler module diversity settings for a full list and their implications.
How to use the module
Most likely there will be at least a few application specific commands and responses. A first step would then be to create a list of message id's and functions that act as the command handlers / response generators for these message id's and to store them in an array of type MSG_CMD_HANDLER_T.

Each such function is to use Msg_AddResponse reply to a received command. It is recommended also create a (packed) command structure and response structure for each message id, as this aids in explicitly describing the message specific parameters.

Also check the other diversity flags and enable the required functionality. Possibly you'll have to implement a few callback functions if you want to make use of all the functionality. Couple your 'extensions' using the diversity flags.

After initializing the message handler module with Msg_Init and Msg_SetResponseCb, you just feed it commands via Msg_HandleCommand. The whole chain provided by the message handler module and your implemented and coupled extensions will deliver the responses to the response callback you set.

Example
Below a minimalistic code-like example is given. This does not cover the full functionality the message handler module offers, but aids in clarifying how all the pieces are tied together. In the example, one application specific message is added, then via the transport layer a command with that new id is received. The newly created command handler generates a response, which is then sent out again.
Handle function
uint8_t response[1];
response[0] = 7;
Msg_AddResponse(0x77, 1, response);
return MSG_OK;
Command Handler
static uint32_t Handler77(uint8_t msgId, int payloadLen, const uint8_t* pPayload);
MSG_CMD_HANDLER_T appCmdHandler[MSG_APP_HANDLERS_COUNT] = { {0x77, Handler77},
/* Additional commands can be added here. */
};
Note
Id 0x77 is considered for this example.
Response callback 'ResponseCb' function
/* Send the bytes over I2C, encapsulate it in an NDEF MIME message, or ... */
return true;
Msg Mod Init
Msg_SetResponseCb(ResponseCb);
Data receive function
uint8_t buffer[2] = {};
uint8_t length = 2;
/* Retrieve the bytes that were sent to the NHS over I2C, NFC, or ... */
buffer[0] = 0x77; /* message id */
buffer[1] = 0; /* directionality byte */
Msg_HandleCommand(length, buffer);

Modules

 Diversity Settings
 

Data Structures

struct  MSG_CMD_READREGISTER_T
 
struct  MSG_CMD_WRITEREGISTER_T
 
struct  MSG_CMD_READMEMORY_T
 
struct  MSG_CMD_WRITEMEMORY_T
 
struct  MSG_CMD_HANDLER_T
 
struct  MSG_RESPONSE_RESULTONLY_T
 
struct  MSG_RESPONSE_GETVERSION_T
 
struct  MSG_RESPONSE_READREGISTER_T
 
struct  MSG_RESPONSE_READMEMORY_T
 
struct  MSG_RESPONSE_GETUID_T
 
struct  MSG_RESPONSE_GETNFCUID_T
 
struct  MSG_RESPONSE_CHECKBATTERY_T
 

Macros

#define MSG_API_MAJOR_VERSION   (0x6)
 
#define MSG_API_MINOR_VERSION   (0x1)
 

Typedefs

typedef uint32_t(* pMsg_CmdHandler_t) (uint8_t msgId, int payloadLen, const uint8_t *pPayload)
 
typedef bool(* pMsg_AcceptCommandCb_t) (uint8_t msgId, int payloadLen, const uint8_t *pPayload)
 
typedef bool(* pMsg_ResponseCb_t) (int responseLength, const uint8_t *pResponseData)
 

Enumerations

enum  MSG_ID_T {
  MSG_ID_GETRESPONSE = 0x01,
  MSG_ID_GETVERSION = 0x02,
  MSG_ID_RESET = 0x03,
  MSG_ID_READREGISTER = 0x04,
  MSG_ID_WRITEREGISTER = 0x05,
  MSG_ID_READMEMORY = 0x06,
  MSG_ID_WRITEMEMORY = 0x07,
  MSG_ID_PREPAREDEBUG = 0x08,
  MSG_ID_GETUID = 0x09,
  MSG_ID_GETNFCUID = 0x0a,
  MSG_ID_CHECKBATTERY = 0x0b,
  MSG_ID_GETCALIBRATIONTIMESTAMP = 0x0c,
  MSG_ID_GETDIAGDATA = 0x3E,
  MSG_ID_LASTRESERVED = 0x3F
}
 
enum  MSG_ERR_T {
  MSG_OK = 0,
  MSG_ERR_UNKNOWN_COMMAND = 0x10007,
  MSG_ERR_NO_RESPONSE = 0x1000B,
  MSG_ERR_INVALID_COMMAND_SIZE = 0x1000D,
  MSG_ERR_INVALID_PARAMETER = 0x1000E,
  MSG_ERR_INVALID_PRECONDITION = 0x1000F,
  MSG_ERR_INVALID_NYI = 0x10010,
  MSG_ERR_LASTRESERVED = 0x1003F
}
 

Functions

void Msg_Init (void)
 
void Msg_SetResponseCb (pMsg_ResponseCb_t cb)
 
void Msg_AddResponse (uint8_t msgId, int payloadLen, const uint8_t *pPayload)
 
void Msg_HandleCommand (int cmdLength, const uint8_t *pCmdData)
 

Data Structure Documentation

◆ MSG_CMD_READREGISTER_T

struct MSG_CMD_READREGISTER_T
Data Fields
uint32_t address

Register address to read from.

◆ MSG_CMD_WRITEREGISTER_T

struct MSG_CMD_WRITEREGISTER_T
Data Fields
uint32_t address

Register address to write to.

uint32_t data

Data to write to the ARM register.

◆ MSG_CMD_READMEMORY_T

struct MSG_CMD_READMEMORY_T
Data Fields
uint32_t address

Byte offset in the ARM RAM to start reading from.

uint8_t length

The number of consecutive bytes to read with a maximum of 32.

◆ MSG_CMD_WRITEMEMORY_T

struct MSG_CMD_WRITEMEMORY_T
Data Fields
uint32_t address

Byte offset in the ARM RAM to start writing to.

uint8_t length

The number of consecutive bytes to write with a maximum of 32.

uint8_t data[32]

A container for the data to write.

◆ MSG_CMD_HANDLER_T

struct MSG_CMD_HANDLER_T

Structure to be used to add the application specific command handlers.

See also
MSG_APP_HANDLERS_COUNT
Data Fields
uint8_t id

The id of the command this handler takes care of.

pMsg_CmdHandler_t handler

The function that handles a command with id as message id.

◆ MSG_RESPONSE_RESULTONLY_T

struct MSG_RESPONSE_RESULTONLY_T

Used whenever no other information is required to be returned except the outcome of a command.

Data Fields
uint32_t result

The command result.

Note
If this structure is used to return an immediate result, the interpretation of the result value is different, depending on the type of command: synchronous or asynchronous:
  • For synchronous commands, the result indicates the result of executing the command. The command has been fully executed. MSG_OK means that the command was successfully executed, any other value indicates an error code and signifies that the command has been partially executed or not at all.
  • For asynchronous commands the result only indicates the result of receiving the command and checking its pre-conditions. MSG_OK means that the commands was successfully received and execution of the command has started, any other value indicates an error code and signifies that the command will be partially executed or not at all. The final result of the execution of the command will be part of the response that will be queued later.
If this structure is used to respond to the command MSG_ID_GETRESPONSE, it signifies the final result of the execution of an asynchronous command.

◆ MSG_RESPONSE_GETVERSION_T

struct MSG_RESPONSE_GETVERSION_T
Data Fields
uint16_t reserved2

Reserved for future use. Must be 0. Does not bear any significance.

uint16_t swMajorVersion

The software major version

uint16_t swMinorVersion

The software minor version

uint16_t apiMajorVersion

Equal to MSG_API_MAJOR_VERSION

uint16_t apiMinorVersion

Equal to MSG_API_MINOR_VERSION

uint32_t deviceId

This value will be equal to:

  • 0x4E310020 for NHS3100 devices
  • 0x4E315220 for NHS3152 devices

◆ MSG_RESPONSE_READREGISTER_T

struct MSG_RESPONSE_READREGISTER_T
Data Fields
uint32_t result

The command result. Only when result equals MSG_OK, the contents of data is valid.

uint32_t data

The value read from the ARM Register

◆ MSG_RESPONSE_READMEMORY_T

struct MSG_RESPONSE_READMEMORY_T
Data Fields
uint32_t result

The command result. Only when result equals MSG_OK, the contents of data is valid.

uint8_t length

The number of consecutive bytes read.

uint8_t data[32]

The values read from the ARM memory. The extraneous array elements - where the index is greater than length - are set to 0.

◆ MSG_RESPONSE_GETUID_T

struct MSG_RESPONSE_GETUID_T
See also
MSG_ID_GETUID
Data Fields
uint32_t uid[4]

The sequence of 4 32-bit words (LSByte first) is guaranteed unique among all NHS31xx ICs.

◆ MSG_RESPONSE_GETNFCUID_T

struct MSG_RESPONSE_GETNFCUID_T
Data Fields
uint8_t nfcuid[8]

The sequence of bytes as assigned to the NFC controller.

◆ MSG_RESPONSE_CHECKBATTERY_T

struct MSG_RESPONSE_CHECKBATTERY_T
Data Fields
uint32_t result

The command result. Only when result equals MSG_OK, the contents of data is valid.

int32_t threshold

Extra current consumption is enabled in progressive steps. The extra current consumption which triggered the BOD is returned here. A negative value indicates BOD could not be triggered.

Macro Definition Documentation

◆ MSG_API_MAJOR_VERSION

#define MSG_API_MAJOR_VERSION   (0x6)

Defines the major API version. This should be incremented each time the API changes.

◆ MSG_API_MINOR_VERSION

#define MSG_API_MINOR_VERSION   (0x1)

Defines the minor API version. This should be reset each time the API changes, and incremented each time the API doesn't change but the implementation or documentation changes.

Typedef Documentation

◆ pMsg_CmdHandler_t

typedef uint32_t(* pMsg_CmdHandler_t) (uint8_t msgId, int payloadLen, const uint8_t *pPayload)

Callback function type to handle custom commands.

See also
Msg_HandleCommand
Parameters
msgIdHolds the id of the message
payloadLenThe size in bytes of the array pPayload points to
pPayloadPoints to the message that requires to be handled. Data retention is only guaranteed until the call has ended.
Returns
  • Either MSG_OK is returned: the command has been handled, and an immediate response is given by calling Msg_AddResponse.
  • Either any other value is returned: the command has not been handled, and no immediate response is given. The message handler module will use the returned error value to create an immediate response of type MSG_RESPONSE_RESULTONLY_T.
Postcondition
If MSG_OK is returned, the first call to Msg_AddResponse during the lifetime of this call must be the immediate response.

◆ pMsg_AcceptCommandCb_t

typedef bool(* pMsg_AcceptCommandCb_t) (uint8_t msgId, int payloadLen, const uint8_t *pPayload)

Callback function type to notify the upper layer of new commands. This is the signature to use when defining MSG_COMMAND_ACCEPT_CB The purpose is to provide a single entry point for the upper layer where he can decide whether the command gets accepted and handled or not.

Note
Do not generate responses during this callback! Use this function to inspect the data, for logging purposes and to enforce a specific communication flow.
See also
Msg_HandleCommand
Parameters
msgIdHolds the id of the message
payloadLenThe size in bytes of the array pPayload points to
pPayloadPoints to the payload of the command that requires to be handled.
Returns

◆ pMsg_ResponseCb_t

typedef bool(* pMsg_ResponseCb_t) (int responseLength, const uint8_t *pResponseData)

Callback function type to handle responses.

Parameters
responseLengthThe size in bytes of the array pResponseData points to
pResponseDataPoints to the response, that must be sent back to the host. Data retention is only guaranteed until the call has ended.
Returns
  • true if the response was accepted, the relevant data has been copied, and the memory occupied by it may be cleared.
  • false if the response was rejected. The response will be stored internally by the message handler module, and can be fetched later by issuing the command MSG_ID_GETRESPONSE. If the internal storage is full, the oldest response is discarded.

Enumeration Type Documentation

◆ MSG_ID_T

enum MSG_ID_T

Supported messages.

Note
Each message comprises of a command and a response. For each command and response a corresponding struct exists which explains the parameters, their sizes and their use.
Enumerator
MSG_ID_GETRESPONSE 

0x01
The message handler module holds a queue of responses. Each time a response is created which cannot be sent back immediately (in response to a command), it is queued. It's the task of the host to use this command to retrieve the queued responses.

Note
When the host doesn't retrieve the responses fast enough, the buffer gets filled up. When a new response can not be stored any more, the oldest responses are discarded until sufficient room is available to store the newest response. The upper layer can get notified when this happens via the diversity setting MSG_RESPONSE_DISCARDED_CB.
Parameters
Header: Sequence of bytes as per the Protocol.
Payload: No payload.
Returns
The response is returned immediately.
Note
synchronous command
For this command to become available, define both MSG_RESPONSE_BUFFER and MSG_RESPONSE_BUFFER_SIZE.
MSG_ID_GETVERSION 

0x02
This message id allows the host to determine the version of the firmware.

Parameters
Header: Sequence of bytes as per the Protocol.
Payload: No payload.
Returns
MSG_RESPONSE_GETVERSION_T
Note
synchronous command
This command is always available.
MSG_ID_RESET 

0x03
Generate a SW reset of the digital part of the system.

Parameters
Header: Sequence of bytes as per the Protocol.
Payload: No payload.
Returns
MSG_RESPONSE_RESULTONLY_T. This response will be available for 500 milliseconds.
Note
synchronous command
For this command to become available, define MSG_ENABLE_RESET
MSG_ID_READREGISTER 

0x04
Read and return the value from the selected ARM register address.

Parameters
Header: Sequence of bytes as per the Protocol.
Payload: MSG_CMD_READREGISTER_T
Returns
MSG_RESPONSE_READREGISTER_T
Note
synchronous command
For this command to become available, define MSG_ENABLE_READREGISTER
MSG_ID_WRITEREGISTER 

0x05
Write the data supplied by the host to the selected ARM register address.

Parameters
Header: Sequence of bytes as per the Protocol.
Payload: MSG_CMD_WRITEREGISTER_T
Returns
MSG_RESPONSE_RESULTONLY_T.
Note
synchronous command
For this command to become available, define MSG_ENABLE_WRITEREGISTER
MSG_ID_READMEMORY 

0x06
Read and return the value from the selected address.

Parameters
Header: Sequence of bytes as per the Protocol.
Payload: MSG_CMD_READMEMORY_T
Returns
MSG_RESPONSE_READMEMORY_T.
Note
synchronous command
For this command to become available, define MSG_ENABLE_READMEMORY
The address range may be part of SRAM, Flash or EEPROM.
Warning
It is assumed the address region is accessible and can be read. This is not checked for. e.g. This implies it is the application's responsibility to ensure the EEPROM is initialized when reading EEPROM data, and that it is the caller's responsibility to ensure the range can be mapped to valid addresses.
MSG_ID_WRITEMEMORY 

0x07
Write the data supplied by the host to the selected ARM memory address.

Parameters
Header: Sequence of bytes as per the Protocol.
Payload: MSG_CMD_WRITEMEMORY_T
Returns
MSG_RESPONSE_RESULTONLY_T.
Note
synchronous command
For this command to become available, define MSG_ENABLE_WRITEMEMORY
Warning
Only SRAM can be written to. It is assumed the address region which is referred to is fully part of SRAM. This is not checked for.
MSG_ID_PREPAREDEBUG 

0x08
Configures and enables the SWD lines, then waits in an endless while loop. This allows a developer to attach a debugger to the running device.

Parameters
Header: Sequence of bytes as per the Protocol.
Payload: No payload.
Returns
MSG_RESPONSE_RESULTONLY_T.
Note
synchronous command
When a debugging session has been established, set the boolean gMsgWaitForDebugConnection to false to return from the command handler.
For this command to become available, define MSG_ENABLE_PREPAREDEBUG
Usage of this message id will be difficult in combination with the watch dog timer. Be sure the WDT is not enabled when you plan to use this debug message.
MSG_ID_GETUID 

0x09
Retrieve the unique identifier of the IC. This is the device serial number guaranteed unique among all NHS31xx ICs.

Note
This is not equal to the NFC ID, which is a randomly assigned number.
Parameters
Header: Sequence of bytes as per the Protocol.
Payload: No payload.
Returns
MSG_RESPONSE_GETUID_T
Note
synchronous command
Enabled by default. To disable this command, undefine MSG_ENABLE_GETUID.
MSG_ID_GETNFCUID 

0x0a
Retrieve the NFC identifier of the IC. This is the serial number assigned to the NFC controller and stored in the first two pages of the NFC shared memory.

Note
This is a random number assigned during production of the IC. It is not guaranteed unique among all NHS31xx ICs.
This is not equal to the device UID.
Parameters
Header: Sequence of bytes as per the Protocol.
Payload: No payload.
Returns
MSG_RESPONSE_GETUID_T
Note
synchronous command
Enabled by default. To disable this command, undefine MSG_ENABLE_GETNFCUID.
MSG_ID_CHECKBATTERY 

0x0b
Generates whether the BOD is triggered under extra load. Use this to check battery impedance.

Parameters
Header: Sequence of bytes as per the Protocol.
Payload: No payload.
Returns
MSG_RESPONSE_RESULTONLY_T immediately;
If result was equal to MSG_OK, MSG_RESPONSE_CHECKBATTERY_T thereafter. This may take several 100 ms. This second response must be fetched by issuing a command with MSG_ID_GETRESPONSE
Note
asynchronous command
For this command to become available, define MSG_ENABLE_CHECKBATTERY
Warning
This check has a (small) negative impact on the battery. And, this check potentially can cause a reset. An application may be prudent by blocking this message while a reset is not desired, e.g. during a monitoring session in a logger application. This can be done by implementing MSG_COMMAND_ACCEPT_CB
MSG_ID_GETCALIBRATIONTIMESTAMP 

0x0b
Retrieves the timestamps of when the temperature calibration took place (at 30C and 85C).

Parameters
Header: Sequence of bytes as per the Protocol.
Payload: No payload.
Returns
MSG_RESPONSE_GETDIAGDATA_T
Note
synchronous command
Enabled by default. To disable this command, undefine MSG_ENABLE_GETCALIBRATIONTIMESTAMP.
MSG_ID_GETDIAGDATA 

0x3E
Retrieve diagnostics information as gathered by the diag module.

Parameters
Header: Sequence of bytes as per the Protocol.
Payload: No payload.
Returns
MSG_RESPONSE_GETDIAGDATA_T
Note
synchronous command
For this command to become available, define ENABLE_DIAG_MODULE.
MSG_ID_LASTRESERVED 

0x3F
This message id does not encompass a command or a response. It is used to signify the highest id that is reserved for use by the message handler itself. All application specific commands - which are to be handled by setting a specific handler - must use id's greater than this value.

Note
Only to be used as an offset for your own application specific commands and responses.
See also
Cmd_SetApplicationHandler

◆ MSG_ERR_T

enum MSG_ERR_T

Lists all possible error codes that may be returned.

Enumerator
MSG_OK 

0x00000000
No error was found.

MSG_ERR_UNKNOWN_COMMAND 

0x00010007 or [07h 00h 01h 00h]
No suitable command handler could be found for this id

MSG_ERR_NO_RESPONSE 

0x0001000B or [0Bh 00h 01h 00h]
Only used in the response to a command with id MSG_ID_GETRESPONSE, to indicate no stored responses are available in the buffer.

MSG_ERR_INVALID_COMMAND_SIZE 

0x0001000D or [0Dh 00h 01h 00h]
A number of parameters are lacking or were given in excess.

MSG_ERR_INVALID_PARAMETER 

0x0001000E or [0Eh 00h 01h 00h]
At least one parameter was missing or had an invalid value.

MSG_ERR_INVALID_PRECONDITION 

0x0001000F or [0Fh 00h 01h 00h]
The command can now not be handled. Check the documentation for a correct command sequence.

MSG_ERR_INVALID_NYI 

0x00010010 or [10h 00h 01h 00h]
The handler of the command is a stub and still needs to be implemented; or the implementation to handle the given combination of parameters is incomplete and a work in progress. Check with the developer to retrieve updated firmware.

MSG_ERR_LASTRESERVED 

0x0001003F
This error code does not encompass an error. It is used to signify the highest id that is reserved for use by the message handler itself. All application specific error codes must use id's greater than this value.

Note
Only to be used as an offset for your own application specific error codes.

Function Documentation

◆ Msg_Init()

void Msg_Init ( void  )

Initializes the module.

Precondition
This must be the first function called of this module.
Note
May be called multiple times. Whenever called, the response buffer will be cleared.

◆ Msg_SetResponseCb()

void Msg_SetResponseCb ( pMsg_ResponseCb_t  cb)

Register a callback function that will be called whenever an immediate response is available.

Parameters
cb: The function to call that will send the response to the host. May not be NULL.
Precondition
This must be set before calling Msg_HandleCommand.
Note
The given function will be called under the same context as the previous call to Msg_AddResponse, or the previous call to Msg_HandleCommand with id MSG_ID_GETRESPONSE

◆ Msg_AddResponse()

void Msg_AddResponse ( uint8_t  msgId,
int  payloadLen,
const uint8_t *  pPayload 
)

Try to send the response back to the upper layer. If this fails and a buffer has been made available via the diversities MSG_RESPONSE_BUFFER and MSG_RESPONSE_BUFFER_SIZE, store the response so it can be given to the upper layer at a later time.

Note
If a function has been assigned to MSG_RESPONSE_DISCARDED_CB, and no response buffer is available, this function will have been called before this function exits in case the upper layer refuses the response. That callback will also have been called when pushing this response into the response buffer causes the oldest response(s) to be popped out.
Parameters
msgId: Holds the id of the message
payloadLen: Size in bytes of the response
pPayload: May not be NULL. Points to payloadLen number of bytes, which forms the complete response.

◆ Msg_HandleCommand()

void Msg_HandleCommand ( int  cmdLength,
const uint8_t *  pCmdData 
)

To be called each time a command has been received via any communication channel.

Parameters
cmdLength: The size in bytes in pCmdData
Precondition
cmdLength >= 2
Parameters
pCmdData: Pointer to the array containing the raw command bytes as specified by Protocol.
Precondition
data retention of the bytes contained in pCmdData must be guaranteed until the function returns.
Postcondition
The callback function as registered in the call to Msg_SetResponseCb will have been called.
Multiple consecutive calls to that same callback function may be issued after this call has ended.