F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
8b1d31b0d723aeb293ca8fe8c5e96b1dd7358115
unison/src/zigbee/model/zigbee-nwk.h
Alberto Gallegos Ramonet 8b1d31b0d7 zigbee: Change callbacks typedef to using
2025-09-28 15:56:44 +00:00

1845 lines
72 KiB
C++
Raw Blame History

/*
* Copyright (c) 2024 Tokushima University, Japan
*
* SPDX-License-Identifier: GPL-2.0-only
*
* Authors:
*
* Alberto Gallegos Ramonet <alramonet@is.tokushima-u.ac.jp>
* Ryo Okuda <c611901200@tokushima-u.ac.jp>
*/
#ifndef ZIGBEE_NWK_H
#define ZIGBEE_NWK_H
#include "zigbee-group-table.h"
#include "zigbee-nwk-fields.h"
#include "zigbee-nwk-header.h"
#include "zigbee-nwk-payload-header.h"
#include "zigbee-nwk-tables.h"
#include "ns3/event-id.h"
#include "ns3/lr-wpan-mac-base.h"
#include "ns3/mac16-address.h"
#include "ns3/mac64-address.h"
#include "ns3/object.h"
#include "ns3/random-variable-stream.h"
#include "ns3/sequence-number.h"
#include "ns3/traced-callback.h"
#include "ns3/traced-value.h"
#include <cstdint>
#include <iomanip>
#include <iterator>
namespace ns3
{
namespace zigbee
{
/**
* @defgroup zigbee ZIGBEE models
*
* This section documents the API of the Zigbee Specification related models. For a generic
* functional description, please refer to the ns-3 manual.
*/
static constexpr uint32_t ALL_CHANNELS = 0x07FFF800; //!< Bitmap representing all channels (11~26)
//!< LSB b0-b26, b27-b31 MSB
//!< Page 0 in Zigbee (250kbps O-QPSK)
/**
* @ingroup Zigbee
*
* Indicates a pending NWK primitive
*/
enum PendingPrimitiveNwk : std::uint8_t
{
NLDE_NLME_NONE = 0, //!< No pending primitive
NLME_NETWORK_FORMATION = 1, //!< Pending NLME-NETWORK-FORMATION.request primitive
NLME_DIRECT_JOIN = 2, //!< Pending NLME-DIRECT-JOIN.request primitive
NLME_JOIN = 3, //!< Pending NLME-JOIN.request primitive
NLME_START_ROUTER = 4, //!< Pending NLME-START-ROUTER.request primitive
NLME_NET_DISCV = 5, //!< Pending NLME-NETWORK-DISCOVERY.request primitive
NLME_JOIN_INDICATION = 6, //!< Pending NLME-JOIN.indication primitive
NLME_ROUTE_DISCOVERY = 7, //!< Pending NLME-ROUTE-DISCOVERY.request primitive
NLDE_DATA = 8 //!< Pending NLDE-DATA.request primitive
};
/**
* @ingroup Zigbee
*
* Table 3.2 (Address Mode) NLDE-DATA-Request parameters
*/
enum AddressMode
{
NO_ADDRESS = 0x00, //!< No destination address
MCST = 0x01, //!< Multicast Address mode
UCST_BCST = 0x02 //!< Unicast or Broadcast address mode
};
/**
* Use to describe the method used to assign addresses in the NWK layer.
* See Zigbee specification r22.1.0, Table 3-58
*/
enum AddrAllocMethod
{
DISTRIBUTED_ALLOC = 0x00, //!< Distributed address allocation
//!< (Zigbee Specification r22.1.0 Section 3.6.1.6)
STOCHASTIC_ALLOC = 0x02 //!< Stochastic address allocation
//!< (Zigbee Specification r22.1.0 Section 3.6.1.7)
};
/**
* Use to describe the identifier of the zigbee stack profile.
*/
enum StackProfile
{
ZIGBEE = 0x01, //!< Zigbee stack profile 0x01 (a.k.a. Zigbee 2006, Zigbee 2007, Zigbee)
ZIGBEE_PRO = 0x02 //!< Zigbee stack profile 0x02 (Zigbee Pro, also known as r22.1.0, 3.0)
};
/**
* Use to describe the parameter that controls the method of joining the network.
* See Zigbee specification r22.1.0, Table 3-21
*/
enum JoiningMethod
{
ASSOCIATION = 0x00, //!< The device is requesting to join a network through association.
DIRECT_OR_REJOIN = 0x01, //!< The device is joining directly or rejoining using the
//!< orphaning procedure.
REJOINING = 0x02, //!< The device is joining the network using the rejoining procedure.
CHANGE_CHANNEL = 0x03 //!< The device is to change the operational network channel to
//!< that identified in the ScanChannel parameter.
};
/**
* The status returned while attempting to find the next hop in route towards a specific
* destination or a many-to-one route request attempt.
*/
enum RouteDiscoveryStatus : std::uint8_t
{
ROUTE_FOUND = 0x01, //!< The next hop toward the destination was found in our
//!< routing table or neighbor table (Mesh route).
ROUTE_NOT_FOUND = 0x02, //!< The next hop was not found. A new entry is is registered
//!< in the routing table with DISCOVER_UNDERWAY status(Mesh route).
TABLE_FULL = 0x03, //!< Either the routing or neighbor table are full.
ROUTE_UPDATED = 0x04, //!< A route was found and updated with a better route
//!< (Mesh route or Many-To-One route)
NO_DISCOVER_ROUTE = 0x05, //!< We are currently not allowed to perform a route discovery
//!< for this route (RouteDiscover flag in network header is false).
DISCOVER_UNDERWAY = 0x06, //!< The route was found in the tables but currently has no next hop.
//!< i.e. A previous attempt was already made is currently awaiting
//!< for a response (hence the route discover is underway).
MANY_TO_ONE_ROUTE = 0x07, //!< A new Many-To-One route was created
NO_ROUTE_CHANGE = 0x08 //!< No route entry was created or updated during
//!< a Many-To-One process
};
/**
* @ingroup Zigbee
*
* Network layer status values
* Combines Zigbee Specification r22.1.0 Table 3-73 and
* and IEEE 802.15.4-2006 Table 78
*
* Used to report the resulting status of various NWK operations.
*
* Note: UNSUPPORTED_ATTRIBUTE, LIMIT_REACHED, SCAN_IN_PROGRESS
*/
enum NwkStatus : std::uint8_t
{
// MAC defined status:
SUCCESS = 0, //!< The operation was completed successfully.
FULL_CAPACITY = 0x01, //!< PAN at capacity. Association Status field (std. 2006, Table 83).
ACCESS_DENIED = 0x02, //!< PAN access denied. Association Status field (std. 2006, Table 83).
COUNTER_ERROR = 0xdb, //!< The frame counter of the received frame is invalid.
IMPROPER_KEY_TYPE = 0xdc, //!< The key is not allowed to be used with that frame type.
IMPROPER_SECURITY_LEVEL = 0xdd, //!< Insufficient security level expected by the recipient.
UNSUPPORTED_LEGACY = 0xde, //!< Deprecated security used in IEEE 802.15.4-2003
UNSUPPORTED_SECURITY = 0xdf, //!< The security applied is not supported.
BEACON_LOSS = 0xe0, //!< The beacon was lost following a synchronization request.
CHANNEL_ACCESS_FAILURE = 0xe1, //!< A Tx could not take place due to activity in the CH.
DENIED = 0xe2, //!< The GTS request has been denied by the PAN coordinator.
DISABLE_TRX_FAILURE = 0xe3, //!< The attempt to disable the transceier has failed.
SECURITY_ERROR = 0xe4, //!< Cryptographic process of the frame failed(FAILED_SECURITY_CHECK).
FRAME_TOO_LONG = 0xe5, //!< Frame more than aMaxPHYPacketSize or too large for CAP or GTS.
INVALID_GTS = 0xe6, //!< Missing GTS transmit or undefined direction.
INVALID_HANDLE = 0xe7, //!< When purging from TX queue handle was not found.
INVALID_PARAMETER_MAC = 0xe8, //!< Invalid parameter in response to a request passed to the MAC.
NO_ACK = 0xe9, //!< No acknowledgment was received after macMaxFrameRetries.
NO_BEACON = 0xea, //!< A scan operation failed to find any network beacons.
NO_DATA = 0xeb, //!< No response data were available following a request.
NO_SHORT_ADDRESS = 0xec, //!< Failure due to unallocated 16-bit short address.
OUT_OF_CAP = 0xed, //!< (Deprecated) See IEEE 802.15.4-2003
PAN_ID_CONFLICT = 0xee, //!< PAN id conflict detected and informed to the coordinator.
REALIGMENT = 0xef, //!< A coordinator realigment command has been received.
TRANSACTION_EXPIRED = 0xf0, //!< The transaction expired and its information discarded.
TRANSACTION_OVERFLOW = 0xf1, //!< There is no capacity to store the transaction.
TX_ACTIVE = 0xf2, //!< The transceiver was already enabled.
UNAVAILABLE_KEY = 0xf3, //!< Unavailable key, unknown or blacklisted.
INVALID_ADDRESS = 0xf5, //!< Invalid source or destination address.
ON_TIME_TOO_LONG = 0xf6, //!< RX enable request fail due to syms. longer than Bcn. interval
PAST_TIME = 0xf7, //!< Rx enable request fail due to lack of time in superframe.
TRACKING_OFF = 0xf8, //!< This device is currently not tracking beacons.
INVALID_INDEX = 0xf9, //!< A MAC PIB write failed because specified index is out of range.
READ_ONLY = 0xfb, //!< SET/GET request issued for a read only attribute.
SUPERFRAME_OVERLAP = 0xfd, //!< Coordinator sperframe and this device superframe tx overlap.
// Zigbee Specification defined status:
INVALID_PARAMETER = 0xc1, //!< Invalid Parameter (Zigbee specification r22.1.0)
INVALID_REQUEST = 0xc2, //!< Invalid request (Zigbee specification r22.1.0)
NOT_PERMITED = 0xc3, //!< Not permitted (Zigbee specification r22.1.0)
STARTUP_FAILURE = 0xc4, //!< Startup failure (Zigbee specification r22.1.0)
ALREADY_PRESENT = 0xc5, //!< Already present (Zigbee specification r22.1.0)
SYNC_FAILURE = 0xc6, //!< Sync Failure (Zigbee specification r22.1.0)
NEIGHBOR_TABLE_FULL = 0xc7, //!< Neighbor table full (Zigbee specification r22.1.0)
UNKNOWN_DEVICE = 0xc8, //!< Unknown device (Zigbee specification r22.1.0)
UNSUPPORTED_ATTRIBUTE = 0xc9, //!< Unsupported attribute (Zigbee specification r22.1.0)
NO_NETWORKS = 0xca, //!< No network (Zigbee specification r22.1.0)
MAX_FRM_COUNTER = 0xcc, //!< Max Frame counter (IEEE 802.15.4, Zigbee specification r22.1.0)
NO_KEY = 0xcd, //!< No Key (Zigbee specification r22.1.0)
BAD_CCM_OUTPUT = 0xce, //!< Bad ccm output (IEEE 802.15.4, Zigbee specification r22.1.0)
ROUTE_DISCOVERY_FAILED = 0xd0, //!< Route discovery failed (Zigbee specification r22.1.0)
ROUTE_ERROR = 0xd1, //!< Route error (Zigbee specification r22.1.0)
BT_TABLE_FULL = 0xd2, //!< Bt table full (Zigbee specification r22.1.0)
FRAME_NOT_BUFFERED = 0xd3, //!< Frame not buffered (Zigbee specification r22.1.0)
INVALID_INTERFACE = 0xd5, //!< Invalid interface (Zigbee specification r22.1.0)
LIMIT_REACHED = 0xd6, //!< Limit reached during network scan (IEEE 802.15.4-2011)
SCAN_IN_PROGRESS = 0xd7 //!< The dev was scanning during this call (IEEE 802.5.4)
};
/**
* Overloaded operator to print the value of a NwkStatus.
*
* @param os The output stream
* @param state The text value of the NWK state
* @return The output stream with text value of the NWK state
*/
std::ostream& operator<<(std::ostream& os, const NwkStatus& state);
/**
* Overloaded operator to print uint8_t vectors
*
* @param os The output stream
* @param vec The uint8_t vector to print
* @return The output stream with the text value of the uint8_t vector members
*/
std::ostream& operator<<(std::ostream& os, const std::vector<uint8_t>& vec);
/**
*
* @param os The output stream
* @param num The uint8_t number to print
* @return The output stream with the text value of the uint8_t number
*/
std::ostream& operator<<(std::ostream& os, const uint8_t& num);
/**
* @ingroup Zigbee
*
* Status codes for network status command frame and route discovery failures.
*
*/
enum NetworkStatusCode : std::uint8_t
{
NO_ROUTE_AVAILABLE = 0x00, //!< No route available
TREE_LINK_FAILURE = 0x01, //!< Tree link failure
NON_TREE_LINK_FAILURE = 0x02, //!< Non tree link failure
LOW_BATTERY = 0x03, //!< Low battery
NO_ROUTING_CAPACITY = 0x04, //!< No routing capacity
NO_INDIRECT_CAPACITY = 0x05, //!< No indirect capacity
INDIRECT_TRANSACTION_EXPIRY = 0x06, //!< Indirect transaction expiry
TARGET_DEVICE_UNAVAILABLE = 0x07, //!< Target device unavailable
TARGET_ADDRESS_UNALLOCATED = 0x08, //!< Target address unallocated
PARENT_LINK_FAILURE = 0x09, //!< Parent link failure
VALIDATE_ROUTE = 0x0a, //!< Validate route
SOURCE_ROUTE_FAILURE = 0x0b, //!< Source route failure
MANY_TO_ONE_ROUTE_FAILURE = 0x0c, //!< Many to one route failure
ADDRESS_CONFLICT = 0x0d, //!< Address conflict
VERIFY_ADDRESS = 0x0e, //!< Verify address
PAN_IDENTIFIER_UPDATE = 0x0f, //!< PAN identifier update
NETWORK_ADDRESS_UPDATE = 0x10, //!< Network address update
BAD_FRAME_COUNTER = 0x11, //!< Bad frame counter
BAD_KEY_SEQUENCE_NUMBER = 0x12, //!< Bad key sequence number
UNKNOWN_COMMAND = 0x13 //!< Unknown command
};
/**
* @ingroup Zigbee
*
* Channel List Structure. See Zigbee Specification 3.2.2.2.1
*/
struct ChannelList
{
uint8_t channelPageCount; //!< The number of the channel page structures contained in
//!< the channel list structure.
std::vector<uint32_t> channelsField; //!< The set of channels for a given page.
ChannelList()
: channelPageCount(1),
channelsField{ALL_CHANNELS}
{
}
};
/**
* @ingroup Zigbee
*
* NLDE-DATA.confirm params. See Zigbee Specification 3.2.1.2
*/
struct NldeDataConfirmParams
{
NwkStatus m_status{NwkStatus::INVALID_PARAMETER}; //!< The status of
//!< the corresponding request.
uint8_t m_nsduHandle{0}; //!< The handle associated with the NSDU being confirmed.
Time m_txTime{Seconds(0)}; //!< The time indication for the transmitted packet
//!< based on the local clock.
};
/**
* @ingroup Zigbee
*
* NLDE-DATA.indication params. See Zigbee Specification 3.2.1.3.1
*/
struct NldeDataIndicationParams
{
AddressMode m_dstAddrMode{UCST_BCST}; //!< Destination address mode.
//!< 0x01=MCST, 0x02=BCST or UCST
Mac16Address m_dstAddr; //!< The destination address to which the NSDU was sent
Mac16Address m_srcAddr; //!< The individual device address from which the NSDU originated
uint32_t m_nsduLength{0}; //!< The number of octets comprising the NSDU being indicated
uint8_t m_linkQuality{0}; //!< LQI value delivered by the MAC on receipt of this frame
Time m_rxTime{Seconds(0)}; //!< A time indication for the received packet
//!< based on the local clock
bool m_securityUse{false}; //!< An indication of whether the received data is using security
};
/**
* @ingroup Zigbee
*
* NLDE-DATA.request params. See Zigbee Specification 3.2.1.1
*/
struct NldeDataRequestParams
{
AddressMode m_dstAddrMode{UCST_BCST}; //!< Destination address mode.
//!< 0x01=MCST, 0x02=BCST or UCST
Mac16Address m_dstAddr; //!< The destination address.
uint32_t m_nsduLength{0}; //!< The number of octets comprising the NSDU to be transferred.
uint8_t m_nsduHandle{0}; //!< The NSDU handle
bool m_useAlias{false}; //!< Indicates if next higher layer use an alias for the current frame.
Mac16Address m_aliasSrcAddr; //!< The source address to be used by this NSDU
//!< (ignored ifuseAlias = false).
SequenceNumber8 m_aliasSeqNumber; //!< The sequence number used by this NSDU
//!< (ignored if useAlias = false).
uint8_t m_radius{0}; //!< Distance in hops that the frame is allowed to
//!< travel through the network.
uint8_t m_nonMemberRadius{0}; //!< Distance in hops that a multicast frame will be relayed by
//!< nodes not a member of the group. 0x07 = Infinity.
uint8_t m_discoverRoute{0}; //!< 0x01 Enable Route Discovery | 0x00: Suppress Route discovery
bool m_securityEnable{false}; //!< Enable NWK layer security for the current frame.
};
/**
* @ingroup Zigbee
*
* NLME-NETWORK-FORMATION.request params. See Zigbee Specification 3.2.2.5.1
*/
struct NlmeNetworkFormationRequestParams
{
ChannelList m_scanChannelList; //!< A structure
//!< that contain a description on the pages and
//!< their channels to be scanned.
uint8_t m_scanDuration; //!< The time spent of each channel in symbols:
//!< aBaseSuperframeDuriantion * (2n+1). n=0-14
uint8_t m_beaconOrder; //!< The beacon order
uint8_t m_superFrameOrder; //!< The superframe order
bool m_batteryLifeExtension; //!< True: The zigbee coordinator is started supporting
//!< battery extension mode.
bool m_distributedNetwork; //!< Indicates that distributed security will be used.
Mac16Address m_distributedNetworkAddress; //!< The address of the device in a
//!< distributed network.
NlmeNetworkFormationRequestParams()
: m_scanChannelList{},
m_scanDuration(14),
m_beaconOrder(15),
m_superFrameOrder(15),
m_batteryLifeExtension(false),
m_distributedNetwork(false),
m_distributedNetworkAddress("FF:F7")
{
}
};
/**
* @ingroup Zigbee
*
* A group of pending parameters arranged into a structure during the execution of
* a NLME-NETWORK-FORMATION.request primitive.
*/
struct NetFormPendingParamsGen : public SimpleRefCount<NetFormPendingParamsGen>
{
uint8_t channel{0}; //!< The channel selected during the initial steps of a network formation
uint8_t page{0}; //!< The page selected during the initial steps of a network formation.
uint16_t panId{0}; //!< The PAN id selected during the initial steps of a network formation.
};
/**
* @ingroup Zigbee
*
* NLME-NETWORK-FORMATION.confirm params. See Zigbee Specification 3.2.2.6.1
*/
struct NlmeNetworkFormationConfirmParams
{
NwkStatus m_status{NwkStatus::INVALID_PARAMETER}; //!< The status as a result of
//!< this request
};
/**
* @ingroup Zigbee
*
* NLME-ROUTE-DISCOVERY.request params. See Zigbee Specification 3.2.2.33
*/
struct NlmeRouteDiscoveryRequestParams
{
AddressMode m_dstAddrMode{UCST_BCST}; //!< Specifies the kind of destination address.
Mac16Address m_dstAddr; //!< The 16-bit destination address or Group ID (MCST destination)
//!< of the route discovery.
uint16_t m_radius{0}; //!< Optional parameter that describes the number of hops that the
//!< route request will travel through the network.
bool m_noRouteCache{true}; //!< This flag determines whether the NWK should establish a
//!< route record table.
};
/**
* @ingroup Zigbee
*
* NLME-ROUTE-DISCOVERY.confirm params. See Zigbee Specification r22.1.0, 3.2.2.34
*/
struct NlmeRouteDiscoveryConfirmParams
{
NwkStatus m_status{NwkStatus::INVALID_PARAMETER}; //!< The status as a result of
//!< this request.
NetworkStatusCode m_networkStatusCode{NetworkStatusCode::UNKNOWN_COMMAND}; //!< In case where
//!< the status parameter has a value of ROUTE_ERROR, this code gives further information about
//!< the error occurred. Otherwise, it should be ignored.
};
/**
* @ingroup Zigbee
*
* NLME-DIRECT-JOIN.request params.
* See Zigbee Specification r22.1.0, 3.2.2.16
*/
struct NlmeDirectJoinRequestParams
{
Mac64Address m_deviceAddr; //!< The EUI-64 bit address of the device directly joined.
uint8_t m_capabilityInfo; //!< The operating capabilities of the device
//!< being directly joined
};
/**
* @ingroup Zigbee
*
* NLME-DIRECT-JOIN.confirm params.
* See Zigbee Specification r22.1.0, 3.2.2.17
*/
struct NlmeDirectJoinConfirmParams
{
NwkStatus m_status{NwkStatus::INVALID_PARAMETER}; //!< The status
//!< the corresponding request.
Mac64Address m_deviceAddr; //!< The IEEE EUI-64 address in the request to
//!< which this is a confirmation.
};
/**
* @ingroup Zigbee
*
* NLME-NETWORK-DISCOVERY.request params.
* See Zigbee Specification r22.1.0, 3.2.2.3
*/
struct NlmeNetworkDiscoveryRequestParams
{
ChannelList m_scanChannelList; //!< The list of all channel pages and the associated
//!< channels that shall be scanned.
uint8_t m_scanDuration{0}; //!< A value used to calculate the length of time to spend
};
/**
* @ingroup lr-wpan
*
* Network Descriptor, Zigbee Specification r22.1.0, 3.2.2.4, Table 3-12
*/
struct NetworkDescriptor
{
uint64_t m_extPanId{0xFFFFFFFFFFFFFFFE}; //!< The 64-bit PAN identifier of the network.
uint16_t m_panId{0xFFFF}; //!< The 16-bit PAN identifier of the network.
uint8_t m_updateId{0}; //!< The value of the UpdateID from the NIB.
uint8_t m_logCh{11}; //!< The current channel number occupied by the network.
StackProfile m_stackProfile{ZIGBEE_PRO}; //!< The Zigbee stack profile identifier in use in
//!< the discovered network.
uint8_t m_zigbeeVersion; //!< The version of the zigbee protocol in use in
//!< the discovered network.
uint8_t m_beaconOrder{15}; //!< The beacon order value of the underlying MAC
//!< (Determinates the beacon frequency, 15 = No beacon)
uint8_t m_superframeOrder{15}; //!< The superframe order value of the underlying MAC
//!< (Determinates the value of the active period)
bool m_permitJoining{true}; //!< TRUE = Indicates that at least one zigbee router on the
//!< network currently permits joining.
bool m_routerCapacity{true}; //!< TRUE = The device is able to accept join requests from
//!< router-capable devices.
bool m_endDeviceCapacity{true}; //!< TRUE= The device is able to accept join request from
//!< end devices.
};
/**
* @ingroup Zigbee
*
* NLME-NETWORK-DISCOVERY.confirm params. See Zigbee Specification r22.1.0, 3.2.2.4
*/
struct NlmeNetworkDiscoveryConfirmParams
{
NwkStatus m_status{NwkStatus::INVALID_PARAMETER}; //!< The status of
//!< the corresponding request.
uint8_t m_networkCount{0}; //!< Gives the number of networks discovered by the search
std::vector<NetworkDescriptor> m_netDescList; //!< A list of descriptors,
//!< one for each of the networks discovered.
};
/**
* @ingroup Zigbee
*
* NLME-JOIN.request params.
* See Zigbee Specification r22.1.0, 3.2.2.13
*/
struct NlmeJoinRequestParams
{
uint64_t m_extendedPanId{1}; //!< The 64 bit PAN identifier of the
//!< the network to join.
JoiningMethod m_rejoinNetwork; //!< This parameter controls the method of joining the
//!< network.
ChannelList m_scanChannelList; //!< The list of all channel pages and the associated
//!< channels that shall be scanned.
uint8_t m_scanDuration{0}; //!< A value used to calculate the length of time to spend
//!< scanning each channel.
uint8_t m_capabilityInfo; //!< The operating capabilities of the device
//!< being directly joined (Bit map).
bool m_securityEnable{false}; //!< If the value of RejoinNetwork is REJOINING and this
//!< value is true, the device will rejoin securely.
};
/**
* @ingroup Zigbee
*
* NLME-JOIN.confirm params.
* See Zigbee Specification r22.1.0, 3.2.2.15
*/
struct NlmeJoinConfirmParams
{
NwkStatus m_status; //!< The status of
//!< the corresponding request.
Mac16Address m_networkAddress; //!< The 16 bit network address that was allocated
//!< to this device. Equal to 0xFFFF if association
//!< was unsuccessful.
uint64_t m_extendedPanId; //!< The extended 64 bit PAN ID for the network of which the
//!< device is now a member.
ChannelList m_channelList; //!< The structure indicating the current channel of the
//!< network that has been joined.
bool m_enhancedBeacon; //!< True if using enhanced beacons (placeholder, not supported)
uint8_t m_macInterfaceIndex; //!< The value of the MAC index from nwkMacInterfaceTable.
//!< (placeholder, not supported)
NlmeJoinConfirmParams()
: m_status(NwkStatus::INVALID_REQUEST),
m_networkAddress("FF:FF"),
m_extendedPanId(1),
m_channelList{},
m_enhancedBeacon(false),
m_macInterfaceIndex(0)
{
}
};
/**
* @ingroup Zigbee
*
* NLME-JOIN.indication params.
* See Zigbee Specification r22.1.0, 3.2.2.14
*/
struct NlmeJoinIndicationParams
{
Mac16Address m_networkAddress{0xFFFF}; //!< The 16 bit network address of an entity that
//!< has been added to the network.
Mac64Address m_extendedAddress; //!< The EUI-64 bit address of an entity that has been added
//!< to the network.
uint8_t m_capabilityInfo; //!< Specifies the operational capabilities of the
//!< joining device.
JoiningMethod m_rejoinNetwork; //!< This parameter indicates the method used to
//!< join the network.
bool m_secureRejoin{false}; //!< True if the rejoin was performed in a secure manner.
};
/**
* @ingroup Zigbee
*
* NLME-START-ROUTER.request params.
* See Zigbee Specification r22.1.0, 3.2.2.13
*/
struct NlmeStartRouterRequestParams
{
uint8_t m_beaconOrder{15}; //!< The beacon order of the network
uint8_t m_superframeOrder{15}; //!< The superframe order of the network
bool m_batteryLifeExt{false}; //!< True if the router supports battery life extension mode.
};
/**
* @ingroup Zigbee
*
* NLME-START-ROUTER.confirm params.
* See Zigbee Specification r22.1.0, 3.2.2.10
*/
struct NlmeStartRouterConfirmParams
{
NwkStatus m_status{NwkStatus::INVALID_REQUEST}; //!< The status of
//!< the corresponding request.
};
/**
* @ingroup Zigbee
*
* Class that implements the Zigbee Specification Network Layer
*/
class ZigbeeNwk : public Object
{
public:
/**
* Get the type ID.
*
* @return the object TypeId
*/
static TypeId GetTypeId();
/**
* Default constructor.
*/
ZigbeeNwk();
~ZigbeeNwk() override;
/**
* This callback is called after a NSDU has successfully received and
* NWK push it to deliver it to the next higher layer.
*/
using NldeDataIndicationCallback = Callback<void, NldeDataIndicationParams, Ptr<Packet>>;
/**
* This callback is used to notify the next higher layer with a confirmation in response to
* a previously issued NLDE-DATA.request.
*/
using NldeDataConfirmCallback = Callback<void, NldeDataConfirmParams>;
/**
* This callback is used to notify the next higher layer with a confirmation in response to
* a previously issued NLME-NETWORK-FORMATION.request.
*/
using NlmeNetworkFormationConfirmCallback = Callback<void, NlmeNetworkFormationConfirmParams>;
/**
* This callback is used to notify the next higher layer with a confirmation in response to
* a previously issued NLME-NETWORK-DISCOVERY.request.
*/
using NlmeNetworkDiscoveryConfirmCallback = Callback<void, NlmeNetworkDiscoveryConfirmParams>;
/**
* This callback is used to notify the next higher layer with a confirmation in response to
* a previously issued NLME-ROUTE-DISCOVERY.request.
*/
using NlmeRouteDiscoveryConfirmCallback = Callback<void, NlmeRouteDiscoveryConfirmParams>;
/**
* This callback is used to notify the next higher layer with a confirmation in response to
* a previously issued NLME-DIRECT-JOIN.request.
*/
using NlmeDirectJoinConfirmCallback = Callback<void, NlmeDirectJoinConfirmParams>;
/**
* This callback is used to notify the next higher layer with a confirmation in response to
* a previously issued NLME-JOIN.request.
*/
using NlmeJoinConfirmCallback = Callback<void, NlmeJoinConfirmParams>;
/**
* This callback is used to notify the next higher layer with an indication that a new
* device has successfully joined its network by association or rejoining.
*/
using NlmeJoinIndicationCallback = Callback<void, NlmeJoinIndicationParams>;
/**
* This callback is used to notify the next higher layer with a confirmation in response to
* a previously issued NLME-START-ROUTER.request.
*/
using NlmeStartRouterConfirmCallback = Callback<void, NlmeStartRouterConfirmParams>;
/**
* Set the underlying MAC to use in this Zigbee NWK
*
* @param mac The pointer to the underlying LrWpan MAC to set to this Zigbee NWK
*/
void SetMac(Ptr<lrwpan::LrWpanMacBase> mac);
/**
* Get the group table used by this Zigbee NWK.
*
* @param groupTable The pointer to the group table to set.
*/
void SetGroupTable(Ptr<ZigbeeGroupTable> groupTable);
/**
* Get the underlying MAC used by the current Zigbee NWK.
*
* @return The pointer to the underlying MAC object currently connected to the Zigbee NWK.
*/
Ptr<lrwpan::LrWpanMacBase> GetMac() const;
/**
* Print the entries in the routing table.
*
* @param stream The stream object used to print.
*/
void PrintRoutingTable(Ptr<OutputStreamWrapper> stream) const;
/**
* Print the entries in the route discovery table.
*
* @param stream The stream object used to print.
*/
void PrintRouteDiscoveryTable(Ptr<OutputStreamWrapper> stream);
/**
* Print the entries in the neighbor table.
*
* @param stream The stream object used to print.
*/
void PrintNeighborTable(Ptr<OutputStreamWrapper> stream) const;
/**
* Print the entries in the RREQ retry table.
*
* @param stream The stream object used to print.
*/
void PrintRREQRetryTable(Ptr<OutputStreamWrapper> stream) const;
/**
* Search for a specific destination in this device
* neighbor and routing tables.
* This function is only a quick reference used for debugging
* purposes.
*
* @param dst The destination to search in our tables
* @param neighbor A flag indicating whether or not the returned
* next hop was found in our neighbor table.
* @return The nexthop address to the destination.
*/
Mac16Address FindRoute(Mac16Address dst, bool& neighbor);
/**
* Obtain this device 16 bit network address (A.K.A. short address).
*
* This function should only be used for debugging purposes and it
* should not be use by higher layers. Higher layers should use
* NLME-GET.request instead to obtain this attribute.
*
* @return Returns this device's 16 bit network address.
*/
Mac16Address GetNetworkAddress() const;
/**
* Obtain this device 64 bit IEEE address (A.K.A. extended address).
*
* This function should only be used for debugging purposes and it
* should not be use by higher layers. Higher layers should use
* NLME-GET.request instead to obtain this attribute.
*
* @return Returns this device's 16 bit network address.
*/
Mac64Address GetIeeeAddress() const;
/**
* IEEE 802.15.4-2011 section 6.3.3
* MCPS-DATA.indication
* Indicates the reception of an MSDU from MAC to NWK (receiving)
*
* @param params The MCPS-DATA.indication parameters.
* @param msdu The set of octets forming the MSDU.
*/
void McpsDataIndication(lrwpan::McpsDataIndicationParams params, Ptr<Packet> msdu);
/**
* IEEE 802.15.4-2011 section 6.3.2
* MCPS-DATA.confirm
* Reports the results of a request to a transfer data to another device.
*
* @param params The MCPS-DATA.confirm parameters.
*/
void McpsDataConfirm(lrwpan::McpsDataConfirmParams params);
/**
* IEEE 802.15.4-2011 section 6.2.10.2
* MLME-SCAN.confirm
* Reports the results of a scan request.
*
* @param params The MLME-SCAN.confirm parameters.
*/
void MlmeScanConfirm(lrwpan::MlmeScanConfirmParams params);
/**
* IEEE 802.15.4-2011 section
* MlME-ASSOCIATE.confirm
* Report the results of an associate request attempt.
*
* @param params The MLME-ASSOCIATE.confirm parameters.
*/
void MlmeAssociateConfirm(lrwpan::MlmeAssociateConfirmParams params);
/**
* IEEE 802.15.4-2011 section 7.1.14.2
* MLME-START.confirm
* Reports the results of a network start request.
*
* @param params The MLME-START.confirm parameters.
*/
void MlmeStartConfirm(lrwpan::MlmeStartConfirmParams params);
/**
* IEEE 802.15.4-2011 section 6.2.11.2
* MLME-SET.confirm
* Reports the result of an attempt to change a MAC PIB attribute.
*
* @param params The MLME-SET.confirm params
*/
void MlmeSetConfirm(lrwpan::MlmeSetConfirmParams params);
/**
* IEEE 802.15.4-2011 section 6.2.5.1
* MLME-GET.confirm
* Reports the result of an attempt to obtain a MAC PIB attribute.
*
* @param status The status as a result of a MLME-GET.request operation
* @param id The identififier of the attribute requested
* @param attribute The value of of the attribute requested
*/
void MlmeGetConfirm(lrwpan::MacStatus status,
lrwpan::MacPibAttributeIdentifier id,
Ptr<lrwpan::MacPibAttributes> attribute);
/**
* IEEE 802.15.4-2011 sections 6.2.7.1,
* Zigbee Specification r22.1.0 Section 3.6.1.4.3 (parent procedure)
* MLME-ORPHAN.indication
* Generated by the coordinator and issued to its next higher
* layer on receipt of an orphan notification command, as defined
* in 5.3.6.
*
* @param params The MLME-ORPHAN.indication parameters
*/
void MlmeOrphanIndication(lrwpan::MlmeOrphanIndicationParams params);
/**
* IEEE 802.15.4-2011 section 6.2.4.2
* MLME-COMM-STATUS.indication
* Allows the MAC MLME to indicate a communication status.
*
* @param params The MLME-COMM-STATUS.indication parameters
*/
void MlmeCommStatusIndication(lrwpan::MlmeCommStatusIndicationParams params);
/**
* IEEE 802.15.4-2011, Section 6.2.4.1
* MLME-BEACON-NOTIFY.indication
* Allows the MAC MLME to indicate the reception of a beacon with payload.
*
* @param params The MLME-BEACON-NOTIFY.indication parameters
*/
void MlmeBeaconNotifyIndication(lrwpan::MlmeBeaconNotifyIndicationParams params);
/**
* IEEE 802.15.4-2011, Section 6.2.2.2.
* MLME-ASSOCIATE.indication
* Allows the MAC MLME to indicate the reception of an associate request
* on a PAN coordinator or router. In the Zigbee specification this implements
* the parent procedure when a device join a network through association
* (See Zigbee specification r22.1.0, Section 3.6.1.4.1)
*
* @param params The MLME-ASSOCIATE.indication parameters
*/
void MlmeAssociateIndication(lrwpan::MlmeAssociateIndicationParams params);
/**
* Zigbee Specification r22.1.0, Section 3.2.1.1
* NLDE-DATA.request
* Request to transfer a NSDU.
*
* @param params the request parameters
* @param packet the NSDU to be transmitted
*/
void NldeDataRequest(NldeDataRequestParams params, Ptr<Packet> packet);
/**
* Zigbee Specification r22.1.0, Section 3.2.2.5 and 3.6.1.1
* NLME-NETWORK-FORMATION.request
* Request the formation of a network in a capable device.
*
* @param params the network formation request params
*/
void NlmeNetworkFormationRequest(NlmeNetworkFormationRequestParams params);
/**
* Zigbee Specification r22.1.0, section 3.2.2.33.3 and 3.6.3.5
* NLME-ROUTE-DISCOVERY.request
* Allows the next higher layer to initiate route discovery.
*
* @param params the route discovery request params
*/
void NlmeRouteDiscoveryRequest(NlmeRouteDiscoveryRequestParams params);
/**
* Zigbee Specification r22.1.0, section 3.2.2.3
* NLME-NETWORK-DISCOVERY.request
* Allows the next higher layer to request that the NWK layer discover
* networks currently operating within the personal operating space (POS).
*
* @param params the network discovery request params
*/
void NlmeNetworkDiscoveryRequest(NlmeNetworkDiscoveryRequestParams params);
/**
* Zigbee Specification r22.1.0, section 3.2.2.16 and 3.6.1.4.3
* NLME-DIRECT-JOIN.request
* Allows the next layer of a Zigbee coordinator or router to request to
* directly join another device to its network
*
* @param params the direct join request params
*/
void NlmeDirectJoinRequest(NlmeDirectJoinRequestParams params);
/**
* Zigbee Specification r22.1.0, section 3.2.2.13
* NLME-JOIN.request
* This primitive allows the next higher layer to request to join or rejoin a
* network, or to change the operating channel for the device while within an
* operating network.
*
* @param params the join request params
*/
void NlmeJoinRequest(NlmeJoinRequestParams params);
/**
* Zigbee Specification r22.1.0, section 3.2.2.9
* NLME-START-ROUTER.request
* This primitive allows the next higher layer of a Zigbee router to initiate
* the activities expected of a Zigbee router including the routing of data
* framaes, route discovery, and the accepting of request to join the network
* from other devices.
*
* @param params the join request params
*/
void NlmeStartRouterRequest(NlmeStartRouterRequestParams params);
/**
* Set the callback for the end of a RX, as part of the
* interconnections between the NWK and the APS sublayer. The callback
* implements the callback used in a NLDE-DATA.indication.
* @param c the NldeDataIndication callback
*/
void SetNldeDataIndicationCallback(NldeDataIndicationCallback c);
/**
* Set the callback as part of the interconnections between the NWK and
* the APS sublayer (or any other higher layer). The callback
* implements the callback used in a NLDE-DATA.confirm
*
* @param c the NldeDataConfirm callback
*/
void SetNldeDataConfirmCallback(NldeDataConfirmCallback c);
/**
* Set the callback as part of the interconnections between the NWK and the
* APS sublayer (or any other higher layer). The callback implements the callback
* used in a NLME-NETWORK-FORMATION.confirm
* @param c the NlmeNetworkFormationConfirm callback
*/
void SetNlmeNetworkFormationConfirmCallback(NlmeNetworkFormationConfirmCallback c);
/**
* Set the callback as part of the interconnections between the NWK and the
* APS sublayer (or any other higher layer). The callback implements the callback
* used in a NLME-NETWORK-DISCOVERY.confirm
* @param c the NlmeNetworkDiscoveryConfirm callback
*/
void SetNlmeNetworkDiscoveryConfirmCallback(NlmeNetworkDiscoveryConfirmCallback c);
/**
* Set the callback as part of the interconnections between the NWK and the
* APS sublayer (or any other higher layer). The callback implements the callback
* used in a NLME-ROUTE-DISCOVERY.confirm
*
* @param c the NlmeRouteDiscoveryConfirm callback
*/
void SetNlmeRouteDiscoveryConfirmCallback(NlmeRouteDiscoveryConfirmCallback c);
/**
* Set the callback as part of the interconnections between the NWK and the
* APS sublayer (or any other higher layer). The callback implements the callback
* used in a NLME-DIRECT-JOIN.confirm
*
* @param c the NlmeDirectJoinConfirm callback
*/
void SetNlmeDirectJoinConfirmCallback(NlmeDirectJoinConfirmCallback c);
/**
* Set the callback as part of the interconnections between the NWK and the
* APS sublayer (or any other higher layer). The callback implements the callback
* used in a NLME-JOIN.confirm
*
* @param c the NlmeJoinConfirm callback
*/
void SetNlmeJoinConfirmCallback(NlmeJoinConfirmCallback c);
/**
* Set the callback as part of the interconnections between the NWK and the
* APS sublayer (or any other higher layer). The callback implements the callback
* used in a NLME-JOIN.indication
*
* @param c the NlmeJoinIndication callback
*/
void SetNlmeJoinIndicationCallback(NlmeJoinIndicationCallback c);
/**
* Set the callback as part of the interconnections between the NWK and the
* APS sublayer (or any other higher layer). The callback implements the callback
* used in a NLME-START-ROUTER.confirm
*
* @param c the NlmeStartRouterConfirm callback
*/
void SetNlmeStartRouterConfirmCallback(NlmeStartRouterConfirmCallback c);
/**
* Assign a fixed random variable stream number to the random variables
* used by this model. Return the number of streams (possibly zero) that
* have been assigned.
*
* @param stream first stream index to use
* @return the number of stream indices assigned by this model
*/
int64_t AssignStreams(int64_t stream);
/**
* TracedCallback signature for RreqRetriesExhaustedTrace events.
*
* @param rreqId The RREQ id used in the retries
* @param dst The destination address of the RREQ retries
* @param rreqRetriesNum The number of rreq retries attempted
*
*/
typedef void (*RreqRetriesExhaustedTracedCallback)(uint8_t rreqId,
Mac16Address dst,
uint8_t rreqRetriesNum);
protected:
void DoInitialize() override;
void DoDispose() override;
void NotifyConstructionCompleted() override;
private:
Ptr<lrwpan::LrWpanMacBase> m_mac; //!< Pointer to the underlying MAC
//!< connected to this Zigbee NWK.
/**
* Structure representing an element in the pending transaction queue.
*/
struct PendingTxPkt : public SimpleRefCount<PendingTxPkt>
{
uint8_t nsduHandle; //!< The NSDU handle
Mac16Address dstAddr; //!< The destination network Address
Ptr<Packet> txPkt; //!< The pending packet.
Time expireTime; //!< The expiration time of the packet
};
/**
* The pending transaction queue of data packets awaiting to be transmitted
* until a route to the destination becomes available.
*/
std::deque<Ptr<PendingTxPkt>> m_pendingTxQueue;
/**
* The maximum size of the pending transaction queue.
*/
uint32_t m_maxPendingTxQueueSize;
/**
* Structure representing an element in the Tx Buffer.
*/
struct TxPkt : public SimpleRefCount<TxPkt>
{
uint8_t macHandle; //!< The mac handle (msdu handle).
uint8_t nwkHandle; //!< The nwk handle (nsdu handle).
Ptr<Packet> txPkt; //!< The buffered packet.
};
/**
* The transmission buffer. Copies of DATA packets are stored here
* for post transmission handling.
*/
std::deque<Ptr<TxPkt>> m_txBuffer;
/**
* The maximum size of the transmission buffer
*/
uint8_t m_txBufferMaxSize;
///////////////
// Callbacks //
///////////////
/**
* A trace source that fires when a node has reached the maximum number
* of RREQ retries allowed. The trace provides the RREQ Id, the destination
* address of the RREQ and the number of the maximum allowed retries from
* this node.
*
*/
TracedCallback<uint8_t, Mac16Address, uint8_t> m_rreqRetriesExhaustedTrace;
/**
* This callback is used to notify incoming packets to the APS sublayer.
* See Zigbee Specification r22.1.0, section 6.2.1.3.
*/
NldeDataIndicationCallback m_nldeDataIndicationCallback;
/**
* This callback is used to respond to data PDU (NSDU) transfer
* request issued by APS sublayer to the NWK (or a layer higher to NWK).
* See Zigbee specification r22.1.0, section 3.2.1.2.
*/
NldeDataConfirmCallback m_nldeDataConfirmCallback;
/**
* This callback is used to to notify the results of a network
* formation to the APS sublayer making the request.
* See Zigbee specification r22.1.0, section 3.2.2.5
*/
NlmeNetworkFormationConfirmCallback m_nlmeNetworkFormationConfirmCallback;
/**
* This callback is used to to notify the results of a network
* formation to the APS sublayer making the request.
* See Zigbee specification r22.1.0, section 3.2.2.4
*/
NlmeNetworkDiscoveryConfirmCallback m_nlmeNetworkDiscoveryConfirmCallback;
/**
* This callback is used to to notify the results of a network
* formation to the APS sublayer making the request.
* See Zigbee specification r22.1.0, section 3.2.2.34
*/
NlmeRouteDiscoveryConfirmCallback m_nlmeRouteDiscoveryConfirmCallback;
/**
* This callback is used by the next layer of a zigbee coordinator or
* router to be notified of the result of its request to directly join
* another device to its network
* See Zigbee specification r22.1.0, section 3.2.2.17
*/
NlmeDirectJoinConfirmCallback m_nlmeDirectJoinConfirmCallback;
/**
* This callback is used by the next layer of a zigbee router or device
* to be notified of the result of its request to join
* another device network.
* See Zigbee specification r22.1.0, section 3.2.2.15
*/
NlmeJoinConfirmCallback m_nlmeJoinConfirmCallback;
/**
* This callback is used by the next layer of a zigbee coordinator or
* router to be notified when a new device has successfully joined its
* network by association or rejoined procedures.
* See Zigbee specification r22.1.0, section 3.2.2.14
*/
NlmeJoinIndicationCallback m_nlmeJoinIndicationCallback;
/**
* This callback is used by the next layer of a zigbee router or device
* to be notified of the result of its request to initiate activities
* as a zigbee router
* See Zigbee specification r22.1.0, section 3.2.2.10
*/
NlmeStartRouterConfirmCallback m_nlmeStartRouterConfirmCallback;
/**
* The parameters used during a NLME-NETWORK-FORMATION.request. These parameters
* are stored here while the scanning operations and network initialization
* procedures take place.
*/
NlmeNetworkFormationRequestParams m_netFormParams;
/**
* The values temporarily stored as a result of the initial steps of a
* NLME-NETWORK-FORMATION.request (i.e. after the first energy scan)
* Page, Channel, PanId.
*/
Ptr<NetFormPendingParamsGen> m_netFormParamsGen;
/**
* The parameters used during a NLME-JOIN.request. These parameters
* are stored here while the scanning operations and network joining
* procedures take place.
*/
NlmeJoinRequestParams m_joinParams;
/**
* Temporarily store the NLME-JOIN.indication parameters while the
* join operations (asocciation) conclude in the coordinator or router.
*/
NlmeJoinIndicationParams m_joinIndParams;
/**
* Temporarily store the NLME-START-ROUTER.request parameters during
* the router initialization process.
*/
NlmeStartRouterRequestParams m_startRouterParams;
/**
* Temporarily store MLME-ASSOCIATE.request parameters
* during a NLME-JOIN.request.
*/
lrwpan::MlmeAssociateRequestParams m_associateParams;
/**
* The maximum acceptable energy level used in an energy scan taking place
* during a NLME-NETWORK-FORMATION.request.
*/
uint8_t m_scanEnergyThreshold;
/**
* Contains the list of channels with acceptable energy levels in a bitmap form.
* This is the result of an Energy Detection (ED) scan during
* a NLME-NETWORK-FORMATION.request
*/
uint32_t m_filteredChannelMask;
/**
* Indicates the current primitive in use in the NWK layer.
*/
PendingPrimitiveNwk m_pendPrimitiveNwk;
/**
* The network layer neighbor table
* See Zigbee specification r22.1.0, 3.6.1.5
*/
NeighborTable m_nwkNeighborTable;
/**
* Use to keep track of neighboring 16 bit PAN id.
* This information is used during the Join process (Association).
*/
PanIdTable m_panIdTable;
/**
* The network layer routing table
* See Zigbee specification r22.1.0, 3.6.3.2
*/
RoutingTable m_nwkRoutingTable;
/**
* The network route discovery table
* See Zigbee specification r22.1.0, 3.6.3.2
*/
RouteDiscoveryTable m_nwkRouteDiscoveryTable;
/**
* Keep track of all the route request retries.
*/
RreqRetryTable m_rreqRetryTable;
/**
* The broadcast transaction table.
* See Zigbee specification r22.1.0, 3.6.5
*/
BroadcastTransactionTable m_btt;
/**
* The Group Table used by this Zigbee NWK.
* See Zigbee specification r22.1.0, 3.6.3.2
*/
Ptr<ZigbeeGroupTable> m_nwkGroupIdTable;
/**
* Enqueue a packet in the pending transmission queue until
* a route is discovered for its destination.
*
* @param p The packet to enqueue.
* @param nsduHandle The handle associated to this packet
*/
void EnqueuePendingTx(Ptr<Packet> p, uint8_t nsduHandle);
/**
* Dequeue a packet previously enqueued in the pending transmission queue.
* This is called after a route has successfully be found and the DATA
* packet is ready to be transmitted.
*
* @param dst The destination of the packet
* @param entry The pending packet element
*
* @return True if successfully dequeued
*/
bool DequeuePendingTx(Mac16Address dst, Ptr<PendingTxPkt> entry);
/**
* Dispose of all PendingTxPkt accumulated in the pending transmission queue.
*/
void DisposePendingTx();
/**
* Buffer a copy of a DATA frame for post transmission handling
* (Transmission failure counts, retransmission of DATA broadcasts,
* push of confirm notifications to the next layer)
*
* @param p The DATA packet to be buffered in the TxPkt buffer.
* @param macHandle The mac layer handle (msdu handle) associated to this frame.
* @param nwkHandle The nwk layer handle (nsdu handle) associated to this frame.
*/
void BufferTxPkt(Ptr<Packet> p, uint8_t macHandle, uint8_t nwkHandle);
/**
* Retrieves a previously DATA frame buffered in the TxPkt buffer.
* If the frame is successfully retrieved, the entry is removed from the
* TxPkt buffer.
*
* @param macHandle The mac layer handle (msdu handle) associated to this frame.
* @param txPkt The packet buffered in the TxPkt buffer.
* @return True if the txPkt is successfully retrieved.
*/
bool RetrieveTxPkt(uint8_t macHandle, Ptr<TxPkt>& txPkt);
/**
* Dispose of all the entries in the TxPkt Buffer.
*/
void DisposeTxPktBuffer();
/**
* Cast a Mac layer status to a NWK layer status.
*
* @param macStatus The Mac layer status to be casted.
* @return The ZigbeeNwkStatus resulting from the cast.
*/
NwkStatus GetNwkStatus(lrwpan::MacStatus macStatus) const;
/**
* Used by a Zigbee coordinator or router to allocate a
* 16 bit address (A.K.A short address or network address)
* to its associated device upon request.
*
* @return The allocated 16 bit address by this router or Zigbee coordinator.
*/
Mac16Address AllocateNetworkAddress();
/**
* Create and store a MAC beacon payload, then updates its registered size in the MAC.
* This is typically followed by updating the content of the beacon payload.
*/
void UpdateBeaconPayloadLength();
/**
* Updates the content of the beacon payload with the most recent information in the NWK.
*/
void UpdateBeaconPayload();
/**
* Get a non linear representation of a Link Quality Indicator (LQI).
* This is used to obtain LQI representations used in the link cost/Path cost
* of a route discovery and the Outgoing cost in the neighbors table.
*
* @param lqi The LQI value (1-255) mapped
* @return The LQI value mapped to a non linear representation (1-7)
*/
uint8_t GetLQINonLinearValue(uint8_t lqi) const;
/**
* Obtain the link cost based on the value of the nwkReportConstantCost.
* If nwkReportConstantCost is True, the link will use a constant value of 7,
* if false, it will use the LQI to obtain the link cost.
* When the LQI option is used, the link cost is based on a non linear mapping
* of LQI values.
* See Zigbee specification r22.1.0, 3.6.3.1
* See NXP Zigbee 3.0 Stack User Guide (JN-UG-3113, revision 1.5), page 108.
*
* @param lqi The lqi value (1-255) used to calculate the link cost.
* @return The link cost (1-7).
*/
uint8_t GetLinkCost(uint8_t lqi) const;
/**
* Send a route request command.
* See Zigbee specification r22.1.0, Section 3.4.1
*
* @param nwkHeader The network header of the RREQ packet to send
* @param payload The payload header of the RREQ packet to send
* @param rreqRetries The maximum number of retries the broadcast transmission of a route
* request command frame is retried. Only valid for non Many-To-One RREQs.
*/
void SendRREQ(ZigbeeNwkHeader nwkHeader,
ZigbeePayloadRouteRequestCommand payload,
uint8_t rreqRetries);
/**
* Handles the reception of a route request command.
* See Zigbee specification r22.1.0, Section 3.6.3.5.2
*
* @param macSrcAddr The MAC header source address
* @param nwkHeader The received network Header
* @param payload The received route request command payload
* @param linkCost The link cost associated to the received RREQ
*/
void ReceiveRREQ(Mac16Address macSrcAddr,
uint8_t linkCost,
ZigbeeNwkHeader nwkHeader,
ZigbeePayloadRouteRequestCommand payload);
/**
* Construct and send a route reply command.
* See Zigbee specification r22.1.0, Section 3.4.2
*
* @param nextHop The address of the next hop in the path back to the RREQ originator.
* @param originator The address of the originator device of the first RREQ.
* @param responder The address of the first device responding to the RREQ with a RREP.
* @param rreqId The RREQ identifier of the originator RREQ.
* @param pathcost The sum value of link costs along the way.
*/
void SendRREP(Mac16Address nextHop,
Mac16Address originator,
Mac16Address responder,
uint8_t rreqId,
uint8_t pathcost);
/**
* Handles the reception of a route reply command.
* See Zigbee specification r22.1.0, Section 3.6.3.5.3
*
* @param macSrcAddr The MAC source address of this reply (a.k.a. previous hop)
* @param nwkHeader The received network Header
* @param payload The received route reply command payload
* @param linkCost The link cost associated to the received RREP
*/
void ReceiveRREP(Mac16Address macSrcAddr,
uint8_t linkCost,
ZigbeeNwkHeader nwkHeader,
ZigbeePayloadRouteReplyCommand payload);
/**
* Process a Multicast Frame received as a member of a multicast group.
* See Zigbee specification r22.1.0 Section 3.6.6.3
*
* @param nwkHeader The network header of the received multicast frame.
* @param msdu The MSDU (MSDU = MAC Service Data Unit) received
* @param params The MCPS-DATA.indication parameters associated to the received frame.
*/
void ReceiveMulticastMemberFrame(ZigbeeNwkHeader nwkHeader,
Ptr<Packet> msdu,
lrwpan::McpsDataIndicationParams params);
/**
* Process a Multicast Frame received as a non member of a multicast group.
* See Zigbee specification r22.1.0 Section 3.6.6.4
*
* @param nwkHeader The network header of the received multicast frame.
* @param msdu The MSDU (MSDU = MAC Service Data Unit) received
* @param params The MCPS-DATA.indication parameters associated to the received frame.
*/
void ReceiveMulticastNonMemberFrame(ZigbeeNwkHeader nwkHeader,
Ptr<Packet> msdu,
lrwpan::McpsDataIndicationParams params);
/**
* Returns true if the address is a broadcast address according to
* Zigbee specification r22.1.0, Section 3.6.5, Table 3-69
*
* @param address The address to compare to a broadcast address
* @return True if the address in a broadcast address
*/
bool IsBroadcastAddress(Mac16Address address);
/**
* Send a data unicast packet, and if necessary look for the next hop route
* and store the pending data transmission until a route is found.
*
* @param packet The NPDU (nwkHeader + data payload) to transmit.
* @param nwkHandle The NWK handle associated to this packet (nsdu handle).
* A handle of 0 implies that the unicast transmission is a
* retransmission and do not requires a handle which is
* used to identify a packet in confirmations to
* requests (NLDE-DATA.confirm).
*/
void SendDataUcst(Ptr<Packet> packet, uint8_t nwkHandle);
/**
* Send a data broadcast packet, and add a record to the broadcast transaction
* table (BTT).
*
* @param packet The NPDU (nwkHeader + data payload) to transmit.
* @param nwkHandle The NWK handle associated to this packet (nsdu handle).
* A handle of 0 implies that the unicast transmission is a
* retransmission and do not requires a handle which is
* used to identify a packet in confirmations to
* requests (NLDE-DATA.confirm).
*/
void SendDataBcst(Ptr<Packet> packet, uint8_t nwkHandle);
/**
* Send a data multicast packet to all the members of a multicast group.
*
* @param packet The NPDU (nwkHeader + data payload) to transmit.
* @param nwkHandle The NWK handle associated to this packet (nsdu handle).
* A handle of 0 implies that the unicast transmission is a
* retransmission and do not requires a handle which is
* used to identify a packet in confirmations to
* requests (NLDE-DATA.confirm).
*/
void SendDataMcst(Ptr<Packet> packet, uint8_t nwkHandle);
/**
* Find the next hop in route to a destination.
*
* See RouteDiscoveryStatus enumeration for full information on the returned status.
*
* @param macSrcAddr The MAC address received from the previous hop.
* @param pathCost The path cost accumulated in the route discovery so far.
* @param nwkHeader The network header created at the initiator or the received RREQ.
* @param payload The payload header of the initiator or the received RREQ.
* @param nextHop If the destination is found in the routing or neighbor tables
* it contains the address of the next hop towards the destination.
*
* @return The RouteDiscoveryStatus of the route search attempt
*/
RouteDiscoveryStatus FindNextHop(Mac16Address macSrcAddr,
uint8_t pathCost,
ZigbeeNwkHeader nwkHeader,
ZigbeePayloadRouteRequestCommand payload,
Mac16Address& nextHop);
/**
* Process Many-To-One routes. In essence, creating new routes or updating
* existing ones from information contained in the received RREQs.
*
* @param macSrcAddr The MAC address received from the previous hop
* @param pathCost The path cost accumulated in the route discovery so far.
* @param nwkHeader The network header created at the initiator or the received RREQ.
* @param payload The payload header created at the initiator or the received RREQ.
*
* @return The resulting RouteDiscoveryStatus of the Many-To-One process request.
*/
RouteDiscoveryStatus ProcessManyToOneRoute(Mac16Address macSrcAddr,
uint8_t pathCost,
ZigbeeNwkHeader nwkHeader,
ZigbeePayloadRouteRequestCommand payload);
/**
* Provides uniform random values
*/
Ptr<UniformRandomVariable> m_uniformRandomVariable;
/**
* Provides uniform random values for the route request jitter
*/
Ptr<UniformRandomVariable> m_rreqJitter;
/**
* Provides uniform random values for the broadcast jitter
*/
Ptr<UniformRandomVariable> m_bcstJitter;
/**
* Temporarily store beacons information from POS routers and PAN coordinators
* during a network-discovery process.
*/
std::vector<NetworkDescriptor> m_networkDescriptorList;
/**
* Points to the beacon payload used during the network formation process.
*/
Ptr<Packet> m_beaconPayload;
/**
* Used to store the value of the PHY current channel.
*/
uint8_t m_currentChannel;
/////////////////////////////
// Network layer constants //
/////////////////////////////
/**
* Indicates whether the device is capable of becoming the ZigBee coordinator
* Zigbee Specification r22.1.0, Table 3-57. Defined as a constant in the specification
* but here is defined as variable to be able to change the devices capabilities.
*/
bool m_nwkcCoordinatorCapable;
/**
* Indicates the version of the ZigBee NWK protocol in the device.
* Zigbee Specification r22.1.0, Table 3-57. Defined as a constant in the specification
* but here is defined as variable to be able to change the devices capabilities.
*/
uint8_t m_nwkcProtocolVersion;
/**
* Indicates the duration until a route discovery expires.
* Zigbee Specification r22.1.0, Table 3-57. Defined as a constant in the specification
* but here is defined as variable to be able to change the devices capabilities.
*/
Time m_nwkcRouteDiscoveryTime;
/**
* The number of times the first broadcast transmission of a route request command
* frame is retried. Zigbee Specification r22.1.0, Table 3-57. Defined as a constant
* in the specification but here is defined as variable to allow the selection of values
* per device.
*/
uint8_t m_nwkcInitialRREQRetries;
/**
* The number of times the broadcast transmission of a route request command frame is
* retried on relay by an intermediate Zigbee router or coordinator.
* Zigbee Specification r22.1.0, Table 3-57. Defined as a constant
* in the specification but here is defined as variable to allow the selection of values
* per device.
*/
uint8_t m_nwkcRREQRetries;
/**
* Count the number of retries this device has transmitted an RREQ
*/
uint8_t m_countRREQRetries;
/**
* Duration between retries of a broadcast route request command frame.
* Zigbee Specification r22.1.0, Table 3-57. Defined as a constant
* in the specification but here is defined as variable to allow the selection of values
* per device.
*/
Time m_nwkcRREQRetryInterval;
/**
* Minimum Route request broadcast jitter time (msec).
* Zigbee Specification r22.1.0, Table 3-57. Defined as a constant
* in the specification but here is defined as variable to allow the selection of values
* per device.
*/
double m_nwkcMinRREQJitter;
/**
* Maximum Route request broadcast jitter time (msec).
* Zigbee Specification r22.1.0, Table 3-57. Defined as a constant
* in the specification but here is defined as variable to allow the selection of values
* per device.
*/
double m_nwkcMaxRREQJitter;
/**
* Minimum Broadcast jitter time (msec).
* Zigbee Specification r22.1.0, Table 3-57. Defined as a constant
* in the specification but here is defined as variable to allow the selection of values
* per device.
*/
double m_nwkcMaxBroadcastJitter;
//////////////////////////////
// Network layer attributes //
//////////////////////////////
/**
* A value that determines the method used to assign addresses.
* See Zigbee specification r22.1.0, Table 3-58
*/
AddrAllocMethod m_nwkAddrAlloc;
/**
* The depth a device can have.
* Default value defined in the stack profile.
* See Zigbee specification r22.1.0 Layer protocol implementation conformance statement (PICS)
* and stack profiles (Section 10.4.2.1)
*/
uint8_t m_nwkMaxDepth;
/**
* The number of children a device is allowed to have on its current network.
* Default value defined in the stack profile.
* See Zigbee PRO/2007 Layer protocol implementation conformance statement (PICS)
* and stack profiles (Section 10.4.2.1)
*/
uint16_t m_nwkMaxChildren;
/**
* The number of routers any one device is allowed to have as children. This is
* determined by the zigbee coordinator for all devices in the network.
* This value is not used if stochastic address allocation is used.
* Default value defined in the stack profile.
* See Zigbee PRO/2007 Layer protocol implementation conformance statement (PICS)
* and stack profiles (Section 10.4.2.1)
*/
uint16_t m_nwkMaxRouters;
/**
* Describes the current stack profile used in this NWK layer
*/
StackProfile m_nwkStackProfile;
/**
* Indicates the index of the requested timeout field that contains the timeout
* in minutes for any end device that does not negotiate a different timeout
* value.
* See Zigbee specification r22.1.0, Table 3-58 (NIB attributes)
*/
uint16_t m_nwkEndDeviceTimeoutDefault;
/**
* The extended PAN identifier for the PAN of which the device is a member.
* A value of 0 means that the extended PAN identifier is unknown.
* See Zigbee specification r22.1.0, Table 3-58 (NIB attributes)
*/
uint64_t m_nwkExtendedPanId;
/**
* The 16-bit address that the device uses to communicate with the PAN.
* This attribute reflects the value of the MAC PIB attribute macShortAddress
* See Zigbee specification r22.1.0, Table 3-58 (NIB attributes)
*/
Mac16Address m_nwkNetworkAddress;
/**
* The EUI 64 bit IEEE address of the local device.
* See Zigbee specification r22.1.0, Table 3-58 (NIB attributes)
*/
Mac64Address m_nwkIeeeAddress;
/**
* This NIB attribute should, at all times, have the same value as macPANId .
* See Zigbee specification r22.1.0, Table 3-58 (NIB attributes)
*/
uint16_t m_nwkPanId;
/**
*
* The behavior depends upon whether the device is a FFD or RFD.
* For RFD, this records the information received in an End device timeout
* response command indicating the parent information (Table 3-55).
* For FFD, this records the device's local capabilities.
* See Zigbee specification r22.1.0, Table 3-58 (NIB attributes)
*/
uint8_t m_nwkParentInformation;
/**
* This NIB attribute contains the device capability information established
* at network joining time.
* See Zigbee specification r22.1.0, Table 3-58 (NIB attributes)
*/
uint8_t m_nwkCapabilityInformation;
/**
* This NIB attribute is a flag determining if this device is a concentrator
* (Use in Many-To-One routing).
* See Zigbee specification r22.1.0, Table 3-58 (NIB attributes)
*/
bool m_nwkIsConcentrator;
/**
* This NIB attribute indicates the hop count radius for concentrator
* route discoveries (Used by Many-To-One routing).
* See Zigbee specification r22.1.0, Table 3-58 (NIB attributes)
*/
uint8_t m_nwkConcentratorRadius;
/**
* The time in seconds between concentrator route discoveries.
* If set to 0x0000, the discoveries are done at the start up
* and by the next higher layer only.
* See Zigbee specification r22.1.0, Table 3-58 (NIB attributes)
*/
uint8_t m_nwkConcentratorDiscoveryTime;
/**
* This NIB attribute indicates whether the NWK layer should assume the ability to
* use hierarchical routing.
* True = Hierarchical routing False = Never use hierarchical routing
* See Zigbee specification r22.1.0, Table 3-58 (NIB attributes)
*/
bool m_nwkUseTreeRouting;
/**
* If false, the NWK layer shall calculate the link cost from all neighbor nodes
* using the LQI values reported by the MAC layer, otherwise it shall report a
* constant value (7).
* See Zigbe Specification r22.1.0, Table 3-58 (NIB attributes)
*/
bool m_nwkReportConstantCost;
/**
* Describes the current route symmetry:
* True: Routes are considered to be symmetric links. Backward and forward routes
* are created during one-route discovery and they are identical.
* False: Routes are not consider to be comprised of symmetric links. Only the forward
* route is stored during route discovery.
* See Zigbe Specification r22.1.0, Table 3-58 (NIB attributes)
*/
bool m_nwkSymLink;
/**
* The maximum number of retries allowed after a broadcast transmission failure
* See Zigbe Specification r22.1.0, Table 3-58 (NIB attributes)
*/
uint8_t m_nwkMaxBroadcastRetries;
/**
* The maximum time duration in milliseconds allowed for the parent all the child devices to
* retransmit a broadcast message.
* See Zigbe Specification r22.1.0, Table 3-58 (NIB attributes)
* See Zigbee-2007 Layer PICS and Stack Profiles
*/
Time m_nwkPassiveAckTimeout;
/**
* Time duration that a broadcast message needs to encompass the entire network.
* Its default value is calculated based on other NIB attributes.
* See Zigbe Specification r22.1.0, Table 3-58 (NIB attributes)
*/
Time m_nwkNetworkBroadcastDeliveryTime;
/**
* The sequence number used to identify outgoing frames
* See Zigbee specification r22.1.0, Table 3-58 (NIB attributes)
*/
SequenceNumber8 m_nwkSequenceNumber;
/**
* The counter used to identify route request commands
*/
SequenceNumber8 m_routeRequestId;
/**
* The handle assigned when doing a transmission request
* to the MAC layer
*/
SequenceNumber8 m_macHandle;
/**
* The expiration time of routing table entry.
* This value is not standardized and it is implementation dependent.
*/
Time m_routeExpiryTime;
};
} // namespace zigbee
} // namespace ns3
#endif /* ZIGBEE_NWK_H */
Reference in New Issue View Git Blame Copy Permalink