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     macLoadBalancingBeaconTxPeriod = 0xfd,  /*> Set Beacon periodic Tx interval.Value size uint16_t in seconds, Use 0 to disable */
00253     macLoadBalancingAcceptAnyBeacon = 0xfe, /*>Beacon accept state control from other network. Value size bool, data true=Enable, false=disable .*/
00254     macThreadForceLongAddressForBeacon = 0xff /*>Thread standard force beacon source address for extended 64-bit*/
00255 } mlme_attr_t;
00256 
00257 //typedef struct mlme_associate_s {
00258 //    uint8_t LogicalChannel;
00259 //    uint8_t ChannelPage;
00260 //    unsigned CoordAddrMode:2;
00261 //    uint16_t CoordPANId;
00262 //    uint8_t CoordAddress[8];
00263 //    uint8_t CapabilityInformation;
00264 //    mlme_security_t Key;
00265 //} mlme_associate_t;
00266 
00267 //typedef struct mlme_associate_ind_s {
00268 //    uint8_t DeviceAddress[8];
00269 //    uint8_t CapabilityInformation;
00270 //    mlme_security_t Key;
00271 //} mlme_associate_ind_t;
00272 
00273 //typedef struct mlme_associate_resp_s {
00274 //    uint8_t DeviceAddress[8];
00275 //    uint16_t AssocShortAddress;
00276 //    uint8_t status;
00277 //    mlme_security_t Key;
00278 //} mlme_associate_resp_t;
00279 
00280 //typedef struct mlme_associate_conf_s {
00281 //    uint16_t AssocShortAddress;
00282 //    uint8_t status;
00283 //    mlme_security_t Key;
00284 //} mlme_associate_conf_t;
00285 
00286 //typedef struct mlme_disassociate_s {
00287 //    unsigned DeviceAddrMode:2;
00288 //    uint16_t DevicePANId;
00289 //    uint8_t DeviceAddress[8];
00290 //    uint8_t DisassociateReason;
00291 //    bool TxIndirect:1;
00292 //    mlme_security_t Key;
00293 //} mlme_disassociate_t;
00294 
00295 //typedef struct mlme_disassociate_ind_s {
00296 //    uint8_t DeviceAddress[8];
00297 //    uint8_t DisassociateReason;
00298 //    mlme_security_t Key;
00299 //} mlme_disassociate_ind_t;
00300 
00301 //typedef struct mlme_disassociate_conf_s {
00302 //    uint8_t status;
00303 //    unsigned DeviceAddrMode:2;
00304 //    uint16_t DevicePANId;
00305 //    uint8_t DeviceAddress[8];
00306 //} mlme_disassociate_conf_t;
00307 
00308 /**
00309  * @brief struct mlme_beacon_pending_address_spec_t Pending address specification field
00310  *
00311  * See IEEE standard 802.15.4-2006 (figure 51) for more details
00312  */
00313 typedef struct mlme_beacon_pending_address_spec_s{
00314     unsigned short_address_count:3;
00315     unsigned extended_address_count:3;
00316 }mlme_beacon_pending_address_spec_t;
00317 
00318 /**
00319  * @brief struct mlme_beacon_gts_spec_t Format of GTS specification field
00320  *
00321  * See IEEE standard 802.15.4-2006 (figure 48) for more details
00322  */
00323 typedef struct mlme_beacon_gts_spec_s{
00324     unsigned description_count:3;
00325     unsigned gts_permit:1;
00326 }mlme_beacon_gts_spec_t;
00327 
00328 /**
00329  * @brief struct mlme_beacon_ind_t Beacon notify structure
00330  *
00331  * See IEEE standard 802.15.4-2006 (table 54) for more details
00332  */
00333 typedef struct mlme_beacon_ind_s {
00334     uint8_t BSN;
00335     mlme_pan_descriptor_t PANDescriptor;
00336     mlme_beacon_pending_address_spec_t PendAddrSpec;
00337     uint8_t *AddrList;
00338     uint16_t beacon_data_length;
00339     uint8_t *beacon_data;
00340 } mlme_beacon_ind_t;
00341 
00342 /**
00343  * @brief struct mlme_scan_t Scan request structure
00344  *
00345  * See IEEE standard 802.15.4-2006 (table 67) for more details
00346  */
00347 typedef struct mlme_scan_s {
00348     mac_scan_type_t     ScanType;       /*> ED=0, active=1, passive=2, orphan=3*/
00349     channel_list_s  ScanChannels;   /*>bit field, low 27 bits used*/
00350     uint8_t     ScanDuration;   /*>0-14, scan duration/channel*/
00351     uint8_t     ChannelPage;    /*>0-31*/
00352     mlme_security_t Key;
00353 } mlme_scan_t;
00354 
00355 /**
00356  * @brief struct mlme_set_t Set request structure
00357  *
00358  * See IEEE standard 802.15.4-2006 (table 70) for more details
00359  */
00360 typedef struct mlme_set_s {
00361     mlme_attr_t attr;
00362     uint8_t attr_index;
00363     const void *value_pointer;
00364     uint8_t value_size;
00365 } mlme_set_t;
00366 
00367 /**
00368  * @brief struct mlme_get_t Get request structure
00369  *
00370  * See IEEE standard 802.15.4-2006 (table 56) for more details
00371  */
00372 typedef struct mlme_get_s {
00373     mlme_attr_t attr;
00374     uint8_t attr_index;
00375 } mlme_get_t;
00376 
00377 /**
00378  * @brief struct mlme_get_conf_t Get confirm structure
00379  *
00380  * See IEEE standard 802.15.4-2006 (table 57) for more details
00381  */
00382 typedef struct mlme_get_conf_s {
00383     uint8_t status;
00384     mlme_attr_t attr;
00385     uint8_t attr_index;
00386     void *value_pointer;
00387     uint8_t value_size;
00388 } mlme_get_conf_t;
00389 
00390 /**
00391  * @brief struct mlme_set_conf_t Set confirm structure
00392  *
00393  * See IEEE standard 802.15.4-2006 (table 71) for more details
00394  */
00395 typedef struct mlme_set_conf_s {
00396     uint8_t status;
00397     mlme_attr_t attr;
00398     uint8_t attr_index;
00399 } mlme_set_conf_t;
00400 
00401 
00402 #define MLME_MAC_RES_SIZE_MAX 16
00403 
00404 /**
00405  * @brief struct mlme_scan_conf_t Scan confirm structure
00406  *
00407  * See IEEE standard 802.15.4-2006 (table 68) for more details
00408  */
00409 typedef struct mlme_scan_conf_s {
00410     uint8_t status;
00411     unsigned ScanType:2;
00412     uint8_t ChannelPage;
00413     channel_list_s UnscannedChannels;
00414     uint8_t ResultListSize;
00415     uint8_t *ED_values;
00416     mlme_pan_descriptor_t *PAN_values[MLME_MAC_RES_SIZE_MAX];
00417 } mlme_scan_conf_t;
00418 
00419 /**
00420  * @brief struct mlme_reset_t Reset request structure
00421  *
00422  * See IEEE standard 802.15.4-2006 (table 63) for more details
00423  */
00424 typedef struct mlme_reset_s {
00425     bool SetDefaultPIB;
00426 } mlme_reset_t;
00427 
00428 /**
00429  * @brief struct mlme_reset_conf_t Reset confirm structure
00430  *
00431  * See IEEE standard 802.15.4-2006 (table 64) for more details
00432  */
00433 typedef struct mlme_reset_conf_s {
00434     uint8_t status;
00435 } mlme_reset_conf_t;
00436 
00437 /**
00438  * @brief struct mlme_rx_enable_t Rx enable request structure
00439  *
00440  * See IEEE standard 802.15.4-2006 (table 65) for more details
00441  */
00442 //typedef struct mlme_rx_enable_s {
00443 //    bool DeferPermit;
00444 //    uint32_t RxOnTime;
00445 //    uint32_t RxOnDuration;
00446 //} mlme_rx_enable_t;
00447 
00448 /**
00449  * @brief struct mlme_rx_enable_conf_t Rx enable confirm structure
00450  *
00451  * See IEEE standard 802.15.4-2006 (table 66) for more details
00452  */
00453 //typedef struct mlme_rx_enable_conf_s {
00454 //    uint8_t status;
00455 //} mlme_rx_enable_conf_t;
00456 
00457 /**
00458  * @brief struct mlme_comm_status_t Comm status indication structure
00459  *
00460  * See IEEE standard 802.15.4-2006 (table 69) for more details
00461  */
00462 typedef struct mlme_comm_status_s {
00463     uint16_t PANId;
00464     unsigned SrcAddrMode:2;
00465     uint8_t SrcAddr[8];
00466     unsigned DstAddrMode:2;
00467     uint8_t DstAddr[8];
00468     uint8_t status;
00469     mlme_security_t Key;
00470 } mlme_comm_status_t;
00471 
00472 /**
00473  * @brief struct mlme_start_t Start request structure
00474  *
00475  * See IEEE standard 802.15.4-2006 (table 72) for more details
00476  */
00477 typedef struct mlme_start_s {
00478     uint16_t PANId;
00479     uint8_t LogicalChannel;
00480     uint8_t ChannelPage;
00481     uint32_t StartTime;
00482     unsigned BeaconOrder:4;
00483     unsigned SuperframeOrder:4;
00484     bool PANCoordinator:1;
00485     bool BatteryLifeExtension:1;
00486     bool CoordRealignment:1;
00487     mlme_security_t CoordRealignKey;
00488     mlme_security_t BeaconRealignKey;
00489 } mlme_start_t;
00490 
00491 /**
00492  * @brief struct mlme_start_conf_t Start confirm structure
00493  *
00494  * See IEEE standard 802.15.4-2006 (table 73) for more details
00495  */
00496 typedef struct mlme_start_conf_s {
00497     uint8_t status;
00498 } mlme_start_conf_t;
00499 
00500 //typedef struct mlme_sync_s {
00501 //    uint8_t LogicalChannel;
00502 //    uint8_t ChannelPage;
00503 //    bool TrackBeacon;
00504 //} mlme_sync_t;
00505 
00506 //typedef struct mlme_sync_loss_s {
00507 //    uint8_t LossReason;
00508 //    uint16_t PANId;
00509 //    uint8_t LogicalChannel;
00510 //    uint8_t ChannelPage;
00511 //    mlme_security_t Key;
00512 //} mlme_sync_loss_t;
00513 
00514 /**
00515  * @brief struct mlme_poll_t Poll request structure
00516  *
00517  * See IEEE standard 802.15.4-2006 (table 76) for more details
00518  */
00519 typedef struct mlme_poll_s {
00520     unsigned CoordAddrMode:2;
00521     uint16_t CoordPANId;
00522     uint8_t CoordAddress[8];
00523     mlme_security_t Key;
00524 } mlme_poll_t;
00525 
00526 /**
00527  * @brief struct mlme_poll_conf_t Poll confirm structure
00528  *
00529  * See IEEE standard 802.15.4-2006 (table 77) for more details
00530  */
00531 typedef struct mlme_poll_conf_s {
00532     uint8_t status;
00533 } mlme_poll_conf_t;
00534 
00535 #endif /* MLME_H_ */