NHS31xx SW API

Detailed Description

This file describes the protocol used for the Message Handler Module in the NFC program loader application (closed).

  1. (NHS31xx) Once the NHS31xx is started (either by a resetN or a by a NFC field) the downloader is initialized, and a MSG_RESPONSE_GETVERSION_T response is placed in NFC memory.
  2. (HOST) From that moment on, a HOST (tag reader) can start sending CMD_INCOMING_PACKAGE_T commands containing data chunks. Every incremental message has an id equal to MSG_INCOMING_PACKAGE. The NHS31xx expects a binary file to be downloaded from lower to higher addresses (starting from address 0x0).
  3. (NHS31xx) This command will be answered/acknowledged as fast as possible, this is done via a MSG_RESPONSE_RESULTONLY_T response. The result can be a MSG_ERR_T or a DOWNLOAD_REPORT_MSG_ERR_T
  4. (HOST) as long as the result is DOWNLOAD_ONGOING, the host can send new data chunks.
  5. (HOST) the very last package send to NHS31xx is slightly different from the incremental once, the header looks the same accept for the message id which is equal to MSG_LAST_INCOMING_PACKAGE. In this package, the data chunk is followed by the file CRC. The new program download will only be finalized when the in target calculated CRC matches the file CRC.

Following message flow describes a successful download cycle:

msc_inline_mscgraph_1
Note
Mind that, if for some reason an error occurs (protocol error/download error) the response will contain the corresponding result (MSG_ERR_T or DOWNLOAD_REPORT_MSG_ERR_T). If that happens, the NHS31xx needs to go through a reset cycle. Either by resetN or by re-providing the NFC field. iow, the complete download cycle has to be re-done.

Data Structures

struct  CMD_INCOMING_PACKAGE_T
 

Macros

#define MIME_TYPE   "N/P"
 
#define MIME_TYPE_LENGTH   3
 
#define MAX_CHUNK_SIZE   NFC_SHARED_MEM_BYTE_SIZE - NDEFT2T_MSG_OVERHEAD(false, NDEFT2T_GetMimeRecordOverhead(false, MIME_TYPE_LENGTH) + sizeof(CMD_INCOMING_PACKAGE_T))
 

Enumerations

enum  DOWNLOAD_REPORT_MSG_ERR_T {
  DOWNLOAD_COMPLETE_OK = 1,
  DOWNLOAD_ONGOING = 2,
  DOWNLOAD_FAILED_IMAGE_TOO_BIG = 3,
  DOWNLOAD_FAILED_FILE_INVALID_CHUNKSIZE = 4,
  DOWNLOAD_FAILED_FILE_CRC_MISMATCH = 5,
  DOWNLOAD_COMMUNICATION_FAILED = 6,
  DOWNLOAD_REPORT_MSG_ERR_LAST_USED = DOWNLOAD_COMMUNICATION_FAILED
}
 
enum  MSGHANDLER_MSG_ID_T {
  MSG_INCOMING_PACKAGE = 0x48,
  MSG_LAST_INCOMING_PACKAGE = 0x49,
  MSG_ID_SETPRISTINE = 0x5A,
  MSG_ID_SETRHYTHM = 0x55,
  MSG_ID_GETRHYTHM = 0x56,
  MSG_ID_START = 0x57,
  MSG_ID_GETSTART = 0x58,
  MSG_ID_GETPILLREMOVALS = 0x5D
}
 

Data Structure Documentation

◆ CMD_INCOMING_PACKAGE_T

struct CMD_INCOMING_PACKAGE_T

Structure defining the incoming packages This 'header' is followed by the data chunk with size defined in chunkSize. If id is MSG_LAST_INCOMING_PACKAGE this 'header' + data chunk is followed by the 16bits binary CRC.

See also
MSG_INCOMING_PACKAGE
MSG_LAST_INCOMING_PACKAGE
Data Fields
uint16_t chunkSize

This field holds the number of valid data bytes which will follow after this header.

Note
This value is limited by MAX_CHUNK_SIZE.
If id is MSG_LAST_INCOMING_PACKAGE chunkSize does not include the CRC size.

