NHS31xx SW API
Diversity Settings

Detailed Description

The message handler module allows the application to enable or disable certain behavior through the use diversity flags in the form of defines. Sensible defaults are chosen; to deviate, simply define the relevant flags and message ids in your application before including the message handler module.

Flags
Special message ids
Additional hooks to control the flow
Other message ids
A few predefined message id's are also enabled by default, and can be disabled in an application's app_sel.h: All other predefined message id's are disabled by default, and can be enabled in an application's app_sel.h:
Example
To override each and every diversity flag that the message handler module offers, create defines that are known to the precompiler before including the message handler module. The recommended way to do this is to add the code below to app_sel.h
#define MSG_APP_HANDLERS_COUNT 15
#define MSG_APP_HANDLERS <name of MSG_CMD_HANDLER_T array>
#define MSG_CATCHALL_HANDLER <name of pMsg_CmdHandler_t function>
#define SW_MAJOR_VERSION 4
#define SW_MINOR_VERSION 2
#define MSG_RESPONSE_BUFFER_SIZE 65
#define MSG_RESPONSE_BUFFER <name of uint8_t buffer>
#define MSG_COMMAND_ACCEPT_CB <name of pMsg_AcceptCommandCb_t function>
#define MSG_RESPONSE_DISCARDED_CB <name of pMsg_ResponseCb_t function>
#define MSG_ENABLE_RESET 1
#define MSG_ENABLE_READREGISTER 1
#define MSG_ENABLE_WRITEREGISTER 1
#define MSG_ENABLE_READMEMORY 1
#define MSG_ENABLE_WRITEMEMORY 1
#define MSG_ENABLE_PREPAREDEBUG 1
#define MSG_ENABLE_GETUID 1
#define MSG_ENABLE_CHECKBATTERY 1
#define MSG_ENABLE_GETCALIBRATIONTIMESTAMP 1
#define ENABLE_DIAG_MODULE 1

Macros

#define MSG_APP_HANDLERS_COUNT   0
 
#define MSG_ENABLE_GETVERSION   1
 
#define SW_MAJOR_VERSION   0
 
#define SW_MINOR_VERSION   0
 
#define MSG_RESPONSE_BUFFER_SIZE   0
 
#define MSG_ENABLE_GETRESPONSE   (MSG_RESPONSE_BUFFER_SIZE > 0)
 
#define MSG_ENABLE_RESET   0
 
#define MSG_ENABLE_READREGISTER   0
 
#define MSG_ENABLE_WRITEREGISTER   0
 
#define MSG_ENABLE_READMEMORY   0
 
#define MSG_ENABLE_WRITEMEMORY   0
 
#define MSG_ENABLE_PREPAREDEBUG   0
 
#define MSG_ENABLE_GETNFCUID   1
 
#define MSG_ENABLE_GETUID   1
 
#define MSG_ENABLE_CHECKBATTERY   0
 
#define MSG_ENABLE_GETCALIBRATIONTIMESTAMP   1
 
#define MSG_APP_HANDLERS   application defined array with MSG_APP_HANDLERS_COUNT elements of type #MSG_CMD_HANDLER_T
 
#define MSG_RESPONSE_BUFFER   application defined array with MSG_RESPONSE_BUFFER_SIZE elements of type uint8_t
 
#define MSG_COMMAND_ACCEPT_CB   application function of type pMsg_AcceptCommandCb_t
 
#define MSG_CATCHALL_HANDLER   application function of type pMsg_CmdHandler_t
 
#define MSG_RESPONSE_DISCARDED_CB   application function of type pMsg_ResponseCb_t
 

Macro Definition Documentation

◆ MSG_APP_HANDLERS_COUNT

#define MSG_APP_HANDLERS_COUNT   0
Precondition
To define custom command handlers, both MSG_APP_HANDLERS_COUNT and MSG_APP_HANDLERS must be defined.
MSG_APP_HANDLERS_COUNT must be a strict positive number indicating the size of the array MSG_APP_HANDLERS

◆ MSG_ENABLE_GETVERSION

#define MSG_ENABLE_GETVERSION   1

The command/response for MSG_ID_GETVERSION is enforced and can not be disabled.

See also
MSG_ID_GETVERSION

◆ SW_MAJOR_VERSION

#define SW_MAJOR_VERSION   0

Use the major version to distinguish between applications and/or application types. This define is used when generating the response to MSG_ID_GETVERSION

◆ SW_MINOR_VERSION

#define SW_MINOR_VERSION   0

Use the minor version to distinguish between application updates. This define is used when generating the response to MSG_ID_GETVERSION

◆ MSG_RESPONSE_BUFFER_SIZE

#define MSG_RESPONSE_BUFFER_SIZE   0

Responses that do not get treated immediately can be stored in an internal buffer.

Precondition
To define a buffer to be used by the message handler module, both MSG_RESPONSE_BUFFER_SIZE and MSG_RESPONSE_BUFFER must be defined. Define here the size of the buffer.
Note
responses greater than or equal to this size can not be stored.
MSG_RESPONSE_DISCARDED_CB will also be used whenever a response is not immediately accepted and:
  • no buffer is set and.
  • the response size is bigger than the buffer size.
  • the response size is bigger than 255 bytes: This is a limitation fully due to the implementation how the responses are stored in the internal buffer.
