Trond Enger / d7a_1x

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of d7a_1x by WizziLab

include/d7a.h@43:28202405094d, 2016-08-30 (annotated)

Committer:
Jeej
Date:
Tue Aug 30 16:59:12 2016 +0000
Revision:
43:28202405094d
Child:
45:b85384e7d825
New version of the API.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Jeej 43:28202405094d 1 #ifndef _D7A_H_
Jeej 43:28202405094d 2 #define _D7A_H_
Jeej 43:28202405094d 3
Jeej 43:28202405094d 4 #include "d7a_common.h"
Jeej 43:28202405094d 5
Jeej 43:28202405094d 6
Jeej 43:28202405094d 7 //======================================================================
Jeej 43:28202405094d 8 // Defines
Jeej 43:28202405094d 9 //======================================================================
Jeej 43:28202405094d 10
Jeej 43:28202405094d 11 #define D7A_UID_LEN (8)
Jeej 43:28202405094d 12
Jeej 43:28202405094d 13
Jeej 43:28202405094d 14 //======================================================================
Jeej 43:28202405094d 15 // Enums
Jeej 43:28202405094d 16 //======================================================================
Jeej 43:28202405094d 17
Jeej 43:28202405094d 18 //======================================================================
Jeej 43:28202405094d 19 // d7a_fs_storage_t
Jeej 43:28202405094d 20 //----------------------------------------------------------------------
Jeej 43:28202405094d 21 /// File "Storage Class"
Jeej 43:28202405094d 22 //======================================================================
Jeej 43:28202405094d 23 typedef enum {
Jeej 43:28202405094d 24 /// No data is keeped. Can only write in it.
Jeej 43:28202405094d 25 /// Ex: Use for commands.
Jeej 43:28202405094d 26 TRANSIENT = 0,
Jeej 43:28202405094d 27 /// Data is stocked in RAM and initialized at 0.
Jeej 43:28202405094d 28 /// Can not guarantee data integrity over time.
Jeej 43:28202405094d 29 /// Ex: Use for often updated data.
Jeej 43:28202405094d 30 VOLATILE,
Jeej 43:28202405094d 31 /// Data is stocked in RAM and initialized with the last flushed data from EEPROM.
Jeej 43:28202405094d 32 /// Can not guarantee data integrity over time.
Jeej 43:28202405094d 33 /// Ex: Use for temporary configurations.
Jeej 43:28202405094d 34 RESTORABLE,
Jeej 43:28202405094d 35 /// Data is stoked in EEPROM.
Jeej 43:28202405094d 36 /// Data integrity is guaranteed.
Jeej 43:28202405094d 37 /// Ex: Use for important configurations.
Jeej 43:28202405094d 38 /// /!\ Use sparingly as operations on these type of files are time and ressource consuming
Jeej 43:28202405094d 39 PERMANENT
Jeej 43:28202405094d 40 } d7a_fs_storage_t;
Jeej 43:28202405094d 41
Jeej 43:28202405094d 42 //======================================================================
Jeej 43:28202405094d 43 // d7a_fs_perm_t
Jeej 43:28202405094d 44 //----------------------------------------------------------------------
Jeej 43:28202405094d 45 /// File permissions for USER/GUEST
Jeej 43:28202405094d 46 //======================================================================
Jeej 43:28202405094d 47 typedef enum {
Jeej 43:28202405094d 48 O_O = 0b00000000,
Jeej 43:28202405094d 49 R_O = 0b00100000,
Jeej 43:28202405094d 50 R_R = 0b00100100,
Jeej 43:28202405094d 51 W_O = 0b00010000,
Jeej 43:28202405094d 52 W_W = 0b00010010,
Jeej 43:28202405094d 53 RW_O = 0b00110000,
Jeej 43:28202405094d 54 RW_R = 0b00110100,
Jeej 43:28202405094d 55 RW_W = 0b00110010,
Jeej 43:28202405094d 56 RW_RW = 0b00110110,
Jeej 43:28202405094d 57 RWX_O = 0b00111000,
Jeej 43:28202405094d 58 RWX_RWX = 0b00111111,
Jeej 43:28202405094d 59 } d7a_fs_perm_t;
Jeej 43:28202405094d 60
Jeej 43:28202405094d 61 // =======================================================================
Jeej 43:28202405094d 62 // d7a_nls_t
Jeej 43:28202405094d 63 // -----------------------------------------------------------------------
Jeej 43:28202405094d 64 /// Enumerator of the NWL security modes
Jeej 43:28202405094d 65 // =======================================================================
Jeej 43:28202405094d 66 typedef enum
Jeej 43:28202405094d 67 {
Jeej 43:28202405094d 68 /// No security enabled
Jeej 43:28202405094d 69 D7A_NLS_NO = 0,
Jeej 43:28202405094d 70 /// Encryption only, Counter Mode
Jeej 43:28202405094d 71 D7A_NLS_AES_CTR,
Jeej 43:28202405094d 72 /// No encryption, Authentication, Cipher-block chaining with 128 bit MAC
Jeej 43:28202405094d 73 D7A_NLS_AES_CBC_MAC_128,
Jeej 43:28202405094d 74 /// No encryption, Authentication, Cipher-block chaining with 64 bit MAC
Jeej 43:28202405094d 75 D7A_NLS_AES_CBC_MAC_64,
Jeej 43:28202405094d 76 /// No encryption, Authentication, Cipher-block chaining with 32 bit MAC
Jeej 43:28202405094d 77 D7A_NLS_AES_CBC_MAC_32,
Jeej 43:28202405094d 78 /// Authentication with CBC-MAC-128 and Encryption with Counter Mode
Jeej 43:28202405094d 79 D7A_NLS_AES_CCM_128,
Jeej 43:28202405094d 80 /// Authentication with CBC-MAC-64 and Encryption with Counter Mode
Jeej 43:28202405094d 81 D7A_NLS_AES_CCM_64,
Jeej 43:28202405094d 82 /// Authentication with CBC-MAC-32 and Encryption with Counter Mode
Jeej 43:28202405094d 83 D7A_NLS_AES_CCM_32,
Jeej 43:28202405094d 84 /// QTY
Jeej 43:28202405094d 85 D7A_NLS_QTY
Jeej 43:28202405094d 86
Jeej 43:28202405094d 87 } d7a_nls_t;
Jeej 43:28202405094d 88
Jeej 43:28202405094d 89
Jeej 43:28202405094d 90 //======================================================================
Jeej 43:28202405094d 91 // Structures
Jeej 43:28202405094d 92 //======================================================================
Jeej 43:28202405094d 93
Jeej 43:28202405094d 94 //======================================================================
Jeej 43:28202405094d 95 // d7a_com_config_t
Jeej 43:28202405094d 96 //----------------------------------------------------------------------
Jeej 43:28202405094d 97 /// Com port configuration structure
Jeej 43:28202405094d 98 //======================================================================
Jeej 43:28202405094d 99 typedef struct {
Jeej 43:28202405094d 100 /// Tx pin
Jeej 43:28202405094d 101 PinName tx;
Jeej 43:28202405094d 102 /// RX pin
Jeej 43:28202405094d 103 PinName rx;
Jeej 43:28202405094d 104 /// WKUP pin
Jeej 43:28202405094d 105 PinName rts;
Jeej 43:28202405094d 106 /// HST_WKUP pin
Jeej 43:28202405094d 107 PinName cts;
Jeej 43:28202405094d 108 /// Size of RX buffer
Jeej 43:28202405094d 109 uint16_t rx_buffer_size;
Jeej 43:28202405094d 110 } d7a_com_config_t;
Jeej 43:28202405094d 111
Jeej 43:28202405094d 112 typedef uint32_t (*WriteFileFunction)( const uint8_t file_id,
Jeej 43:28202405094d 113 const uint16_t offset,
Jeej 43:28202405094d 114 const uint16_t size,
Jeej 43:28202405094d 115 const uint8_t* const content);
Jeej 43:28202405094d 116
Jeej 43:28202405094d 117 typedef uint32_t (*ReadFileFunction)( const uint8_t file_id,
Jeej 43:28202405094d 118 const uint16_t offset,
Jeej 43:28202405094d 119 const uint16_t size,
Jeej 43:28202405094d 120 uint8_t* buf);
Jeej 43:28202405094d 121
Jeej 43:28202405094d 122 //======================================================================
Jeej 43:28202405094d 123 // d7a_fs_callbacks_t
Jeej 43:28202405094d 124 //----------------------------------------------------------------------
Jeej 43:28202405094d 125 /// File system callbacks
Jeej 43:28202405094d 126 //======================================================================
Jeej 43:28202405094d 127 typedef struct {
Jeej 43:28202405094d 128 /// Write in local file
Jeej 43:28202405094d 129 WriteFileFunction write_file;
Jeej 43:28202405094d 130 /// Read from local file
Jeej 43:28202405094d 131 ReadFileFunction read_file;
Jeej 43:28202405094d 132 } d7a_fs_callbacks_t;
Jeej 43:28202405094d 133
Jeej 43:28202405094d 134 //======================================================================
Jeej 43:28202405094d 135 // fw_version_t
Jeej 43:28202405094d 136 //----------------------------------------------------------------------
Jeej 43:28202405094d 137 /// Firmware version Structure
Jeej 43:28202405094d 138 /// Used within the revision structure
Jeej 43:28202405094d 139 //======================================================================
Jeej 43:28202405094d 140 TYPEDEF_STRUCT_PACKED
Jeej 43:28202405094d 141 {
Jeej 43:28202405094d 142 /// Software identifier
Jeej 43:28202405094d 143 uint8_t id;
Jeej 43:28202405094d 144 /// Version major
Jeej 43:28202405094d 145 uint8_t major;
Jeej 43:28202405094d 146 /// Version minor
Jeej 43:28202405094d 147 uint8_t minor;
Jeej 43:28202405094d 148 /// Version patch
Jeej 43:28202405094d 149 uint16_t patch;
Jeej 43:28202405094d 150 /// Version hash
Jeej 43:28202405094d 151 uint32_t hash;
Jeej 43:28202405094d 152 } fw_version_t;
Jeej 43:28202405094d 153
Jeej 43:28202405094d 154 //======================================================================
Jeej 43:28202405094d 155 // d7a_revision_t
Jeej 43:28202405094d 156 //----------------------------------------------------------------------
Jeej 43:28202405094d 157 /// Revision Structure
Jeej 43:28202405094d 158 ///
Jeej 43:28202405094d 159 /// Usage within D7B server:
Jeej 43:28202405094d 160 /// An XML describing the File system of a device is associated to a
Jeej 43:28202405094d 161 /// couple manufacturer_id/device_id (==Device).
Jeej 43:28202405094d 162 /// Different versions of the Device's XML can exist and can be mapped
Jeej 43:28202405094d 163 /// according to fw_version id/major/minor
Jeej 43:28202405094d 164 //======================================================================
Jeej 43:28202405094d 165 TYPEDEF_STRUCT_PACKED
Jeej 43:28202405094d 166 {
Jeej 43:28202405094d 167 /// Manufacturer ID: provided by Wizzilab
Jeej 43:28202405094d 168 // comes from: here
Jeej 43:28202405094d 169 uint32_t manufacturer_id;
Jeej 43:28202405094d 170 /// Device ID: Arbitrary number, at user/customer choice
Jeej 43:28202405094d 171 // comes from: application
Jeej 43:28202405094d 172 uint32_t device_id;
Jeej 43:28202405094d 173 /// Hardware Board ID:
Jeej 43:28202405094d 174 // comes from: board definition
Jeej 43:28202405094d 175 uint32_t hw_version;
Jeej 43:28202405094d 176 /// Firmware Version: made of
Jeej 43:28202405094d 177 /// - major,minor and patch indexes : comes from versioning tool
Jeej 43:28202405094d 178 /// - fw_id : "build-flavour" : comes from build setup
Jeej 43:28202405094d 179 /// FW_ID | MAJOR | MINOR | PATCH | HASH |
Jeej 43:28202405094d 180 /// 1B | 1B | 1B | 2B | 4B |
Jeej 43:28202405094d 181 fw_version_t fw_version;
Jeej 43:28202405094d 182 /// "file-system" signature XXX: to be worked out
Jeej 43:28202405094d 183 // comes from: application
Jeej 43:28202405094d 184 uint32_t fs_crc;
Jeej 43:28202405094d 185 } d7a_revision_t;
Jeej 43:28202405094d 186
Jeej 43:28202405094d 187
Jeej 43:28202405094d 188 // =======================================================================
Jeej 43:28202405094d 189 // d7a_addressee_ctrl_t
Jeej 43:28202405094d 190 // -----------------------------------------------------------------------
Jeej 43:28202405094d 191 /// Bitfield structure of the Addressee control byte
Jeej 43:28202405094d 192 // =======================================================================
Jeej 43:28202405094d 193 typedef union
Jeej 43:28202405094d 194 {
Jeej 43:28202405094d 195 // bit access fields
Jeej 43:28202405094d 196 struct {
Jeej 43:28202405094d 197 /// Network security method
Jeej 43:28202405094d 198 uint8_t nls : 4;
Jeej 43:28202405094d 199 /// ID type
Jeej 43:28202405094d 200 uint8_t idf : 2;
Jeej 43:28202405094d 201 /// RFU
Jeej 43:28202405094d 202 uint8_t rfu_6 : 1;
Jeej 43:28202405094d 203 uint8_t rfu_7 : 1;
Jeej 43:28202405094d 204 } bf;
Jeej 43:28202405094d 205
Jeej 43:28202405094d 206 // byte access
Jeej 43:28202405094d 207 uint8_t byte;
Jeej 43:28202405094d 208
Jeej 43:28202405094d 209 } d7a_addressee_ctrl_t;
Jeej 43:28202405094d 210
Jeej 43:28202405094d 211 // =======================================================================
Jeej 43:28202405094d 212 // d7a_xcl_t
Jeej 43:28202405094d 213 // -----------------------------------------------------------------------
Jeej 43:28202405094d 214 /// Bitfield structure of the Addressee Access Class
Jeej 43:28202405094d 215 // =======================================================================
Jeej 43:28202405094d 216 typedef union
Jeej 43:28202405094d 217 {
Jeej 43:28202405094d 218 // bit access fields
Jeej 43:28202405094d 219 struct {
Jeej 43:28202405094d 220 /// Subclass mask
Jeej 43:28202405094d 221 uint8_t m : 4;
Jeej 43:28202405094d 222 /// Specifier
Jeej 43:28202405094d 223 uint8_t s : 4;
Jeej 43:28202405094d 224 } bf;
Jeej 43:28202405094d 225
Jeej 43:28202405094d 226 // byte access
Jeej 43:28202405094d 227 uint8_t byte;
Jeej 43:28202405094d 228
Jeej 43:28202405094d 229 } d7a_xcl_t;
Jeej 43:28202405094d 230
Jeej 43:28202405094d 231 // =======================================================================
Jeej 43:28202405094d 232 // d7a_addressee_t
Jeej 43:28202405094d 233 // -----------------------------------------------------------------------
Jeej 43:28202405094d 234 /// Structure of the D7ATP Addressee byte
Jeej 43:28202405094d 235 // =======================================================================
Jeej 43:28202405094d 236 TYPEDEF_STRUCT_PACKED
Jeej 43:28202405094d 237 {
Jeej 43:28202405094d 238 d7a_addressee_ctrl_t ctrl;
Jeej 43:28202405094d 239 d7a_xcl_t xcl;
Jeej 43:28202405094d 240 uint8_t id[D7A_UID_LEN];
Jeej 43:28202405094d 241
Jeej 43:28202405094d 242 } d7a_addressee_t;
Jeej 43:28202405094d 243
Jeej 43:28202405094d 244
Jeej 43:28202405094d 245 //======================================================================
Jeej 43:28202405094d 246 // Prototypes
Jeej 43:28202405094d 247 //======================================================================
Jeej 43:28202405094d 248
Jeej 43:28202405094d 249 //======================================================================
Jeej 43:28202405094d 250 // d7a_open
Jeej 43:28202405094d 251 //----------------------------------------------------------------------
Jeej 43:28202405094d 252 /// @brief Open D7A driver and start the modem
Jeej 43:28202405094d 253 /// @param d7a_com_config_t* Com port configuration structure
Jeej 43:28202405094d 254 /// @param PinName Reset pin
Jeej 43:28202405094d 255 /// @param d7a_fs_callbacks_t* File system callbacks (You cannot use local files if this is not specified)
Jeej 43:28202405094d 256 //======================================================================
Jeej 43:28202405094d 257 void d7a_open(const d7a_com_config_t* com_config, PinName reset_pin = NC, const d7a_fs_callbacks_t* fs_callbacks = NULL);
Jeej 43:28202405094d 258
Jeej 43:28202405094d 259 //======================================================================
Jeej 43:28202405094d 260 // d7a_close
Jeej 43:28202405094d 261 //----------------------------------------------------------------------
Jeej 43:28202405094d 262 /// @brief Close D7A driver and stop the modem
Jeej 43:28202405094d 263 //======================================================================
Jeej 43:28202405094d 264 void d7a_close(void);
Jeej 43:28202405094d 265
Jeej 43:28202405094d 266 //======================================================================
Jeej 43:28202405094d 267 // d7a_start
Jeej 43:28202405094d 268 //----------------------------------------------------------------------
Jeej 43:28202405094d 269 /// @brief Start the modem
Jeej 43:28202405094d 270 /// @return bool true if error
Jeej 43:28202405094d 271 //======================================================================
Jeej 43:28202405094d 272 bool d7a_start(void);
Jeej 43:28202405094d 273
Jeej 43:28202405094d 274 //======================================================================
Jeej 43:28202405094d 275 // d7a_stop
Jeej 43:28202405094d 276 //----------------------------------------------------------------------
Jeej 43:28202405094d 277 /// @brief Stop the modem (goes to low power)
Jeej 43:28202405094d 278 /// @return bool true if error
Jeej 43:28202405094d 279 //======================================================================
Jeej 43:28202405094d 280 bool d7a_stop(void);
Jeej 43:28202405094d 281
Jeej 43:28202405094d 282 //======================================================================
Jeej 43:28202405094d 283 // d7a_create
Jeej 43:28202405094d 284 //----------------------------------------------------------------------
Jeej 43:28202405094d 285 /// @brief Creates a file on the modem
Jeej 43:28202405094d 286 /// @param d7a_fs_storage_t Type of file
Jeej 43:28202405094d 287 /// @param uint8_t Access permissions
Jeej 43:28202405094d 288 /// @param uint32_t Length of the created file
Jeej 43:28202405094d 289 /// @param uint32_t Maximum size of the file
Jeej 43:28202405094d 290 /// @param uint8_t File ID to an eventual Action file
Jeej 43:28202405094d 291 /// @param uint8_t File ID to an eventual Interface file
Jeej 43:28202405094d 292 /// @return bool true if error
Jeej 43:28202405094d 293 //======================================================================
Jeej 43:28202405094d 294 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);
Jeej 43:28202405094d 295
Jeej 43:28202405094d 296 //======================================================================
Jeej 43:28202405094d 297 // d7a_declare
Jeej 43:28202405094d 298 //----------------------------------------------------------------------
Jeej 43:28202405094d 299 /// @brief Declare a file stocked on the host to the modem (need to have implemented the fs_callbacks)
Jeej 43:28202405094d 300 /// @param uint8_t File ID of file to declare
Jeej 43:28202405094d 301 /// @param d7a_fs_storage_t Type of file
Jeej 43:28202405094d 302 /// @param uint8_t Access permissions
Jeej 43:28202405094d 303 /// @param uint32_t Length of the created file
Jeej 43:28202405094d 304 /// @param uint32_t Maximum size of the file
Jeej 43:28202405094d 305 /// @param uint8_t File ID to an eventual Action file
Jeej 43:28202405094d 306 /// @param uint8_t File ID to an eventual Interface file
Jeej 43:28202405094d 307 /// @return bool true if error
Jeej 43:28202405094d 308 //======================================================================
Jeej 43:28202405094d 309 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);
Jeej 43:28202405094d 310
Jeej 43:28202405094d 311 //======================================================================
Jeej 43:28202405094d 312 // d7a_read
Jeej 43:28202405094d 313 //----------------------------------------------------------------------
Jeej 43:28202405094d 314 /// @brief Read data from a file
Jeej 43:28202405094d 315 /// @param uint8_t File ID of file to read
Jeej 43:28202405094d 316 /// @param uint32_t Offset from which to start reading
Jeej 43:28202405094d 317 /// @param uint32_t Size of data to read
Jeej 43:28202405094d 318 /// @param uint8_t* Buffer to retrieve data
Jeej 43:28202405094d 319 /// @return bool true if error
Jeej 43:28202405094d 320 //======================================================================
Jeej 43:28202405094d 321 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);
Jeej 43:28202405094d 322
Jeej 43:28202405094d 323 //======================================================================
Jeej 43:28202405094d 324 // d7a_write
Jeej 43:28202405094d 325 //----------------------------------------------------------------------
Jeej 43:28202405094d 326 /// @brief Write data to a file
Jeej 43:28202405094d 327 /// @param uint8_t File ID of file to write
Jeej 43:28202405094d 328 /// @param uint32_t Offset from which to start writing
Jeej 43:28202405094d 329 /// @param uint32_t Size of data to write
Jeej 43:28202405094d 330 /// @param uint8_t* Buffer of the data to write
Jeej 43:28202405094d 331 /// @return bool true if error
Jeej 43:28202405094d 332 //======================================================================
Jeej 43:28202405094d 333 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);
Jeej 43:28202405094d 334
Jeej 43:28202405094d 335 #endif // _D7A_H_