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:
- 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:
- Multiple responses per command
Some commands take time to complete, or cause the generation of multiple responses:
- 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.
- 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;
- Command Handler
static uint32_t Handler77(uint8_t msgId, int payloadLen, const uint8_t* pPayload);
};
- Note
- Id 0x77 is considered for this example.
- Response callback 'ResponseCb' function
-
- Msg Mod Init
-
- Data receive function
uint8_t buffer[2] = {};
uint8_t length = 2;
buffer[0] = 0x77;
buffer[1] = 0;
|
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
} |
|
◆ 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
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 |
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.
|
◆ 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.
◆ 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
-
msgId | Holds the id of the message |
payloadLen | The size in bytes of the array pPayload points to |
pPayload | Points 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
-
msgId | Holds the id of the message |
payloadLen | The size in bytes of the array pPayload points to |
pPayload | Points 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
-
responseLength | The size in bytes of the array pResponseData points to |
pResponseData | Points 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.
◆ 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
-
- 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
-
- 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
-
- 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
-
- 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
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.
|
◆ Msg_Init()
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()
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.