Defining MSG_RESPONSE_BUFFER_SIZE will automatically enable the command/response for MSG_ID_GETRESPONSE
See also
pMsg_ResponseCb_t

◆ MSG_ENABLE_GETRESPONSE

#define MSG_ENABLE_GETRESPONSE   (MSG_RESPONSE_BUFFER_SIZE > 0)

This command is automatically enabled when MSG_RESPONSE_BUFFER_SIZE is set.

See also
MSG_RESPONSE_BUFFER
MSG_ID_GETRESPONSE

◆ MSG_ENABLE_RESET

#define MSG_ENABLE_RESET   0

Assign a non-zero value to enable the handling of the command MSG_ID_RESET

◆ MSG_ENABLE_READREGISTER

#define MSG_ENABLE_READREGISTER   0

Assign a non-zero value to enable the handling of the command MSG_ID_READREGISTER

Warning
Should be disabled in production code; may be useful for debugging and testing purposes.

◆ MSG_ENABLE_WRITEREGISTER

#define MSG_ENABLE_WRITEREGISTER   0

Assign a non-zero value to enable the handling of the command MSG_ID_WRITEREGISTER

Warning
Should be disabled in production code; may be useful for debugging and testing purposes.

◆ MSG_ENABLE_READMEMORY

#define MSG_ENABLE_READMEMORY   0

Assign a non-zero value to enable the handling of the command MSG_ID_READMEMORY

Warning
Should be disabled in production code; may be useful for debugging and testing purposes.

◆ MSG_ENABLE_WRITEMEMORY

#define MSG_ENABLE_WRITEMEMORY   0

Assign a non-zero value to enable the handling of the command MSG_ID_WRITEMEMORY

Warning
Should be disabled in production code; may be useful for debugging and testing purposes.

◆ MSG_ENABLE_PREPAREDEBUG

#define MSG_ENABLE_PREPAREDEBUG   0

Assign a non-zero value to enable the handling of the command MSG_ID_PREPAREDEBUG

Warning
Should be disabled in production code; may be useful for debugging and testing purposes.

◆ MSG_ENABLE_GETNFCUID

#define MSG_ENABLE_GETNFCUID   1

Assign a zero value to disable the handling of the command MSG_ID_GETNFCUID

◆ MSG_ENABLE_GETUID

#define MSG_ENABLE_GETUID   1

Assign a zero value to disable the handling of the command MSG_ID_GETUID

◆ MSG_ENABLE_CHECKBATTERY

#define MSG_ENABLE_CHECKBATTERY   0

Assign a non-zero value to enable the handling of the command MSG_ID_CHECKBATTERY.

Warning
When enabled, the module batimp must also be referenced in the project.

◆ MSG_ENABLE_GETCALIBRATIONTIMESTAMP

#define MSG_ENABLE_GETCALIBRATIONTIMESTAMP   1

Assign a zero value to disable the handling of the command MSG_ID_GETCALIBRATIONTIMESTAMP

◆ MSG_APP_HANDLERS

#define MSG_APP_HANDLERS   application defined array with MSG_APP_HANDLERS_COUNT elements of type #MSG_CMD_HANDLER_T

To define custom command handlers, both MSG_APP_HANDLERS_COUNT and MSG_APP_HANDLERS must be defined.

Precondition
MSG_APP_HANDLERS must be an array with elements of type MSG_CMD_HANDLER_T

◆ MSG_RESPONSE_BUFFER

#define MSG_RESPONSE_BUFFER   application defined array with MSG_RESPONSE_BUFFER_SIZE elements of type uint8_t

Responses that do not get treated immediately can be stored in an internal buffer. To define a buffer to be used by the message handler module, both MSG_RESPONSE_BUFFER_SIZE and MSG_RESPONSE_BUFFER must be defined. Define here the location of the buffer.

Note
There are no alignment requirements.
The value set must match type pMsg_ResponseCb_t
Defining MSG_RESPONSE_BUFFER_SIZE will automatically enable the command/response for MSG_ID_GETRESPONSE

◆ MSG_COMMAND_ACCEPT_CB

#define MSG_COMMAND_ACCEPT_CB   application function of type pMsg_AcceptCommandCb_t

Adds a hook inside Msg_HandleCommand that allows to block handling each individual command.

Note
The value set must match type pMsg_AcceptCommandCb_t

◆ MSG_CATCHALL_HANDLER

#define MSG_CATCHALL_HANDLER   application function of type pMsg_CmdHandler_t

When the flexibility offered at compile time with MSG_APP_HANDLERS and MSG_APP_HANDLERS_COUNT is not enough, a callback can be defined where all untreated commands are directed to. The upper layer can then dynamically decide to treat certain commands or not.

Note
The value set must match type pMsg_CmdHandler_t
This must be set to the name of a function, not a pointer to a function: no dereference will be made!

◆ MSG_RESPONSE_DISCARDED_CB

#define MSG_RESPONSE_DISCARDED_CB   application function of type pMsg_ResponseCb_t

Responses that do not get treated immediately can be stored in an internal buffer, and they can be fetched later using MSG_ID_GETRESPONSE. Whenever this buffer runs full, the oldest response is discarded. To get notified when a response is being discarded, set this define to the callback to be called.

Note
The value set must match type pMsg_ResponseCb_t
This must be set to the name of a function, not a pointer to a function: no dereference will be made!
This callback will also be used when no buffer is set and whenever a response is not immediately accepted.