You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
327 lines
14 KiB
327 lines
14 KiB
/**
|
|
* @file zigbee.startup.h
|
|
* @brief Zigbee startup header file
|
|
* @author Exegin Technologies
|
|
* @copyright Copyright [2009 - 2020] Exegin Technologies Limited. All rights reserved.
|
|
*/
|
|
|
|
#ifndef ZIGBEE_STARTUP_H
|
|
# define ZIGBEE_STARTUP_H
|
|
|
|
#include "zcl/zcl.touchlink.h"
|
|
|
|
/** Startup control-codes as per the ZCL Spec, Commissioning Cluster's StartupControl
|
|
* attribute in the "Startup Parameters Attribute Set" */
|
|
enum ZbStartType {
|
|
ZbStartTypePreconfigured = 0x00, /**< (0x00) Preconfigured. No explicit form, join or rejoin to be performed. */
|
|
ZbStartTypeForm = 0x01, /**< (0x01) Form network */
|
|
ZbStartTypeRejoin = 0x02, /**< (0x02) Rejoin network */
|
|
ZbStartTypeJoin = 0x03, /**< (0x03) Join network */
|
|
/* Exegin add-ons (Internal use only) */
|
|
ZbStartTypeTouchlink = 0xfd, /**< [Internal stack use only] Touchlink */
|
|
ZbStartTypeFindBind = 0xfe, /**< [Internal stack use only] Finding & Binding */
|
|
ZbStartTypeNone = 0xff /**< [Internal stack use only] None */
|
|
};
|
|
|
|
/** CBKE configuration parameters for ZbStartup. This configuration is only
|
|
* applicable if the 'suite_mask' is non-zero. */
|
|
struct ZbStartupCbkeT {
|
|
uint8_t endpoint;
|
|
/**< Endpoint to assign ZCL Key Exchange cluster. Default is ZB_ENDPOINT_CBKE_DEFAULT (240) */
|
|
|
|
uint16_t deviceId;
|
|
/**< Device Id to assign to the endpoint created for the ZCL Key Exchange cluster.
|
|
* Default is ZCL_DEVICE_METER */
|
|
|
|
uint16_t suite_mask;
|
|
/**< The Key Exchange suite bitmask. E.g. ZCL_KEY_SUITE_CBKE2_ECMQV for CBKE version 2 (cbke_v2). */
|
|
|
|
struct ZbZclCbkeInfoT cbke_v1;
|
|
/**< CBKE version 1 certificate and security keys configuration.
|
|
* Only applicable if ZCL_KEY_SUITE_CBKE_ECMQV is set in suite_mask. */
|
|
|
|
struct ZbZclCbke2InfoT cbke_v2;
|
|
/**< CBKE version 2 certificate and security keys configuration.
|
|
* Only applicable if ZCL_KEY_SUITE_CBKE2_ECMQV is set in suite_mask. */
|
|
|
|
/* Keep Alive Server or Client */
|
|
bool tc_keepalive_server_enable;
|
|
/**< If CBKE is enabled (suite_mask != 0), this flag determines whether to allocate the
|
|
* Trust Center Keep Alive Server (true) or Client (false). */
|
|
|
|
/* Keep Alive Server attributes */
|
|
uint8_t tc_keepalive_base;
|
|
/**< Trust Center Keep Alive Server 'Base' attribute value in minutes.
|
|
* If zero, let the stack choose a default value. */
|
|
uint16_t tc_keepalive_jitter;
|
|
/**< Trust Center Keep Alive Server 'Jitter' attribute value in seconds.
|
|
* If zero, let the stack choose a default value. */
|
|
|
|
void (*tcso_callback)(enum ZbTcsoStatusT status, void *arg);
|
|
/**< Application callback that is called for any Trust Center Swap Out (TCSO) process
|
|
* initiated by the Keep Alive Client cluster. This includes when a TCSO has been started
|
|
* and the final outcome of a TCSO process. */
|
|
|
|
void *tcso_arg; /** Application callback argument for 'tcso_callback' */
|
|
};
|
|
|
|
/**
|
|
* The set of configuration parameters used to form or join a network using ZbStartup.
|
|
* Should be first initialized using ZbStartupConfigGetProDefaults or
|
|
* ZbStartupConfigGetProSeDefaults.
|
|
*/
|
|
struct ZbStartupT {
|
|
uint16_t shortAddress;
|
|
/**< Network short address. Only applicable if startupControl is
|
|
* ZbStartTypePreconfigured or ZbStartTypeRejoin */
|
|
|
|
uint16_t panId;
|
|
/**< Network PAN Id. Only applicable if startupControl is
|
|
* ZbStartTypePreconfigured or ZbStartTypeRejoin */
|
|
|
|
uint16_t networkManagerAddress;
|
|
/**< Network Manager Address. Only applicable if startupControl is
|
|
* ZbStartTypePreconfigured or ZbStartTypeRejoin */
|
|
|
|
uint64_t extendedPanId;
|
|
/**< Extended PAN Id.
|
|
*
|
|
* If startupControl is ZbStartTypeForm and extendedPanId is zero, then the device's
|
|
* extended address (EUI) will be used.
|
|
*
|
|
* If startupControl is ZbStartTypeRejoin a non-zero extendedPanId must be provided.
|
|
*
|
|
* If startupControl is ZbStartTypeJoin, the device will only attempt to join a
|
|
* network matching the extendedPanId. If extendedPanId is zero, then the device will
|
|
* attempt to join any available network, sorted by LQI.
|
|
*
|
|
* If startupControl is ZbStartTypePreconfigured a non-zero extendedPanId must be provided.
|
|
*/
|
|
|
|
struct ZbChannelListT channelList;
|
|
/**< Specify the channel mask(s) to use. If no channel masks are specified,
|
|
* ZB_BDB_PrimaryChannelSet and ZB_BDB_SecondaryChannelSet are used instead. */
|
|
|
|
uint8_t stackProfile;
|
|
/**< Network Stack Profile. If not ZB_NWK_STACK_PROFILE_PRO, application must
|
|
* configure the following NIB parameters before calling ZbStartup:
|
|
* nwkMaxDepth, nwkMaxChildren, nwkReportConstantCost, nwkLinkStatusPeriod,
|
|
* nwkTransactionPersistenceTime, nwkPassiveAckTimeout, nwkMaxBroadcastRetries,
|
|
* nwkSecureAllFrames, nwkSecurityLevel */
|
|
|
|
uint8_t bdbCommissioningMode;
|
|
/**< BDB Commissioning Mode mask. Set to 0 by default.
|
|
* If BDB_COMMISSION_MODE_TOUCHLINK is set, then Touchlink will be used.
|
|
* If BDB_COMMISSION_MODE_FIND_BIND is set, then Finding & Binding will be used after joining.
|
|
*/
|
|
|
|
enum ZbStartType startupControl;
|
|
/**< Startup Type. Not applicable if BDB_COMMISSION_MODE_TOUCHLINK commissioning mode is set.
|
|
*
|
|
* If startup type is ZbStartTypeJoin, the ZB_APS_IB_ID_SCAN_COUNT attribute is used to
|
|
* control the number of scans to perform while searching for a network to join. Similarily,
|
|
* the ZB_BDB_ScanDuration attribute is used to configure the MAC scan duration to use for
|
|
* scans during network joining and forming.
|
|
*/
|
|
|
|
struct {
|
|
uint8_t level; /**< Security Level. Default is 0x05. */
|
|
bool useInsecureRejoin; /**< Configures ZB_APS_IB_ID_USE_INSECURE_JOIN. */
|
|
uint64_t trustCenterAddress;
|
|
/**< Configures ZB_APS_IB_ID_TRUST_CENTER_ADDRESS. If forming the network and assuming the role of
|
|
* Trust Center, the device's extended address will be used instead, unless this parameter has
|
|
* been explicitly set to ZB_DISTRIBUTED_TC_ADDR. */
|
|
|
|
uint8_t preconfiguredLinkKey[ZB_SEC_KEYSIZE]; /**< Preconfigured Link Key */
|
|
uint8_t distributedGlobalKey[ZB_SEC_KEYSIZE]; /**< Preconfigured Distributed Global Link Key */
|
|
|
|
uint8_t networkKey[ZB_SEC_KEYSIZE];
|
|
/**< Configures the Network Key with key type set to ZB_SEC_KEYTYPE_STANDARD_NWK.
|
|
* Only applicable if startupControl is ZbStartTypePreconfigured. */
|
|
|
|
uint8_t networkKeySeqNum;
|
|
/**< Configures the Network Key Sequence Number for the Network Key.
|
|
* Also sets ZB_NWK_NIB_ID_ActiveKeySeqNumber to this value.
|
|
* Only applicable if startupControl is ZbStartTypePreconfigured.
|
|
*/
|
|
|
|
enum ZbSecKeyTypeT networkKeyType; /**< Deprecated and not used. */
|
|
|
|
struct ZbStartupCbkeT cbke; /**< CBKE certificate configuration */
|
|
} security;
|
|
|
|
struct {
|
|
uint16_t timeBetweenScans; /**< Deprecated and not used. */
|
|
uint16_t rejoinInterval; /**< Deprecated and not used. */
|
|
uint16_t maxRejoinInterval; /**< Deprecated and not used. */
|
|
} join;
|
|
|
|
uint8_t capability;
|
|
/**< Device capability mask. Default value includes:
|
|
* MCP_ASSOC_CAP_PWR_SRC (mains power),
|
|
* MCP_ASSOC_CAP_RXONIDLE (radio receiver is on, not sleepy),
|
|
* MCP_ASSOC_CAP_ALLOC_ADDR (parent allocates network address),
|
|
* MCP_ASSOC_CAP_DEV_TYPE (full function device) */
|
|
|
|
uint8_t endDeviceTimeout;
|
|
/**< End-device timeout is only used by end-devices. It configures the
|
|
* time used to periodically update the Parent device so this
|
|
* device is not removed from the Parent's NWK Neighbor Table.
|
|
* Configures ZB_NWK_NIB_ID_EndDeviceTimeoutDefault.
|
|
*
|
|
* Timeout = (60 * 2^n) seconds for n > 0. If n = 0, timeout = 10 seconds.
|
|
* Setting to ZB_NWK_CONST_ENDDEV_TIMEOUT_DISABLED (0xff) disables end-device timeout.*/
|
|
|
|
uint16_t fastPollPeriod; /**< Configures ZB_NWK_NIB_ID_FastPollPeriod. */
|
|
|
|
struct {
|
|
uint8_t tl_endpoint; /**< Endpoint for the Touchlink Cluster (e.g. ) */
|
|
uint8_t bind_endpoint; /**< Endpoint to use when binding clusters from Initiator to Target. */
|
|
uint16_t deviceId; /**< e.g. ZCL_DEVICE_ONOFF_SWITCH */
|
|
uint8_t zb_info; /**< e.g. ZCL_TL_ZBINFO_TYPE_ROUTER */
|
|
uint8_t flags; /**< e.g. ZCL_TL_FLAGS_IS_TARGET */
|
|
const void *persist_buf;
|
|
/**< Pointer to persistence data. Only applicable if ZCL_TL_ZBINFO_USE_PERSIST
|
|
* flag is set in zb_info. */
|
|
unsigned int persist_len; /**< Length of persistence data. */
|
|
struct ZbTouchlinkCallbacks callbacks;
|
|
/**< Callback functions for Touchlink Controller Device Utility commands. */
|
|
void *cb_arg; /**< Pointer to application data that will be used with Touchlink callbacks. */
|
|
} touchlink; /**< Touchlink configuration. Only applicable if BDB_COMMISSION_MODE_TOUCHLINK. */
|
|
};
|
|
|
|
/**
|
|
* Executes the startup procedure as described in section 2.5.5.5.6.2 of [R1].
|
|
*
|
|
* The startup code also handles callbacks from the stack to maintain the network
|
|
* and security processes. For example, these include the handling of
|
|
* APSME-UPDATE-DEVICE.indication messages when acting as a Coordinator Trust Center,
|
|
* to handle the authentication procedure described in section 4.6.3.2 of Zigbee R22.
|
|
*
|
|
* The message callback handlers can be overridden by the application by creating
|
|
* message filters using ZbMsgFilterRegister.
|
|
*
|
|
* This function and the entire startup code can be bypassed by the application, and
|
|
* the Network Layer APIs used directly, if so desired.
|
|
*
|
|
* @param zb Zigbee stack instance
|
|
* @param configPtr Pointer to ZbStartupT configuration structure.
|
|
* @param callback Application callback that is called with the final result
|
|
* of the startup procedure.
|
|
* @param arg Callback argument
|
|
* @return Zigbee Status Code whether the startup procedure has been started.
|
|
* If ZB_STATUS_SUCCESS, then the callback will be called with the final result.
|
|
*/
|
|
enum ZbStatusCodeT ZB_WARN_UNUSED ZbStartup(struct ZigBeeT *zb, struct ZbStartupT *configPtr,
|
|
void (*callback)(enum ZbStatusCodeT status, void *cb_arg), void *arg);
|
|
|
|
/**
|
|
* If Touchlink Target was started with ZbStartup, this API can be used to stop it.
|
|
* @param zb Zigbee stack instance
|
|
* @return Zigbee Status Code whether Touchlink was successfully stopped or not.
|
|
*/
|
|
enum ZbStatusCodeT ZbStartupTouchlinkTargetStop(struct ZigBeeT *zb);
|
|
|
|
/**
|
|
* Manually start Finding & Binding. F&B is also started automatically
|
|
* after joining the network.
|
|
* @param zb Zigbee stack instance
|
|
* @param callback Application callback to call after Finding & Binding complete
|
|
* @param arg Application callback argument
|
|
* @return Zigbee Status Code
|
|
*/
|
|
enum ZbStatusCodeT ZB_WARN_UNUSED ZbStartupFindBindStart(struct ZigBeeT *zb,
|
|
void (*callback)(enum ZbStatusCodeT status, void *arg), void *arg);
|
|
|
|
/**
|
|
* Same as ZbStartupFindBindStart, but only for a single endpoint.
|
|
* @param zb Zigbee stack instance
|
|
* @param endpoint Endpoint to perform Finding & Binding from.
|
|
* @param callback Application callback to call after Finding & Binding complete
|
|
* @param arg Application callback argument
|
|
* @return Zigbee Status Code
|
|
*/
|
|
enum ZbStatusCodeT ZB_WARN_UNUSED ZbStartupFindBindStartEndpoint(struct ZigBeeT *zb, uint8_t endpoint,
|
|
void (*callback)(enum ZbStatusCodeT status, void *arg), void *arg);
|
|
|
|
/**
|
|
* ZbStartupRejoin is a wrapper for ZbNlmeJoinReq(ZB_NWK_REJOIN_TYPE_NWKREJOIN).
|
|
* Use ZbStartupRejoin instead, because the internal startup handler will restart
|
|
* any timers we need to maintain our parent.
|
|
*
|
|
* Must already be connected to a network. If not on a network and want to
|
|
* rejoin as way to connect, use ZbStartup with ZbStartTypeRejoin.
|
|
* @param zb Zigbee stack instance
|
|
* @param callback Application callback to call after rejoin is complete,
|
|
* indicating success or failure.
|
|
* @param cbarg Application callback argument
|
|
* @return Zigbee Status Code
|
|
*/
|
|
enum ZbStatusCodeT ZB_WARN_UNUSED ZbStartupRejoin(struct ZigBeeT *zb,
|
|
void (*callback)(struct ZbNlmeJoinConfT *conf, void *arg), void *cbarg);
|
|
|
|
/**
|
|
* Trust Center Rejoin - unsecured rejoin (already joined to network, but
|
|
* missed a NWK key update).
|
|
* @param zb Zigbee stack instance
|
|
* @param callback Application callback to call after Trust Center rejoin is complete.
|
|
* If this function returns an error, then no callback will be generated.
|
|
* @param cbarg Application callback argument
|
|
* @return Zigbee Status Code
|
|
*/
|
|
enum ZbStatusCodeT ZB_WARN_UNUSED ZbTrustCenterRejoin(struct ZigBeeT *zb,
|
|
void (*callback)(enum ZbStatusCodeT status, void *arg), void *cbarg);
|
|
|
|
/**
|
|
* Try starting stack using persistence data provided.
|
|
* @param zb Zigbee stack instance
|
|
* @param pdata Pointer to persistent data
|
|
* @param plen Length of persistent data
|
|
* @param cbke_config Optional pointer to CBKE configuration data structure.
|
|
* @param callback Application callback to call after persistence is completed.
|
|
* If this function returns an error, then no callback will be generated.
|
|
* @param arg Application callback argument
|
|
* @return Zigbee Status Code
|
|
*/
|
|
enum ZbStatusCodeT ZbStartupPersist(struct ZigBeeT *zb, const void *pdata, unsigned int plen,
|
|
struct ZbStartupCbkeT *cbke_config,
|
|
void (*callback)(enum ZbStatusCodeT status, void *arg), void *arg);
|
|
|
|
/**
|
|
* Get the default configuration for a PRO network.
|
|
* @param configPtr Startup configuration to initialize
|
|
* @return None
|
|
*/
|
|
void ZbStartupConfigGetProDefaults(struct ZbStartupT *configPtr);
|
|
|
|
/**
|
|
* Same as ZbStartupConfigGetProDefaults, but clears the preconfigured
|
|
* global link keys.
|
|
* @param configPtr Startup configuration to initialize
|
|
* @return None
|
|
*/
|
|
void ZbStartupConfigGetProSeDefaults(struct ZbStartupT *configPtr);
|
|
|
|
/**
|
|
* The application can call ZbStartupTcsoStart if it thinks it as lost
|
|
* communication with the Trust Center. The Trust Center Swap Out process
|
|
* will be performed. The callback status is set to ZB_STATUS_SUCCESS if
|
|
* the stack is operational.
|
|
* @param zb Zigbee stack instance
|
|
* @param callback Application callback that is called after TCSO is complete.
|
|
* @param arg Application callback argument
|
|
* @return True if TCSO was started and to wait for callback to indicate
|
|
* completion. False if TCSO wasn't started.
|
|
*/
|
|
bool ZB_WARN_UNUSED ZbStartupTcsoStart(struct ZigBeeT *zb,
|
|
void (*callback)(enum ZbTcsoStatusT status, void *arg), void *arg);
|
|
|
|
/**
|
|
* Abort a TCSO, if it's running. This function should not be necessary,
|
|
* but an application may.
|
|
* @param zb Zigbee stack instance
|
|
* @return True if TCSO was aborted, false otherwise (i.e. wasn't running).
|
|
*/
|
|
bool ZbStartupTcsoAbort(struct ZigBeeT *zb);
|
|
|
|
#endif /* ZIGBEE_STARTUP_H */
|
|
|