Diff: include/d7a.h

Revision:

43:28202405094d

Child:

45:b85384e7d825

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/include/d7a.h	Tue Aug 30 16:59:12 2016 +0000
@@ -0,0 +1,335 @@
+#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_
\ No newline at end of file