1 /* 2 * Copyright 2018 Oticon A/S 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 #ifndef BS_P2G4_TYPES_H 7 #define BS_P2G4_TYPES_H 8 9 #include "bs_types.h" 10 #include "bs_pc_base_types.h" 11 #include "bs_pc_2G4_modulations.h" 12 13 #ifdef __cplusplus 14 extern "C"{ 15 #endif 16 17 /* 18 * From 0.0 to 80.0 in which frequency is the transmission centered 19 * format 8.8 in MHz, offset relative to 2400 20 * (can be negative for blockers < 2400) 21 */ 22 typedef int16_t p2G4_freq_t; 23 #define P2G4_freq_FRACB 8 24 #define P2G4_INVALID_FREQ 0x7FFF 25 26 /* Power level in dBm or gain in dB (depending on context). 27 * Format 8.8 (-128.0 .. 127.99609375)*/ 28 typedef int16_t p2G4_power_t; 29 #define P2G4_POWER_MIN INT16_MIN 30 /* RSSI measured power level in dBm, format signed 16.16 31 * from -32768.0 .. 32768-1/2^16 dBm with a resolution of 1/2^16 = 1.5e-5dBm */ 32 typedef int32_t p2G4_rssi_power_t; 33 #define P2G4_RSSI_POWER_MIN INT32_MIN 34 35 typedef uint16_t p2G4_modulation_t; 36 37 #define P2G4_RXV2_MAX_ADDRESSES 16 38 typedef uint64_t p2G4_address_t; 39 40 typedef struct __attribute__ ((packed)) { 41 /* At this point the Tx/Rx will be stopped abruptly 42 * If not used, set to TIME_NEVER */ 43 bs_time_t abort_time; 44 /* Time in which the phy should check if the device wants 45 * to change its mind regarding the next abort time. 46 * If not used set to TIME_NEVER */ 47 bs_time_t recheck_time; 48 } p2G4_abort_t; 49 50 typedef struct __attribute__ ((packed)) { 51 /* One of P2G4_MOD_* */ 52 p2G4_modulation_t modulation; 53 /* Carrier frequency */ 54 p2G4_freq_t center_freq; 55 } p2G4_radioparams_t; 56 57 typedef struct __attribute__ ((packed)) { 58 /* Absolute microsecond when the measurement should be taken */ 59 bs_time_t meas_time; 60 p2G4_radioparams_t radio_params; 61 p2G4_power_t antenna_gain; 62 } p2G4_rssi_t ; 63 64 typedef struct __attribute__ ((packed)) { 65 /* RSSI measured value by the modem */ 66 p2G4_rssi_power_t RSSI; 67 } p2G4_rssi_done_t; 68 69 typedef struct __attribute__ ((packed)) { 70 /* Absolute us when the receiver starts scanning */ 71 bs_time_t start_time; 72 /* Time in which we need to get a preamble + address match before giving up 73 * Once we get a preamble + address match we will continue to receive the 74 * whole packet, unless there is a header error. 75 * We scan in the range [ start_time, start_time + scan_duration - 1] us */ 76 uint32_t scan_duration; 77 /* Address we search for */ 78 uint32_t phy_address; 79 p2G4_radioparams_t radio_params; 80 p2G4_power_t antenna_gain; 81 /* Reception tolerance: */ 82 /* How many errors do we accept before considering the preamble + address sync lost 83 * (if there is less errors than this the packet can be received correctly) */ 84 uint16_t sync_threshold; 85 /* How many errors do we accept in the header before giving a header error 86 * (automatically in the phy) 87 * Note: any header error will result at least in a CRC error 88 */ 89 uint16_t header_threshold; 90 /* Packet parameters: */ 91 /*in us, duration of the preamble and start flag */ 92 uint16_t pream_and_addr_duration; 93 /* in us duration of the BLE header */ 94 uint16_t header_duration; 95 /* 96 * Data rate in bits per second 97 */ 98 uint32_t bps; 99 /* 100 * Structure defining when the device may want to abort the reception 101 * Note: abort_time shall be > start_time 102 */ 103 p2G4_abort_t abort; 104 } p2G4_rx_t; 105 106 typedef struct __attribute__ ((packed)) { 107 /* absolute us when the first bit of the packet is sent to the air 108 * = the begining of the preamble */ 109 bs_time_t start_time; 110 /* absolute us when the last bit of the packet is sent to the air */ 111 bs_time_t end_time; 112 /* 113 * Structure defining when the device may want to abort the transmission 114 * Note: abort_time shall be > start_time 115 */ 116 p2G4_abort_t abort; 117 /* Phy address/access code used in the packet */ 118 uint32_t phy_address; 119 p2G4_radioparams_t radio_params; 120 /* In dBm, transmitter power level (including antenna gain) */ 121 p2G4_power_t power_level; 122 /* Packet size in bytes; Only used for moving the payload, not modeling related */ 123 uint16_t packet_size; 124 } p2G4_tx_t; 125 126 typedef struct __attribute__ ((packed)) { 127 /* one of P2G4_RXSTATUS* */ 128 uint16_t status; 129 /* Found packet size in bytes */ 130 uint16_t packet_size; 131 /* if Status != P2G4_RXSTATUS_NOSYNC: absolute us when the address ended. 132 * otherwise when the scan window ended */ 133 bs_time_t rx_time_stamp; 134 /* Absolute us this message is sent */ 135 bs_time_t end_time; 136 /* RSSI measured values by the modem */ 137 p2G4_rssi_done_t rssi; 138 } p2G4_rx_done_t; 139 140 #define P2G4_RXSTATUS_OK 0x1 141 #define P2G4_RXSTATUS_CRC_ERROR 0x2 /* At least 1 bit error was detected during the header or payload */ 142 #define P2G4_RXSTATUS_PACKET_CONTENT_ERROR 0x2 /* Rename of CRC_ERROR */ 143 #define P2G4_RXSTATUS_HEADER_ERROR 0x3 /* More bit errors found during header than <header_threshold> */ 144 #define P2G4_RXSTATUS_NOSYNC 0x4 /*Nothing was synchronized*/ 145 #define P2G4_RXSTATUS_INPROGRESS 0x5 /*The reception is/was ongoing*/ 146 147 typedef struct __attribute__ ((packed)) { 148 /* absolute us this message is sent */ 149 bs_time_t end_time; 150 } p2G4_tx_done_t; 151 152 153 /************************************************************ 154 * V2 API extension 155 * In *Alpha* state, API backward/forward compatibility NOT guaranteed. 156 * API breaking changes can be expected in future releases 157 * 158 * This includes: 159 * * Txv2 procedure p2G4_txv2_t (followed by p2G4_tx_done_t) 160 * * Rxv2 procedure p2G4_rxv2_t & p2G4_rxv2_done_t 161 * * CCA search procedure p2G4_search_comp_mod_done_t & p2G4_search_comp_mod_t 162 * 163 * Note this API includes the Txv2 and Rxv2 procedures which provide 164 * a superset of the functionality their v1 counterparts supported 165 * The v1 and v2 procedures are fully cross-compatible 166 * (within the limitation imposed by the v1 party) 167 * 168 * The v1 API is NOT deprecated: 169 * Devices utilizing the v1 API are not expected to migrate to the 170 * new API, and are discouraged from doing so while the 171 * API is in alpha and beta state. 172 ************************************************************/ 173 174 typedef struct __attribute__ ((packed)) { 175 /* Absolute us when the transmittion starts. 176 * This will typically be the same as start_packet_time. 177 * But, it may be: 178 * * Earlier, if the transmitter starts emitting a spurious carrier 179 * or similar before the actual packet start 180 * * The transmitter eats into the preamble by ramping up too late 181 * 182 * Note: The device must send this request no later than the Phy simulated time start_tx_time 183 */ 184 bs_time_t start_tx_time; 185 /* Absolute us when the transmitter stops transmitting 186 * This will typically be the same as end_packet_time. 187 * But, it may be: 188 * * Longer, if the transmitter continuous emitting a spurious carrier 189 * or desired (i.e. BLE CTE) after the actual packet end 190 */ 191 bs_time_t end_tx_time; 192 193 /* Absolute us when the first bit of a protocol compliant packet would be sent to the air 194 * i.e. typically the beginning of the preamble 195 * Note that a real transmitter may send some carrier/noise before this, 196 * or may be purposely configured to truncate the beginning of the preamble. 197 * Neither of these 2 effects should be reflected in this value 198 */ 199 bs_time_t start_packet_time; 200 /* Absolute us when the last bit of the packet is sent to the air 201 * Note that this should only include "data" bits, and not extra transmitted tones 202 * either desired (for ex. BLE CTE) or undesired (possible spurious tails/carrier) 203 */ 204 bs_time_t end_packet_time; 205 206 /* {Phy,access} {address,code}/{sync,start} {word,flag,delimiter} used in the packet 207 * If the protocol does not use it, or uses less than 64 bits 208 * you must set the unused bits to 0 209 * For BLE this should be set to the 32bit "access address" (not encoded in case of coded phy) 210 * For 802.15.4 this should be set to the 8 bit SFD 211 * For other protocols, the address may include more than just this, 212 * while both Tx and Rx agree by convention on what it includes. 213 */ 214 p2G4_address_t phy_address; 215 216 /* 217 * Structure defining when the device may want to abort the transmission 218 * Note: abort_time shall be > start_tx_time 219 */ 220 p2G4_abort_t abort; 221 222 p2G4_radioparams_t radio_params; 223 /* In dBm, transmitter power level (including antenna gain) */ 224 p2G4_power_t power_level; 225 226 /* (if coded) Which coding rate, the data is sent with 227 * Note that this is only used for a == or != check.*/ 228 uint16_t coding_rate; 229 230 /* Packet size in bytes; Only used for moving the payload, not modeling related */ 231 uint16_t packet_size; 232 233 /* Note: For mapping the old p2G4_tx_t API to this, 234 * start_tx_time = start_packet_time = v1 start_time 235 * end_tx_time = end_packet_time = v1 end_time 236 * phy_address is just 0 extended 237 * coding_rate = 0 238 */ 239 } p2G4_txv2_t; 240 241 242 typedef struct __attribute__ ((packed)) { 243 /* Absolute us when the receiver starts scanning */ 244 bs_time_t start_time; 245 246 /* 247 * Structure defining when the device may want to abort the reception 248 * Note: abort_time shall be > start_time 249 */ 250 p2G4_abort_t abort; 251 252 /* Time in which we need to get a preamble + address match before giving up 253 * Once we get a preamble + address match we will continue to receive the 254 * whole packet, unless there is a header error. 255 * We scan in the range [ start_time, start_time + scan_duration - 1] us */ 256 uint32_t scan_duration; 257 258 /* Duration of the packet the receiver will listen for. 259 * That is, for how long the receiver will be receiving bits, 260 * instead of during Tx.start_packet_time -> Tx.end_packet_time 261 * The receiver will think the packet lasts Tx.start_packet_time -> (Tx.start_packet_time+forced_packet_duration) 262 * A value of UINT32_MAX means it follows the Tx packet duration. 263 * Note: This is not a filter, but a way to model receivers mistakenly 264 * decoding the length or code/rate indication fields. 265 */ 266 uint32_t forced_packet_duration; 267 268 /* Error calculation rate, in times per second. 269 * Typically the data rate in bits per second (For binary FSK, PSK, ASK.. modulations) 270 * Note: This is just the bit error and SNR calculation rate. 271 * It does not affect the actual packet duration in any way. 272 * It is up to the receiver to set it in accordance with the type of modulation. 273 * For more complex modulations or coded packets, it may be the chip-rate, 274 * symbol-rate or coded-bit-rate */ 275 uint32_t error_calc_rate; 276 277 p2G4_radioparams_t radio_params; 278 279 p2G4_power_t antenna_gain; 280 281 /* (if coded) Which coding rate, the data is received with 282 * Note that this is only used for a == or != check.*/ 283 uint16_t coding_rate; 284 285 /* Packet parameters: */ 286 287 /* In us, duration of the preamble and start flag 288 * It can be set to zero */ 289 uint16_t pream_and_addr_duration; 290 291 /* In us duration of the "header". It can be 0. 292 * For uncoded BLE this correspond to the BLE header 293 * For 15.4 this should be set to 0 294 * For Nordic's ESB this should be set to the duration of 8 bits */ 295 uint16_t header_duration; 296 297 /* Reception tolerance: */ 298 299 /* How many us into the transmitted preamble we accept having opened the receiver in, 300 * and consider it is still possible to receive a packet 301 * 302 * Note: The missing piece of the preamble will NOT be counted as having "bit errors" 303 * for the sync_threshold calculation. Actually the receive procedure will just skip 304 * the whole acceptable_pre_truncation, and start checking for bit errors after. 305 * Note: acceptable_pre_truncation must be <= pream_and_addr_duration 306 */ 307 uint16_t acceptable_pre_truncation; 308 309 /* How many errors do we accept before considering the preamble + address sync lost */ 310 uint16_t sync_threshold; 311 312 /* How many errors do we accept in the header before giving a header error 313 * (automatically in the phy) 314 * Note: any header error will result at least in a CRC/packet error 315 */ 316 uint16_t header_threshold; 317 318 /* When set to 0 the Rx is not pre-locked. 319 * When set to 1, the Rx is already pre-locked. 320 * In that case, the Rx will not search for a transmitter but continue receiving from the last 321 * transmitter that it just was. 322 * The receiver will go directly to sync mode 323 * 324 * Note that in this case : 325 * * scan_duration should be set to pream_and_addr_duration + 1. 326 * * acceptable_pre_truncation should be set to 0 327 * * it may fail during sync depending on the sync_threshold and/or the transmitter disappearing. 328 * even if pream_and_addr_duration == 0 (an instantaneous check will be performed still). 329 * So if you do not want this to happen set sync_threshold high enough (for ex. UINT16_MAX) 330 * * Similarly it may fail during the header reception just like with a normal packet. 331 * * Any given phy_addr[] will be ignored. 332 */ 333 uint8_t prelocked_tx; 334 335 /* Requested type of response 336 * * 0: Basic response 337 * * (reserved) 1: Include also bit error mask 338 * * (reserved) all others 339 */ 340 uint8_t resp_type; 341 342 /* How many addresses we actively search for, must be >= 1 & < 8 343 * And how many elements of p2G4_address_t phy_addr[] follow */ 344 uint8_t n_addr; 345 346 /* Note: For mapping the old p2G4_rx_t API to this, 347 * n_addr = 1 348 * phy_address[0] = phy_address (0 extended) 349 * error_calc_rate = v1 bps 350 * acceptable_pre_truncation = 0 351 * resp_type = 0; 352 * forced_packet_duration = UINT32_MAX 353 * coding_rate = 0 354 */ 355 } p2G4_rxv2_t; 356 357 358 typedef struct __attribute__ ((packed)) { 359 /* if Status != P2G4_RXSTATUS_NOSYNC: absolute us when the address ended. 360 * otherwise when the scan window ended */ 361 bs_time_t rx_time_stamp; 362 /* Absolute us this message is sent */ 363 bs_time_t end_time; 364 365 /*Matched address (if any)*/ 366 p2G4_address_t phy_address; 367 368 /*The transmitter coding rate*/ 369 uint16_t coding_rate; 370 371 /* RSSI measured value by the modem */ 372 p2G4_rssi_done_t rssi; 373 374 /* one of P2G4_RXSTATUS* */ 375 uint16_t status; 376 /* Found packet size in bytes */ 377 uint16_t packet_size; 378 379 } p2G4_rxv2_done_t; 380 381 382 /** 383 * Search for a compatible modulation and/or 384 * do an average energy measurements on the channel 385 * Typically used for CCA procedures 386 */ 387 typedef struct __attribute__ ((packed)) { 388 /* Absolute us when the receiver starts */ 389 bs_time_t start_time; 390 391 /* 392 * Structure defining when the device may want to abort the reception 393 * Note: abort_time shall be > start_time 394 */ 395 p2G4_abort_t abort; 396 397 /* For how long the device will check for 398 * We scan in the range [ start_time, start_time + scan_duration - 1] us */ 399 uint32_t scan_duration; 400 401 /* Scan period 402 * How often the device wants to check 403 * The Phy will do ceil(scan_duration/scan_period) measurements, at start_time + i*scan_period */ 404 uint32_t scan_period; 405 406 /*Modulation we search for (and in which the receiver is set) and center frequency */ 407 p2G4_radioparams_t radio_params; 408 409 /* Rx power threshold with which a compatible transmitter will be considered found */ 410 p2G4_rssi_power_t mod_threshold; 411 /* RSSI power threshold with which the energy detection will be considered over threshold */ 412 p2G4_rssi_power_t rssi_threshold; 413 414 /*Gain of the Rx antenna*/ 415 p2G4_power_t antenna_gain; 416 417 /* Stop as soon as a compatible modulation is found with power over mod_threshold (1) 418 * Stop as soon as any RRSI measurement is over rssi_threshold (2) 419 * either (3) 420 * Or continue until the end of the scan_duration (0) */ 421 uint8_t stop_when_found; 422 } p2G4_cca_t; 423 424 425 typedef struct __attribute__ ((packed)) { 426 /* Absolute us this message is sent */ 427 bs_time_t end_time; 428 429 /* The averaged RSSI measurement (Of all scan_periods) */ 430 p2G4_rssi_power_t RSSI_ave; 431 /* The max RSSI measurement (Of all scan_periods) */ 432 p2G4_rssi_power_t RSSI_max; 433 /* RRSI power level measured when a matching Tx modulation was found (if several are found over time, the greater level) */ 434 p2G4_rssi_power_t mod_rx_power; 435 /* Was a compatible transmitter with power over mod_threshold found (1) or not (0) */ 436 uint8_t mod_found; 437 /* Was at any point the RRSI level over rssi_threshold (1) or not (0) */ 438 uint8_t rssi_overthreshold; 439 } p2G4_cca_done_t; 440 441 442 /* 443 * Commands and responses IDs: 444 */ 445 446 /** Message headers from device to phy **/ 447 /* The device will transmit */ 448 #define P2G4_MSG_TX 0x02 449 /* The device wants to attempt to receive */ 450 #define P2G4_MSG_RX 0x11 451 /* Continue receiving (the device likes the address and headers of the packet) */ 452 #define P2G4_MSG_RXCONT 0x12 453 /* Stop reception (the device does not likes the address or headers of the packet) => The phy will stop this reception */ 454 #define P2G4_MSG_RXSTOP 0x13 455 /* Do an RSSI measurement*/ 456 #define P2G4_MSG_RSSIMEAS 0x14 457 /* Device is successfully providing a new p2G4_abort_t */ 458 #define P2G4_MSG_RERESP_ABORTREEVAL 0x15 459 /* Continue receiving (the device likes the address and headers of the packet, and it provides an updated abort substructure) */ 460 #define P2G4_MSG_RXV2CONT 0x16 461 462 463 /* The device will transmit (updated/v2 Tx API) */ 464 #define P2G4_MSG_TXV2 0x22 465 /* The device wants to attempt to receive (updated/v2 Rx API) */ 466 #define P2G4_MSG_RXV2 0x31 467 /* The device wants to do a CCA check (new v2 API) */ 468 #define P2G4_MSG_CCA_MEAS 0x32 469 /* Device is requesting an immediate RSSI measurement during an Rx abort reevaluation (new for v2 API) */ 470 #define P2G4_MSG_RERESP_IMMRSSI 0x16 471 472 473 /** From Phy to device **/ 474 /* Tx completed (fully or not) */ 475 #define P2G4_MSG_TX_END 0x100 476 /* Poking the device to see if it wants to change its abort time */ 477 #define P2G4_MSG_ABORTREEVAL 0x101 478 /* Phy responds to the device with the immediate RRSI measurement 479 * while re-requesting a new abort reeval.(new for v2 API) */ 480 #define P2G4_MSG_IMMRSSI_RRSI_DONE 0x102 481 482 483 /* Matching address found while receiving */ 484 #define P2G4_MSG_RX_ADDRESSFOUND 0x102 485 /* Rx completed (successfully or not) */ 486 #define P2G4_MSG_RX_END 0x103 487 /* RSSI measurement completed */ 488 #define P2G4_MSG_RSSI_END 0x104 489 490 /* Matching address found while receiving (new v2 API) */ 491 #define P2G4_MSG_RXV2_ADDRESSFOUND 0x112 492 /* Rx completed (successfully or not) (new v2 API) */ 493 #define P2G4_MSG_RXV2_END 0x113 494 /* Search CCA check completed (new v2 API) */ 495 #define P2G4_MSG_CCA_END 0x114 496 497 #ifdef __cplusplus 498 } 499 #endif 500 501 #endif 502
