mlme.h

00001 /*
00002  * Copyright (c) 2013-2016 ARM Limited. All rights reserved.
00003  *
00004  * SPDX-License-Identifier: LicenseRef-PBL
00005  *
00006  * Licensed under the Permissive Binary License, Version 1.0 (the "License"); you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  * https://www.mbed.com/licenses/PBL-1.0
00010  *
00011  * See the License for the specific language governing permissions and limitations under the License.
00012  *
00013  */
00014 
00015 /** \file mlme.h
00016  * \brief MLME API
00017  */
00018 
00019 #ifndef MLME_H_
00020 #define MLME_H_
00021 
00022 #include <stdbool.h>
00023 #include "mac_common_defines.h"
00024 #include "net_interface.h"
00025 
00026 /**
00027  * @brief struct mlme_pan_descriptor_t PAN descriptor
00028  *
00029  * See IEEE standard 802.15.4-2006 (table 55) for more details
00030  */
00031 typedef struct mlme_pan_descriptor_s {
00032     unsigned CoordAddrMode:2;
00033     uint16_t CoordPANId;
00034     uint8_t CoordAddress[8];
00035     uint8_t LogicalChannel;
00036     uint8_t ChannelPage;
00037     uint8_t SuperframeSpec[2];
00038     bool GTSPermit:1;
00039     uint8_t LinkQuality;
00040     uint32_t Timestamp;
00041     uint8_t SecurityFailure;
00042     mlme_security_t Key;
00043 } mlme_pan_descriptor_t;
00044 
00045 /**
00046  * @brief struct mlme_command_type_t Command type enumeration
00047  *
00048  * See IEEE standard 802.15.4-2006 (table 82) for more details
00049  */
00050 typedef enum {
00051     ASSOCIATION_REQUEST = 1,
00052     ASSOCIATION_RESPONSE = 2,
00053     DISASSOCIATION_NOTIFICATION = 3,
00054     DATA_REQUEST = 4,
00055     PAN_ID_CONFLICT_NOTIFICATION = 5,
00056     ORPHAN_NOTIFICATION = 6,
00057     BEACON_REQUEST = 7,
00058     COORDINATOR_REALIGNMENT = 8,
00059     GTS_REQUEST = 9
00060     //Reserved
00061 } mlme_command_type_t;
00062 
00063 /**
00064  * @brief struct mlme_key_usage_descriptor_t Key usage descriptor
00065  *
00066  * See IEEE standard 802.15.4-2006 (table 90) for more details
00067  */
00068 typedef struct mlme_key_usage_descriptor_s {
00069     unsigned FrameType:3; //See mlme_frame_types
00070     unsigned CommandFrameIdentifier:4; //See mlme_command_type_t
00071 } mlme_key_usage_descriptor_t;
00072 
00073 /**
00074  * @brief struct mlme_key_device_descriptor_t Key usage descriptor
00075  *
00076  * See IEEE standard 802.15.4-2006 (table 91) for more details
00077  */
00078 typedef struct mlme_key_device_descriptor_s {
00079     uint8_t DeviceDescriptorHandle; //Index of an entry in macDeviceTable
00080     bool UniqueDevice:1;
00081     bool Blacklisted:1;
00082 } mlme_key_device_descriptor_t;
00083 
00084 /**
00085  * @brief enum mlme_security_type_t Security type enumeration
00086  *
00087  * See IEEE standard 802.15.4-2006 (table 95) for more details
00088  */
00089 typedef enum {
00090     SEC_NONE = 0,
00091     SEC_MIC32 = 1,
00092     SEC_MIC64 = 2,
00093     SEC_MIC128 = 3,
00094     SEC_ENC = 4,
00095     SEC_ENC_MIC32 = 5,
00096     SEC_ENC_MIC64 = 6,
00097     SEC_ENC_MIC128 = 7
00098 } mlme_security_type_t;
00099 
00100 /**
00101  * @brief struct mlme_security_level_descriptor_t Security level descriptor
00102  *
00103  * See IEEE standard 802.15.4-2006 (table 92) for more details
00104  */
00105 typedef struct mlme_security_level_descriptor_s {
00106     unsigned FrameType:3; //See mlme_frame_types
00107     unsigned CommandFrameIdentifier:4; //See mlme_command_type_t
00108     unsigned SecurityMinimum:3; //See mlme_security_type_t
00109     bool DeviceOverrideSecurityMinimum:1;
00110 } mlme_security_level_descriptor_t;
00111 
00112 /**
00113  * @brief struct mlme_device_descriptor_t Device descriptor
00114  *
00115  * See IEEE standard 802.15.4-2006 (table 93) for more details
00116  */
00117 typedef struct mlme_device_descriptor_s {
00118     uint16_t PANId;
00119     uint16_t ShortAddress;
00120     uint8_t ExtAddress[8];
00121     uint32_t FrameCounter;
00122     bool Exempt:1;
00123 } mlme_device_descriptor_t;
00124 
00125 /**
00126  * @brief struct mlme_key_id_lookup_descriptor_t Key id lookup descriptor
00127  *
00128  * See IEEE standard 802.15.4-2006 (table 94) for more details
00129  */
00130 typedef struct mlme_key_id_lookup_descriptor_s {
00131     uint8_t LookupData[9];
00132     unsigned LookupDataSize:1; //0 == 5, 1 == 9
00133 } mlme_key_id_lookup_descriptor_t;
00134 
00135 
00136 /**
00137  * @brief struct mlme_key_descriptor_entry_t Key descriptor entry
00138  *
00139  * See IEEE standard 802.15.4-2006 (table 89) for more details
00140  */
00141 typedef struct mlme_key_descriptor_entry_s {
00142     mlme_key_id_lookup_descriptor_t *KeyIdLookupList;
00143     uint8_t KeyIdLookupListEntries;
00144     mlme_key_device_descriptor_t *KeyDeviceList;
00145     uint8_t KeyDeviceListEntries;
00146     mlme_key_usage_descriptor_t *KeyUsageList;
00147     uint8_t KeyUsageListEntries;
00148     uint8_t Key[16];
00149 }mlme_key_descriptor_entry_t;
00150 
00151 /**
00152  * @brief MLME primitive error statuses
00153  *
00154  * See IEEE standard 802.15.4-2006 for more details
00155  */
00156 #define MLME_SUCCESS                    0x00
00157 #define MLME_BUSY_CHAN                  0xe1
00158 #define MLME_BUSY_RX                    0x01
00159 #define MLME_BUSY_TX                    0x02
00160 #define MLME_FORCE_TRX_OFF              0x03
00161 #define MLME_IDLE                       0x04
00162 #define MLME_RX_ON                      0x06
00163 #define MLME_TRX_OFF                    0x08
00164 #define MLME_TX_ON                      0x09
00165 #define MLME_COUNTER_ERROR              0xdb
00166 #define MLME_IMPROPER_KEY_TYPE          0xdc
00167 #define MLME_IMPROPER_SECURITY_LEVEL    0xdd
00168 #define MLME_UNSUPPORTED_LEGACY         0xde
00169 #define MLME_UNSUPPORTED_SECURITY       0xdf
00170 #define MLME_SECURITY_FAIL              0xe4
00171 #define MLME_FRAME_TOO_LONG             0xe5
00172 #define MLME_INVALID_HANDLE             0xe7
00173 #define MLME_INVALID_PARAMETER          0xe8
00174 #define MLME_TX_NO_ACK                  0xe9
00175 #define MLME_NO_BEACON                  0xea
00176 #define MLME_NO_DATA                    0xeb
00177 #define MLME_NO_SHORT_ADDRESS           0xec
00178 #define MLME_PAN_ID_CONFLICT            0xee
00179 #define MLME_TRANSACTION_EXPIRED        0xf0
00180 #define MLME_TRANSACTION_OVERFLOW       0xf1
00181 #define MLME_UNAVAILABLE_KEY            0xf3
00182 #define MLME_UNSUPPORTED_ATTRIBUTE      0xf4
00183 #define MLME_INVALID_ADDRESS            0xf5
00184 #define MLME_INVALID_INDEX              0xf9
00185 #define MLME_LIMIT_REACHED              0xfa
00186 #define MLME_READ_ONLY                  0xfb
00187 #define MLME_SCAN_IN_PROGRESS           0xfc
00188 #define MLME_DATA_POLL_NOTIFICATION     0xff
00189 
00190 /**
00191  * @brief enum mac_scan_type_t MAC scan type
00192  *
00193  * See IEEE standard 802.15.4-2006 (table 67) for more details
00194  */
00195 typedef enum {
00196     MAC_ED_SCAN_TYPE = 0,
00197     MAC_ACTIVE_SCAN = 1,
00198     MAC_PASSIVE_SCAN = 2,
00199     MAC_ORPHAN_SCAN = 3
00200 } mac_scan_type_t;
00201 
00202 /**
00203  * @brief enum mlme_attr_t MLME attributes used with GET and SET primitives
00204  *
00205  * See IEEE standard 802.15.4-2006 (table 86) for more details
00206  */
00207 typedef enum {
00208     phyCurrentChannel = 0x00,       /*>Current RF channel*/
00209     macAckWaitDuration = 0x40,      /*>Integer, n. of symbols*/
00210     macAssociatedPANCoord = 0x56,   /*>Boolean, associated to PAN coordinator*/
00211     macAssociationPermit = 0x41,    /*>Boolean, if association is allowed (in coordinator)*/
00212     macAutoRequest = 0x42,          /*>Boolean, if device automatically sends data request on beacon*/
00213     macBattLifeExt = 0x43,          /*>Boolean, if BLE is enabled*/
00214     macBattLifeExtPeriods = 0x44,   /*>Integer 6-41, BLE backoff periods */
00215     macBeaconPayload = 0x45,        /*>Set of bytes, beacon payload*/
00216     macBeaconPayloadLength = 0x46,  /*>Integer 0-MaxPayLoadLen*/
00217     macBeaconOrder = 0x47,          /*>Integer 0–15, Beacon tx period, 15 = no periodic beacon*/
00218     macBeaconTxTime = 0x48,         /*>Integer 0x000000–0xffffff, symbols, when last beacon was transmitted*/
00219     macBSN = 0x49,                  /*>Integer 0x00–0xff, Beacon sequence number*/
00220     macCoordExtendedAddress = 0x4a, /*>64-bit IEEE of coordinator*/
00221     macCoordShortAddress = 0x4b,    /*>16-bit addr of coordinator*/
00222     macDSN = 0x4c,                  /*>Integer 0x00–0xff, Data frame sequence number*/
00223     macGTSPermit = 0x4d,            /*>Boolean, GTS allowed?*/
00224     macMaxBE = 0x57,                /*>Integer 3–8, max value of backoff exponent*/
00225     macMaxCSMABackoffs = 0x4e,      /*>Integer 0–5*/
00226     macMaxFrameTotalWaitTime = 0x58,/*>Integer, max of CAP symbols while waiting for data requested by DREQ or PEND*/
00227     macMaxFrameRetries = 0x59,      /*>Integer 0–7*/
00228     macMinBE = 0x4f,                /*>Integer 0–macMaxBE*/
00229     macPANId = 0x50,                /*>PAN ID, 16 bits*/
00230     macPromiscuousMode = 0x51,      /*>Boolean*/
00231     macResponseWaitTime = 0x5a,     /*>Integer 2–64  The maximum time in SuperFrameDurations to wait for responses*/
00232     macRxOnWhenIdle = 0x52,         /*>Boolean*/
00233     macSecurityEnabled = 0x5d,      /*>Boolean*/
00234     macShortAddress = 0x53,         /*>Short address, 16 bits*/
00235     macSuperframeOrder = 0x54,      /*>Integer 0–15, The length of the active portion of the outgoing superframe, 15 = none*/
00236     macSyncSymbolOffset = 0x5b,     /*>Integer 0x000–0x100 (symbols) timestamp offset*/
00237     macTimestampSupported = 0x5c,   /*>Boolean*/
00238     macTransactionPersistenceTime = 0x55, /*>Integer 0x0000–0xffff (unit periods)*/
00239     macKeyTable = 0x71,             /*>A table of KeyDescriptor entries, each containing keys and related information required for secured communications.*/
00240     macKeyTableEntries = 0x72,      /*>The number of entries in macKeyTable.*/
00241     macDeviceTable = 0x73,          /*>List of Descriptor entries, each indicating a remote device*/
00242     macDeviceTableEntries = 0x74,   /*>The number of entries in macDeviceTable.*/
00243     macSecurityLevelTable = 0x75,   /*>A table of SecurityLevelDescriptor entries*/
00244     macSecurityLevelTableEntries = 0x76,    /*>The number of entries in macSecurityLevelTable*/
00245     macFrameCounter = 0x77,         /*>The outgoing frame counter*/
00246     macAutoRequestSecurityLevel = 0x78, /*>0x00–0x07  The security level used for automatic data requests.*/
00247     macAutoRequestKeyIdMode = 0x79,      /*> The key identifier mode used for automatic data requests.*/
00248     macAutoRequestKeySource = 0x7a, /*>Key source for automatic data*/
00249     macAutoRequestKeyIndex = 0x7b,  /*>The index of the key used for automatic data*/
00250     macDefaultKeySource = 0x7c,      /*>Default key source*/
00251     //NON standard extension
00252     macThreadForceLongAddressForBeacon = 0xff /*>Thread standard force beacon source address for extended 64-bit*/
00253 } mlme_attr_t;
00254 
00255 //typedef struct mlme_associate_s {
00256 //    uint8_t LogicalChannel;
00257 //    uint8_t ChannelPage;
00258 //    unsigned CoordAddrMode:2;
00259 //    uint16_t CoordPANId;
00260 //    uint8_t CoordAddress[8];
00261 //    uint8_t CapabilityInformation;
00262 //    mlme_security_t Key;
00263 //} mlme_associate_t;
00264 
00265 //typedef struct mlme_associate_ind_s {
00266 //    uint8_t DeviceAddress[8];
00267 //    uint8_t CapabilityInformation;
00268 //    mlme_security_t Key;
00269 //} mlme_associate_ind_t;
00270 
00271 //typedef struct mlme_associate_resp_s {
00272 //    uint8_t DeviceAddress[8];
00273 //    uint16_t AssocShortAddress;
00274 //    uint8_t status;
00275 //    mlme_security_t Key;
00276 //} mlme_associate_resp_t;
00277 
00278 //typedef struct mlme_associate_conf_s {
00279 //    uint16_t AssocShortAddress;
00280 //    uint8_t status;
00281 //    mlme_security_t Key;
00282 //} mlme_associate_conf_t;
00283 
00284 //typedef struct mlme_disassociate_s {
00285 //    unsigned DeviceAddrMode:2;
00286 //    uint16_t DevicePANId;
00287 //    uint8_t DeviceAddress[8];
00288 //    uint8_t DisassociateReason;
00289 //    bool TxIndirect:1;
00290 //    mlme_security_t Key;
00291 //} mlme_disassociate_t;
00292 
00293 //typedef struct mlme_disassociate_ind_s {
00294 //    uint8_t DeviceAddress[8];
00295 //    uint8_t DisassociateReason;
00296 //    mlme_security_t Key;
00297 //} mlme_disassociate_ind_t;
00298 
00299 //typedef struct mlme_disassociate_conf_s {
00300 //    uint8_t status;
00301 //    unsigned DeviceAddrMode:2;
00302 //    uint16_t DevicePANId;
00303 //    uint8_t DeviceAddress[8];
00304 //} mlme_disassociate_conf_t;
00305 
00306 /**
00307  * @brief struct mlme_beacon_pending_address_spec_t Pending address specification field
00308  *
00309  * See IEEE standard 802.15.4-2006 (figure 51) for more details
00310  */
00311 typedef struct mlme_beacon_pending_address_spec_s{
00312     unsigned short_address_count:3;
00313     unsigned extended_address_count:3;
00314 }mlme_beacon_pending_address_spec_t;
00315 
00316 /**
00317  * @brief struct mlme_beacon_gts_spec_t Format of GTS specification field
00318  *
00319  * See IEEE standard 802.15.4-2006 (figure 48) for more details
00320  */
00321 typedef struct mlme_beacon_gts_spec_s{
00322     unsigned description_count:3;
00323     unsigned gts_permit:1;
00324 }mlme_beacon_gts_spec_t;
00325 
00326 /**
00327  * @brief struct mlme_beacon_ind_t Beacon notify structure
00328  *
00329  * See IEEE standard 802.15.4-2006 (table 54) for more details
00330  */
00331 typedef struct mlme_beacon_ind_s {
00332     uint8_t BSN;
00333     mlme_pan_descriptor_t PANDescriptor;
00334     mlme_beacon_pending_address_spec_t PendAddrSpec;
00335     uint8_t *AddrList;
00336     uint16_t beacon_data_length;
00337     uint8_t *beacon_data;
00338 } mlme_beacon_ind_t;
00339 
00340 /**
00341  * @brief struct mlme_scan_t Scan request structure
00342  *
00343  * See IEEE standard 802.15.4-2006 (table 67) for more details
00344  */
00345 typedef struct mlme_scan_s {
00346     mac_scan_type_t     ScanType;       /*> ED=0, active=1, passive=2, orphan=3*/
00347     channel_list_s  ScanChannels;   /*>bit field, low 27 bits used*/
00348     uint8_t     ScanDuration;   /*>0-14, scan duration/channel*/
00349     uint8_t     ChannelPage;    /*>0-31*/
00350     mlme_security_t Key;
00351 } mlme_scan_t;
00352 
00353 /**
00354  * @brief struct mlme_set_t Set request structure
00355  *
00356  * See IEEE standard 802.15.4-2006 (table 70) for more details
00357  */
00358 typedef struct mlme_set_s {
00359     mlme_attr_t attr;
00360     uint8_t attr_index;
00361     const void *value_pointer;
00362     uint8_t value_size;
00363 } mlme_set_t;
00364 
00365 /**
00366  * @brief struct mlme_get_t Get request structure
00367  *
00368  * See IEEE standard 802.15.4-2006 (table 56) for more details
00369  */
00370 typedef struct mlme_get_s {
00371     mlme_attr_t attr;
00372     uint8_t attr_index;
00373 } mlme_get_t;
00374 
00375 /**
00376  * @brief struct mlme_get_conf_t Get confirm structure
00377  *
00378  * See IEEE standard 802.15.4-2006 (table 57) for more details
00379  */
00380 typedef struct mlme_get_conf_s {
00381     uint8_t status;
00382     mlme_attr_t attr;
00383     uint8_t attr_index;
00384     void *value_pointer;
00385     uint8_t value_size;
00386 } mlme_get_conf_t;
00387 
00388 /**
00389  * @brief struct mlme_set_conf_t Set confirm structure
00390  *
00391  * See IEEE standard 802.15.4-2006 (table 71) for more details
00392  */
00393 typedef struct mlme_set_conf_s {
00394     uint8_t status;
00395     mlme_attr_t attr;
00396     uint8_t attr_index;
00397 } mlme_set_conf_t;
00398 
00399 
00400 #define MLME_MAC_RES_SIZE_MAX 16
00401 
00402 /**
00403  * @brief struct mlme_scan_conf_t Scan confirm structure
00404  *
00405  * See IEEE standard 802.15.4-2006 (table 68) for more details
00406  */
00407 typedef struct mlme_scan_conf_s {
00408     uint8_t status;
00409     unsigned ScanType:2;
00410     uint8_t ChannelPage;
00411     channel_list_s UnscannedChannels;
00412     uint8_t ResultListSize;
00413     uint8_t *ED_values;
00414     mlme_pan_descriptor_t *PAN_values[MLME_MAC_RES_SIZE_MAX];
00415 } mlme_scan_conf_t;
00416 
00417 /**
00418  * @brief struct mlme_reset_t Reset request structure
00419  *
00420  * See IEEE standard 802.15.4-2006 (table 63) for more details
00421  */
00422 typedef struct mlme_reset_s {
00423     bool SetDefaultPIB;
00424 } mlme_reset_t;
00425 
00426 /**
00427  * @brief struct mlme_reset_conf_t Reset confirm structure
00428  *
00429  * See IEEE standard 802.15.4-2006 (table 64) for more details
00430  */
00431 typedef struct mlme_reset_conf_s {
00432     uint8_t status;
00433 } mlme_reset_conf_t;
00434 
00435 /**
00436  * @brief struct mlme_rx_enable_t Rx enable request structure
00437  *
00438  * See IEEE standard 802.15.4-2006 (table 65) for more details
00439  */
00440 //typedef struct mlme_rx_enable_s {
00441 //    bool DeferPermit;
00442 //    uint32_t RxOnTime;
00443 //    uint32_t RxOnDuration;
00444 //} mlme_rx_enable_t;
00445 
00446 /**
00447  * @brief struct mlme_rx_enable_conf_t Rx enable confirm structure
00448  *
00449  * See IEEE standard 802.15.4-2006 (table 66) for more details
00450  */
00451 //typedef struct mlme_rx_enable_conf_s {
00452 //    uint8_t status;
00453 //} mlme_rx_enable_conf_t;
00454 
00455 /**
00456  * @brief struct mlme_comm_status_t Comm status indication structure
00457  *
00458  * See IEEE standard 802.15.4-2006 (table 69) for more details
00459  */
00460 typedef struct mlme_comm_status_s {
00461     uint16_t PANId;
00462     unsigned SrcAddrMode:2;
00463     uint8_t SrcAddr[8];
00464     unsigned DstAddrMode:2;
00465     uint8_t DstAddr[8];
00466     uint8_t status;
00467     mlme_security_t Key;
00468 } mlme_comm_status_t;
00469 
00470 /**
00471  * @brief struct mlme_start_t Start request structure
00472  *
00473  * See IEEE standard 802.15.4-2006 (table 72) for more details
00474  */
00475 typedef struct mlme_start_s {
00476     uint16_t PANId;
00477     uint8_t LogicalChannel;
00478     uint8_t ChannelPage;
00479     uint32_t StartTime;
00480     unsigned BeaconOrder:4;
00481     unsigned SuperframeOrder:4;
00482     bool PANCoordinator:1;
00483     bool BatteryLifeExtension:1;
00484     bool CoordRealignment:1;
00485     mlme_security_t CoordRealignKey;
00486     mlme_security_t BeaconRealignKey;
00487 } mlme_start_t;
00488 
00489 /**
00490  * @brief struct mlme_start_conf_t Start confirm structure
00491  *
00492  * See IEEE standard 802.15.4-2006 (table 73) for more details
00493  */
00494 typedef struct mlme_start_conf_s {
00495     uint8_t status;
00496 } mlme_start_conf_t;
00497 
00498 //typedef struct mlme_sync_s {
00499 //    uint8_t LogicalChannel;
00500 //    uint8_t ChannelPage;
00501 //    bool TrackBeacon;
00502 //} mlme_sync_t;
00503 
00504 //typedef struct mlme_sync_loss_s {
00505 //    uint8_t LossReason;
00506 //    uint16_t PANId;
00507 //    uint8_t LogicalChannel;
00508 //    uint8_t ChannelPage;
00509 //    mlme_security_t Key;
00510 //} mlme_sync_loss_t;
00511 
00512 /**
00513  * @brief struct mlme_poll_t Poll request structure
00514  *
00515  * See IEEE standard 802.15.4-2006 (table 76) for more details
00516  */
00517 typedef struct mlme_poll_s {
00518     unsigned CoordAddrMode:2;
00519     uint16_t CoordPANId;
00520     uint8_t CoordAddress[8];
00521     mlme_security_t Key;
00522 } mlme_poll_t;
00523 
00524 /**
00525  * @brief struct mlme_poll_conf_t Poll confirm structure
00526  *
00527  * See IEEE standard 802.15.4-2006 (table 77) for more details
00528  */
00529 typedef struct mlme_poll_conf_s {
00530     uint8_t status;
00531 } mlme_poll_conf_t;
00532 
00533 #endif /* MLME_H_ */