Macro Definition Documentation

◆ MIME_TYPE

#define MIME_TYPE   "N/P"

Mime type to be used in the data transfer

◆ MIME_TYPE_LENGTH

#define MIME_TYPE_LENGTH   3

Size of mime type used in the data transfer

◆ MAX_CHUNK_SIZE

#define MAX_CHUNK_SIZE   NFC_SHARED_MEM_BYTE_SIZE - NDEFT2T_MSG_OVERHEAD(false, NDEFT2T_GetMimeRecordOverhead(false, MIME_TYPE_LENGTH) + sizeof(CMD_INCOMING_PACKAGE_T))

Maximum size of data chunk to be send by the HOST Using this size will result in optimal use of shared memory

Enumeration Type Documentation

◆ DOWNLOAD_REPORT_MSG_ERR_T

Lists all possible download errors codes that may be returned. Extends MSG_ERR_T

Enumerator
DOWNLOAD_COMPLETE_OK 

0x01
No error was found.

DOWNLOAD_ONGOING 

0x02
Ongoing Download.

DOWNLOAD_FAILED_IMAGE_TOO_BIG 

0x03
The image did not fit in user flash

DOWNLOAD_FAILED_FILE_INVALID_CHUNKSIZE 

0x04
The given chunk size does not match with the total CMD size

DOWNLOAD_FAILED_FILE_CRC_MISMATCH 

0x05
The calculated CRC doesn't match with the received CRC

DOWNLOAD_COMMUNICATION_FAILED 

0x06
General ERROR, i.e. non valid command ID

◆ MSGHANDLER_MSG_ID_T

Supported application commands

Enumerator
MSG_INCOMING_PACKAGE 

0x48
Incremental data package

MSG_LAST_INCOMING_PACKAGE 

0x49
Last incremental data package including the binary CRC

MSG_ID_SETPRISTINE 

0x5A
Removes all information that was received via any command. Removes all stored events.

Parameters
MSG_CMD_TAGONLY_T
Returns
MSG_RESPONSE_RESULTONLY_T
Note
synchronous command
MSG_ID_SETRHYTHM 

0x55
Defines the rhythm the patient must adhere to when following the therapy. The application will determine based on this information whether the patient still adheres to the therapy.

Note
In case the application tracks different pills - each pill is specific and the order of intake of each pill is important - it is assumed the first pill must ideally be taken at the first pill intake moment, the nth pill must ideally be taken at the nth pill intake moment, and so on.
Parameters
MSG_CMD_SETRHYTHM_T
Returns
MSG_RESPONSE_RESULTONLY_T
Note
synchronous command
MSG_ID_GETRHYTHM 

0x56
Retrieves rhythm information that was set by the last command with id MSG_ID_SETRHYTHM.

Parameters
MSG_CMD_TAGONLY_T
Returns
MSG_RESPONSE_GETRHYTHM_T
Note
synchronous command
MSG_ID_START 

0x57
Sets the time when the therapy starts. When this command is received, events will be tracked and followed up by the IC. All events before the given start time are considered out-of-band; all events after the given start time that do not follow the prescribed rhythm are also considered out-of-band.

Note
Mandatory configuration messages that must be exchanged before this command is accepted:
The therapy ends automatically when all drugs have been taken, or when a command with message id MSG_ID_SETPRISTINE is received.
Precondition
The therapy has not yet been started.
Parameters
MSG_CMD_START_T
Returns
MSG_RESPONSE_RESULTONLY_T
Note
synchronous command
MSG_ID_GETSTART 

0x58
Retrieves the start time that was set by the last command with id MSG_ID_START.

Parameters
MSG_CMD_TAGONLY_T
Returns
MSG_RESPONSE_GETSTART_T
Note
synchronous command
MSG_ID_GETPILLREMOVALS 

0x5D
Retrieves all pill removals that have been recorded since the start of the therapy.

Parameters
MSG_CMD_TAGONLY_T
Returns
MSG_RESPONSE_GETPILLREMOVALS_T
Note
synchronous command
Retrieving the pill removals does not clear them from the IC. Issuing the same command again will yield the same response - possibly expanded with new removals.