File content as of revision 43:28202405094d:

#ifndef _D7A_H_
#define _D7A_H_

#include "d7a_common.h"


//======================================================================
// Defines
//======================================================================

#define D7A_UID_LEN     (8)


//======================================================================
// Enums
//======================================================================

//======================================================================
// d7a_fs_storage_t
//----------------------------------------------------------------------
/// File "Storage Class"
//======================================================================
typedef enum {
    /// No data is keeped. Can only write in it.
    /// Ex: Use for commands.
    TRANSIENT = 0,
    /// Data is stocked in RAM and initialized at 0.
    /// Can not guarantee data integrity over time.
    /// Ex: Use for often updated data.
    VOLATILE,
    /// Data is stocked in RAM and initialized with the last flushed data from EEPROM.
    /// Can not guarantee data integrity over time.
    /// Ex: Use for temporary configurations.
    RESTORABLE,
    /// Data is stoked in EEPROM.
    /// Data integrity is guaranteed.
    /// Ex: Use for important configurations.
    /// /!\ Use sparingly as operations on these type of files are time and ressource consuming
    PERMANENT
} d7a_fs_storage_t;

//======================================================================
// d7a_fs_perm_t
//----------------------------------------------------------------------
/// File permissions for USER/GUEST
//======================================================================
typedef enum {
    O_O                = 0b00000000,
    R_O                = 0b00100000,
    R_R                = 0b00100100,
    W_O                = 0b00010000,
    W_W                = 0b00010010,
    RW_O               = 0b00110000,
    RW_R               = 0b00110100,
    RW_W               = 0b00110010,
    RW_RW              = 0b00110110,
    RWX_O              = 0b00111000,
    RWX_RWX            = 0b00111111,
} d7a_fs_perm_t;

// =======================================================================
// d7a_nls_t
// -----------------------------------------------------------------------
/// Enumerator of the NWL security modes
// =======================================================================
typedef enum
{
    /// No security enabled
    D7A_NLS_NO = 0,
    /// Encryption only, Counter Mode
    D7A_NLS_AES_CTR,
    /// No encryption, Authentication, Cipher-block chaining with 128 bit MAC
    D7A_NLS_AES_CBC_MAC_128,
    /// No encryption, Authentication, Cipher-block chaining with 64 bit MAC
    D7A_NLS_AES_CBC_MAC_64,
    /// No encryption, Authentication, Cipher-block chaining with 32 bit MAC
    D7A_NLS_AES_CBC_MAC_32,
    /// Authentication with CBC-MAC-128 and Encryption with Counter Mode
    D7A_NLS_AES_CCM_128,
    /// Authentication with CBC-MAC-64 and Encryption with Counter Mode
    D7A_NLS_AES_CCM_64,
    /// Authentication with CBC-MAC-32 and Encryption with Counter Mode
    D7A_NLS_AES_CCM_32,
    /// QTY
    D7A_NLS_QTY

} d7a_nls_t;


//======================================================================
// Structures
//======================================================================

//======================================================================
// d7a_com_config_t
//----------------------------------------------------------------------
/// Com port configuration structure
//======================================================================
typedef struct {
     /// Tx pin
     PinName tx;
     /// RX pin
     PinName rx;
     /// WKUP pin
     PinName rts;
     /// HST_WKUP pin
     PinName cts;
     /// Size of RX buffer
     uint16_t rx_buffer_size;
} d7a_com_config_t;

typedef uint32_t (*WriteFileFunction)(  const uint8_t file_id,
                                        const uint16_t offset,
                                        const uint16_t size,
                                        const uint8_t* const content);
                                            
typedef uint32_t (*ReadFileFunction)(   const uint8_t file_id,
                                        const uint16_t offset,
                                        const uint16_t size,
                                        uint8_t* buf);

//======================================================================
// d7a_fs_callbacks_t
//----------------------------------------------------------------------
/// File system callbacks
//======================================================================
typedef struct {
    /// Write in local file
    WriteFileFunction   write_file;
    /// Read from local file
    ReadFileFunction    read_file;
} d7a_fs_callbacks_t;

//======================================================================
// fw_version_t
//----------------------------------------------------------------------
/// Firmware version Structure
/// Used within the revision structure
//======================================================================
TYPEDEF_STRUCT_PACKED
{
    /// Software identifier
    uint8_t  id;
    /// Version major
    uint8_t  major;
    /// Version minor
    uint8_t  minor;
    /// Version patch
    uint16_t patch;
    /// Version hash
    uint32_t hash;
} fw_version_t;

//======================================================================
// d7a_revision_t
//----------------------------------------------------------------------
/// Revision Structure
///
/// Usage within D7B server:
/// An XML describing the File system of a device is associated to a
/// couple manufacturer_id/device_id (==Device).
/// Different versions of the Device's XML can exist and can be mapped
/// according to fw_version id/major/minor
//======================================================================
TYPEDEF_STRUCT_PACKED
{
    /// Manufacturer ID: provided by Wizzilab
    //  comes from: here
    uint32_t manufacturer_id;
    /// Device ID: Arbitrary number, at user/customer choice
    //  comes from: application
    uint32_t device_id;
    /// Hardware Board ID:
    //  comes from: board definition
    uint32_t hw_version;
    /// Firmware Version: made of
    ///  - major,minor and patch indexes : comes from versioning tool
    ///  - fw_id : "build-flavour" : comes from build setup
    ///  FW_ID | MAJOR | MINOR | PATCH | HASH |
    ///    1B  |  1B   |  1B   |   2B  |  4B  |
    fw_version_t fw_version;
    /// "file-system" signature XXX: to be worked out
    //  comes from: application
    uint32_t fs_crc;
} d7a_revision_t;


// =======================================================================
// d7a_addressee_ctrl_t
// -----------------------------------------------------------------------
/// Bitfield structure of the Addressee control byte
// =======================================================================
typedef union
{
    // bit access fields
    struct {
        /// Network security method
        uint8_t nls      : 4;
        /// ID type
        uint8_t idf      : 2;
        /// RFU
        uint8_t rfu_6    : 1;
        uint8_t rfu_7    : 1;
    } bf;

    // byte access
    uint8_t byte;

} d7a_addressee_ctrl_t;

// =======================================================================
// d7a_xcl_t
// -----------------------------------------------------------------------
/// Bitfield structure of the Addressee Access Class
// =======================================================================
typedef union
{
    // bit access fields
    struct {
        /// Subclass mask
        uint8_t m    : 4;
        /// Specifier
        uint8_t s    : 4;
    } bf;

    // byte access
    uint8_t byte;

} d7a_xcl_t;

// =======================================================================
// d7a_addressee_t
// -----------------------------------------------------------------------
/// Structure of the D7ATP Addressee byte
// =======================================================================
TYPEDEF_STRUCT_PACKED
{
    d7a_addressee_ctrl_t ctrl;
    d7a_xcl_t xcl;
    uint8_t id[D7A_UID_LEN];

} d7a_addressee_t;


//======================================================================
// Prototypes
//======================================================================

//======================================================================
// d7a_open
//----------------------------------------------------------------------
/// @brief                      Open D7A driver and start the modem
/// @param d7a_com_config_t*    Com port configuration structure
/// @param PinName              Reset pin
/// @param d7a_fs_callbacks_t*  File system callbacks (You cannot use local files if this is not specified)
//======================================================================
void d7a_open(const d7a_com_config_t* com_config, PinName reset_pin = NC, const d7a_fs_callbacks_t* fs_callbacks = NULL);

//======================================================================
// d7a_close
//----------------------------------------------------------------------
/// @brief                      Close D7A driver and stop the modem
//======================================================================
void d7a_close(void);

//======================================================================
// d7a_start
//----------------------------------------------------------------------
/// @brief                      Start the modem
/// @return bool                true if error
//======================================================================
bool d7a_start(void);

//======================================================================
// d7a_stop
//----------------------------------------------------------------------
/// @brief                      Stop the modem (goes to low power)
/// @return bool                true if error
//======================================================================
bool d7a_stop(void);

//======================================================================
// d7a_create
//----------------------------------------------------------------------
/// @brief                      Creates a file on the modem
/// @param d7a_fs_storage_t     Type of file
/// @param uint8_t              Access permissions
/// @param uint32_t             Length of the created file
/// @param uint32_t             Maximum size of the file
/// @param uint8_t              File ID to an eventual Action file
/// @param uint8_t              File ID to an eventual Interface file
/// @return bool                true if error
//======================================================================
bool d7a_create(const uint8_t file_id, d7a_fs_storage_t prop, d7a_fs_perm_t perm, uint32_t size, uint32_t alloc, uint8_t action_file = 0, uint8_t interface = 0);

//======================================================================
// d7a_declare
//----------------------------------------------------------------------
/// @brief                      Declare a file stocked on the host to the modem (need to have implemented the fs_callbacks)
/// @param uint8_t              File ID of file to declare
/// @param d7a_fs_storage_t     Type of file
/// @param uint8_t              Access permissions
/// @param uint32_t             Length of the created file
/// @param uint32_t             Maximum size of the file
/// @param uint8_t              File ID to an eventual Action file
/// @param uint8_t              File ID to an eventual Interface file
/// @return bool                true if error
//======================================================================
bool d7a_declare(const uint8_t file_id, d7a_fs_storage_t prop, d7a_fs_perm_t perm, uint32_t size, uint32_t alloc, uint8_t action_file = 0, uint8_t interface = 0);

//======================================================================
// d7a_read
//----------------------------------------------------------------------
/// @brief                      Read data from a file
/// @param uint8_t              File ID of file to read
/// @param uint32_t             Offset from which to start reading
/// @param uint32_t             Size of data to read
/// @param uint8_t*             Buffer to retrieve data
/// @return bool                true if error
//======================================================================
bool d7a_read(const uint8_t file_id, const uint32_t offset, const uint32_t size, const uint8_t* buf, d7a_addressee_t* addressee = NULL, uint8_t retry = 0, bool resp = true);

//======================================================================
// d7a_write
//----------------------------------------------------------------------
/// @brief                      Write data to a file
/// @param uint8_t              File ID of file to write
/// @param uint32_t             Offset from which to start writing
/// @param uint32_t             Size of data to write
/// @param uint8_t*             Buffer of the data to write
/// @return bool                true if error
//======================================================================
bool d7a_write(const uint8_t file_id, const uint32_t offset, const uint32_t size, const uint8_t* const buf, d7a_addressee_t* addressee = NULL, uint8_t retry = 0, bool resp = true);

#endif // _D7A_H_