Plugin Callbacks

Ember Application Framework API Reference > Application Framework Callback Interface

Ok To Sleep.

This function is called by the Idle/Sleep plugin before sleeping. It is called with interrupts disabled. The application should return true if the device may sleep or false otherwise.

Parameters

durationMs

The maximum duration in milliseconds that the device will sleep. Ver.: always

Gpd Commissioning.

This function is called by the Green Power Sink Plugin to notify the application of a Green Power Gp Notification of an incomming gpd command. Return true to handle in application.

Parameters

appInfo

Ver.: always

Gpd Commissioning.

This function is called by the Green Power Sink Plugin to notify the application of a Green Power Gp Notification without translation(endpoint is 0xFC).

Parameters

appInfo

Ver.: always

Ok To Sleep.

This function is called by the Idle/Sleep plugin before sleeping. It is called with interrupts disabled. The application should return true if the device may sleep or false otherwise.

Parameters

durationMs

The maximum duration in milliseconds that the device will sleep. Ver.: always

Ota Server Image Block Request.

This function is called when the server application receives an image block request by a client.

Parameters

data	A struct containing the details of the image block response and values that can be returned by the application to effect the behavior of the server's response.

Reset To Factory Defaults.

This function is called by the Basic server plugin when a request to reset to factory defaults is received. The plugin will reset attributes managed by the framework to their default values. The application should perform any other necessary reset-related operations in this callback, including resetting any externally-stored attributes.

Parameters

endpoint

Ver.: always

Data Ready.

This function is called whenever the battery monitor has generated a new valid battery level.

Parameters

batteryVoltageMilliV

The battery voltage, in milli Volts Ver.: always

This function is called from the BLE stack to notify the application of a stack event.

This function is called at init time. The following fields will be overwritten by the framework:

• max_connections
• heap
• heap_size

Finished.

This callback is fired when the bulb-ui plugin is finished with the forming or joining process. The result of the operation will be returned in the status parameter.

Parameters

status

Ver.: always

Called when Button 0 goes high.

This function is called when the GPIO tied to button zero goes high

Called when Button 0 goes low.

This function is called when the GPIO tied to button zero goes low

Called when Button 0 is pressed long.

Parameters

timePressedMs	Amount of time button 0 was pressed.
pressedAtReset	Was the button pressed at startup.

Called when Button 0 is pressed short.

Parameters

timePressedMs

Time (in ms) button 0 was pressed short

Called while Button 0 is pressed.

This function is periodically called when button 0 is being pressed.

Called when Button 1 goes high.

This function is called when the GPIO tied to button one goes high

Called when Button 1 goes low.

This function is called when the GPIO tied to button one goes low

Called when Button 1 is pressed long.

Parameters

timePressedMs	Amount of time button 1 was pressed.
pressedAtReset	Was the button pressed at startup.

Called when Button 1 is pressed short.

Parameters

timePressedMs

Time (in ms) button 1 was pressed short

Called while Button 1 is pressed.

This function is periodically called when button 1 is being pressed.

Button Event.

This allows another module to get notification when a button is pressed and released but the button joining plugin did not handle it. This callback is NOT called in ISR context so there are no restrictions on what code can execute.

Parameters

buttonNumber	The button number that was pressed. Ver.: always
buttonPressDurationMs	The length of time button was held down before it was released. Ver.: always

Publish Info.

This function is called by the calendar-server plugin after receiving any of the following commands and just before it starts publishing the response: GetCalendar, GetDayProfiles, GetSeasons, GetSpecialDays, and GetWeekProfiles.

Parameters

publishCommandId	ZCL command to be published Ver.: always
clientNodeId	Destination nodeId Ver.: always
clientEndpoint	Destination endpoint Ver.: always
totalCommands	Total number of publish commands to be sent Ver.: always

Is Color Supported.

This function will be called to determine whether a color is supported by a device. The color will be specified by hue and saturation.

Parameters

hue	Ver.: always
saturation	Ver.: always

Compute Pwm from HSV.

This function is called from the color server when it is time for the PWMs to be driven with a new value from the HSV values.

Parameters

endpoint

The identifying endpoint Ver.: always

Compute Pwm from HSV.

This function is called from the color server when it is time for the PWMs to be driven with a new value from the color temperature.

Parameters

endpoint

The identifying endpoint Ver.: always

Compute Pwm from HSV.

This function is called from the color server when it is time for the PWMs to be driven with a new value from the color X and color Y values.

Parameters

endpoint

The identifying endpoint Ver.: always

Changed.

Called when relays rules are added or removed.

Alert WAN.

Notify the application of an Alert that should be sent to the WAN. The second argument is a pointer to the gbz alert buffer. The application is responsible for freeing this buffer.

Parameters

alertCode	The 16 bit allert code as defined by GBCS Ver.: always
gbzAlert	Buffer continaing the GBZ formatted Alert Ver.: always
gbzAlertLength	The length in octets of the GBZ formatted Alert Ver.: always

Received.

This callback is called by the Comms Hub Function (CHF) plugin whenever a message is received.

Parameters

senderDeviceId	The EUI64 of the sending device Ver.: always
dataLen	The length in octets of the data Ver.: always
data	Buffer containing the raw octets of the data Ver.: always

Send.

This callback is called by the Comms Hub Function (CHF) plugin to report the status of a message that was previously sent.

Parameters

status	The status of the message that was sent Ver.: always
destinationDeviceId	The EUI64 of the destination device to which the data was sent Ver.: always
dataLen	The length in octets of the data that was sent Ver.: always
data	Buffer containing the raw octets of the data that was sent Ver.: always

Sub-GHz channel change request outcome callback.

This callback is called by the Comms Hub Function (Sub-GHz) plugin to report the outcome of the channel change request.

Parameters

outcome	Channel change request outcome
status	Ember status code if the outcome is negative

Tunnel Opened.

This function is called by the Comms Hub Function (CHF) plugin when a tunnel is opened.

Parameters

remoteDeviceId

The EUI64 of the remote device for which a tunnel is opened Ver.: always

Broadcast Sent.

This function is called when a new MTORR broadcast has been successfully sent by the concentrator plugin.

Finished.

This callback is fired when the bulb-ui plugin is finished with the forming or joining process. The result of the operation will be returned in the status parameter.

Parameters

status

Ver.: always

Network join finished.

This callback is fired when the Connection Manager plugin is finished with the network search process. The result of the operation will be returned as the status parameter.

Parameters

status

Ver.: always

Leave the currently joined network.

This function is called by the Connection Manager Plugin when the device is about to leave the network. It is normally used to trigger a UI event to notify the user of a network leave.

Begin searching for network to join.

This function is called by the Connection Manager Plugin when it starts to search for a new network. It is normally used to trigger a UI event to notify the user that the device is currently searching for a network.

Rollover.

This function is called every time a counter exceeds its threshold.

Parameters

type	The counter that rolled over Ver.: always

Discovery Complete.

This function is called when a device in the database has been set to EMBER_AF_DEVICE_DISCOVERY_STATUS_DONE.

Parameters

device

A pointer to the information struct about the device. Ver.: always

Enact Change Of Supplier.

This callback will be implemented by a meter to enact a change of supplier at the requested time of implementation.

Parameters

endpoint	Ver.: always
supplier	Ver.: always

Enact Change Of Tenancy.

This callback will be implemented by a meter to enact a change of tenancy at the requested time of implementation.

Parameters

endpoint	Ver.: always
tenancy	Ver.: always

Enact Change Supply.

This callback will be implemented by a meter to enact a supply change at the requested time of implementation.

Parameters

endpoint	Ver.: always
supply	Ver.: always

Enact Update Uncontrolled Flow Threshold.

This callback will be implemented by a meter to enact an update to the uncontrolled flow threshold as specified.

Parameters

endpoint	Ver.: always
supplier	Ver.: always

Set Supply Status.

This callback will be implemented by a meter to appropriately set the supply status.

Parameters

endpoint	Ver.: always
supplyStatus	Ver.: always

Get Password.

This callback will be implemented by an esi to provide device specific password information.

Parameters

senderNodeId	Ver.: always
passwordType	Ver.: always
passwordInfo	Ver.: always

Cleared.

This callback is called when a device table has been cleared.

StateChange.

This callback is called when a device's state changes.

Parameters

nodeId	Ver.: always
state	Ver.: always

StateChange.

This callback is called when a device's state changes.

Parameters

nodeId	Ver.: always
state	Ver.: always

StateChange.

This callback is called when a device's state changes.

Parameters

nodeId	Ver.: always
state	Ver.: always

StateChange.

This callback is called when a device's state changes.

Parameters

nodeId	Ver.: always
state	Ver.: always

NewDevice.

This callback is called when a new device joins the gateway.

Parameters

uui64

Ver.: always

Rejoin device.

Called when a device rejoins.

Parameters

newNodeEui64

EUI64 of the rejoined device.

StateChange.

This callback is called when a device's state changes.

Parameters

nodeId	Ver.: always
state	Ver.: always

Activate Door Lock.

This function is provided by the door lock server plugin. It is

Parameters

activate

True if the lock should move to the locked position, false if it should move to the unlocked position Ver.: always

Event Action.

This function is called by the demand response and load control client plugin whenever an event status changes within the DRLC event table. The list of possible event status values is defined by the ZCL spec and is listed in the Application Framework's generated enums located in enums.h. For example, an event status may be: AMI_EVENT_STATUS_LOAD_CONTROL_EVENT_COMMAND_RX indicating that a properly formatted event was received; AMI_EVENT_STATUS_EVENT_STARTED indicating that an event has started; AMI_EVENT_STATUS_THE_EVENT_HAS_BEEN_CANCELED, indicating that the event was canceled. This callback is intended to give the device an opportunity to take action on the event in question. For instance if an event starts, the device should take the appropriate event action on the hardware. This callback returns a bool, if returned value is true, then a notification will be send over the air automatically to the originator of the event. If it is false, then nothing will be sent back to the originator of the event. Please note that in order for your application to be ZigBee compliant, a notification must be sent over the air to the originator of the event, so a value of false should only be returned if your application code takes care of sending this message or there is some other reason a message does not need to be sent by the framework.

Parameters

loadControlEvent	Actual event Ver.: always
eventStatus	Status of event Ver.: always
sequenceNumber	Sequence number Ver.: always

Lost Parent Connectivity.

This function is called by the End Device Support plugin when the end device cannot connect to its parent. This callback is called under the following instances:

• When the network state of the device is EMBER_JOINED_NETWORK_NO_PARENT.
• If there are 3 or more data poll transaction failures for an end device.

If this callback returns false, the End Device Support plugin code will proceed with issuing a Trust Center rejoin. Otherwise, if this function returns true, the End Device Support plugin will not issue a Trust Center rejoin.

Poll Completed.

This function is called by the End Device Support plugin after a poll is completed.

Parameters

status

Return status of a completed poll operation Ver.: always

Pre Network Move.

This function is called by the End Device Support plugin just before it issues a Network Move, or a sequence of a secure rejoin followed by several trust center rejoins. Various plugins issue a Network Move when certain conditions are met, such as when the network state is EMBER_JOINED_NO_PARENT.

Users can consume this callback and return true to prevent the End Device Support plugin from issuing rejoin requests. Consuming the callback also gives the application a chance to implement its own rejoin logic. If this callback returns false, the End Device Support plugin will issue network rejoins as usual.

Log Data Updated.

This function is called by the Events server plugin when any modification to the plugin's event logs has been made. The argument will hint the ZCL command that might be used to triggered the data change. If null, it means the logging data have been updated through other means, e.g. CLI.

Parameters

cmd	ZCL command Ver.: always

Ok To Clear Log.

This function is called by the Events server plugin whenever a Clear Event Log Request command is received. The application should return true if it is Ok to clear the given log and false otherwise. If the request is to clear all logs (i.e. logId == EMBER_ZCL_EVENT_LOG_ID_ALL_LOGS) and the application allows all logs to be cleared then the application should return true. If the application does not allow all logs to be cleared it should return false in which case the plugin will subsequently call this callback for each event log allowing the application to selectively choose which event logs are Ok to be cleared.

Parameters

logId

The identifier of the log requested to be cleared. Ver.: always

Client Complete.

This function is called by the EZ-Mode Commissioning plugin when client commissioning completes.

Parameters

bindingIndex

The binding index that was created or EMBER_NULL_BINDING if an error occurred. Ver.: always

Bind Target.

This callback with enable the user to programmatically decide if they want to bind with a potential target. The plugin will try to bind with this target if and only if the function returns true. By default, the callback tells the plugin to try to bind with the target. If the binding type is changed to EMBER_MULTICAST_BINDING , a multicast binding will be created.

Parameters

nodeId	short ID of the potential target Ver.: always
bindingEntry	The binding entry for that target. Ver.: always
groupName	The name of the group if a multicast binding is created. Ver.: always

Complete.

This callback is fired by the initiator when the Find and Bind process is complete.

Parameters

status

Status code describing the completion of the find and bind process Ver.: always

Network Found.

This is called by the form-and-join library to notify the application of the network found after a call to ::emberScanForJoinableNetwork() or ::emberScanForNextJoinableNetwork(). See form-and-join documentation for more information.

Parameters

networkFound	Ver.: always
lqi	Ver.: always
rssi	Ver.: always

Unused Pan Id Found.

This function is called when the form-and-join library finds an unused PAN ID that can be used to form a new network on.

Parameters

panId	A randomly generated PAN ID without other devices on it. Ver.: always
channel	The channel where the PAN ID can be used to form a new network. Ver.: always

Alert WAN.

Notify the application of an Alert that should be sent to the WAN. The second argument is a pointer to the gbz alert buffer. The application is responsible for freeing this buffer.

Parameters

alertCode	The 16 bit allert code as defined by GBCS Ver.: always
gbzAlert	Buffer continaing the GBZ formatted Alert Ver.: always
gbzAlertLength	The length in octets of the GBZ formatted Alert Ver.: always

Data Log Access Request.

Query the application regarding the processing of the current GBCS specific command. Depending on the vendor specific information, such as the Tenancy attribute in the Device Management Cluster, the callback's return value determines whether the current command gets processed or not. With a return value of true, the plugin will process the message. Otherwise, the plugin will reject the message.

Parameters

gpfMessage	Ver.: always
zclClusterCommand	Ver.: always

Non Tap Off Message Handler Completed.

Notify the application that the Non Tap Off Message (Non-TOM) have been handled by the mirror endpoint. This callback is invoked when the the Non Tap Off Message have been processed. The first argument is a pointer to the gbz commands response buffer. The application is responsible for freeing this buffer.

Parameters

gbzCommandsResponse	Ver.: always
gbzCommandsResponseLength	Ver.: always

Tap Off Message Future Command Ignored.

Notify the application that an elemental ZCL command, embedded within the Tap Off Message (TOM), has been ignored by the GPF as it is a future dated command. The application can utilize the callback to store the discarded command for later retrieval. When the future dated command becomes active on the GSME, it will inform the CommsHub about the activation via an Alert message. The CommsHub should be able to correlate the matching messages and pass the previously stored ZCL commands to the TOM message handler for processing.

Parameters

gpfMessage	Ver.: always
zclClusterCommand	Ver.: always

Unknown Season Week Id.

This callback is called when the GPF receives a PublishSeasons command with an unknown week ID in one of the seasons. The callback contains a mask, unknownWeekIdSeasonsMask, with bits set corresponding to season entries that were not published because of an unknown week ID reference.

Parameters

issuerCalendarId	The calendar ID associated with these seasons. Ver.: always
seasonEntries	The season entries for this publish command. Ver.: always
seasonEntriesLength	The length of the season entries. Ver.: always
unknownWeekIdSeasonsMask	A mask where bit N indicates that the Nth season entry contains an unknown week ID reference. Ver.: always

Unknown Special Days Day Id.

This callback is called when the GPF receives a PublishSpecialDays command with an unknown day ID for one of the special days. The callback contains a mask, unknownDayIdMask, with bits set corresponding to special day entries that were not published because of an unknown day ID reference.

Parameters

issuerCalendarId	The calendar ID associated with these special days. Ver.: always
specialDayEntries	The special day entries for this publish command. Ver.: always
specialDayEntriesLength	The length of the special day entries. Ver.: always
unknownDayIdMask	A mask where bit N indicates that the Nth special day entry contains an unknown day ID reference. Ver.: always

Validate Incoming Zcl Command.

Query the application to check if a specific ZCL command should be processed given the UseCase # and ZCL command payload information. This function should capture the behavior detailed by the GBCS Use Case documentation. Please refer to EmberAfGpfZclCommandPermission enum for specific return data types.

Parameters

cmd	Ver.: always
messageCode	Ver.: always

Device Removed.

This callback is called by the plugin when a device is removed from the device log.

Parameters

deviceId

Identifier of the device removed Ver.: always

Decrypt Data.

This function is called by the Gbz Message Controller plugin to decrypt a ZCL payload. If the decryption is successful, the application is responsible for allocating the memory for the new decrypted data and passing the pointer via the "plainPayload" field as well as the plainPayloadLength field for the length. The framework will be responsible for free-ing the allocated memory. If the decryption fails, the callback return false and should not modify any data.

Parameters

data	Ver.: always

Encrypt Data.

This function is called by the Gbz Message Controller plugin to encrypt a ZCL payload. If the encryption is successful, the application is responsible for allocating the memory for the new encrypted data and passing the pointer via the "encryptedPayload" field as well as the encryptedPayloadLength field for the length. The framework will be responsible for free-ing the allocated memory. If the encryption fails, the callback return false and should not modify any data.

Parameters

data	Ver.: always

Called whenever the GPIO sensor detects a change in state.

Parameters

newSensorState

The new state of the sensor based alarm (EMBER_AF_PLUGIN_GPIO_SENSOR_ACTIVE or EMBER_AF_PLUGIN_GPIO_SENSOR_NOT_ACTIVE) Ver.: always

Gpd Commissioning.

This function is called by the Green Power Sink Plugin to notify the application of a Green Power Device that has requested commissioning with this sink. Return true to accept, false to reject.

Parameters

appInfo

Ver.: always

Gpd Commissioning.

This function is called by the Green Power Sink Plugin to notify the application of a Green Power Security Processing failed for a incomming. Return true to proceed with the process, false to drop the packet.

Parameters

appInfo

Ver.: always

Get Group Name.

This function returns the name of a group with the provided group ID, should it exist.

Parameters

endpoint	Endpoint Ver.: always
groupId	Group ID Ver.: always
groupName	Group Name Ver.: always

Group Names Supported.

This function returns whether or not group names are supported.

Parameters

endpoint

Endpoint Ver.: always

Set Group Name.

This function sets the name of a group with the provided group ID.

Parameters

endpoint	Endpoint Ver.: always
groupId	Group ID Ver.: always
groupName	Group Name Ver.: always

Start Feedback.

This function is called by the Identify plugin when identification begins. It informs the Identify Feedback plugin that it should begin providing its implemented feedback functionality (e.g. LED blinking, buzzer sounding, etc.) until the Identify plugin tells it to stop. The identify time is purely a matter of informational convenience; this plugin does not need to know how long it will identify (the Identify plugin will perform the necessary timekeeping.)

Parameters

endpoint	The identifying endpoint Ver.: always
identifyTime	The identify time Ver.: always

Stop Feedback.

This function is called by the Identify plugin when identification is finished. It tells the Identify Feedback plugin to stop providing its implemented feedback functionality.

Parameters

endpoint

The identifying endpoint Ver.: always

Active.

This function is called by the Idle/Sleep plugin after idling.

Ok To Idle.

This function is called by the Idle/Sleep plugin before idling. It is called with interrupts disabled. The application should return true if the device may idle or false otherwise.

Ok To Sleep.

This function is called by the Idle/Sleep plugin before sleeping. It is called with interrupts disabled. The application should return true if the device may sleep or false otherwise.

Parameters

durationMs

The maximum duration in milliseconds that the device will sleep. Ver.: always

RTOS idle/sleep.

This function is called by the Idle/Sleep plugin before idling or sleeping. If it returns true, the RTOS is handling the MCU idling/sleeping, if it returns false the idle/sleep shall manage the actual MCU idling/sleeping.

Parameters

durationMs	A pointer to the allowed idle/sleep duration in milliseconds. Ver.: always
sleepOk	A boolean indicating whether sleep is allowed.

Wake Up.

This function is called by the Idle/Sleep plugin after sleeping.

Parameters

durationMs

The duration in milliseconds that the device slept. Ver.: always

Fragment Transmission Failed.

This function is called by the Interpan plugin when a fragmented transmission has failed.

Parameters

interpanFragmentationStatus	The status describing why transmission failed Ver.: always
fragmentNum	The fragment number that encountered the failure Ver.: always

Message Received Over Fragments.

This function is called by the Interpan plugin when a fully reconstructed message has been received over inter-PAN fragments, or IPMFs.

Parameters

header	The inter-PAN header Ver.: always
msgLen	The message payload length Ver.: always
message	The message payload Ver.: always

Pre Message Received.

This function is called by the Interpan plugin when an interpan message is received but has not yet been handled by the plugin or the framework. The application should return true if the message was handled.

Parameters

header	The inter-PAN header Ver.: always
msgLen	The message payload length Ver.: always
message	The message payload Ver.: always

Level Control Cluster Server Post Init.

Following resolution of the Current Level at startup for this endpoint, perform any additional initialization needed; e.g., synchronize hardware state.

Parameters

endpoint

Endpoint that is being initialized Ver.: always

Level Control Coupled Color Temp Change.

Adjust Color Control cluster Color Temperature in response to a change in Level Control cluster CurrentLevel.

Parameters

endpoint

Endpoint that is being initialized Ver.: always

Ok To Shutdown.

This function is called by the Low Voltage Shutdown plugin after the low voltage threshold has been detected but before shutting down the chip (until a full power-on reset is triggered). The application should return true if the device may shutdown or false otherwise. Note that this callback is not the proper place to put logic to be performed just prior to shutdown; that would be the Pre Shutdown Callback. If callback returns false, shutdown check will be performed again in EMBER_AF_PLUGIN_LOW_VOLTAGE_SHUTDOWN_POSTPONE_DURATION_MS milliseconds.

Parameters

shutdownVoltage

The voltage (in mV) read from VDD at shutdown time, which can be used to determine the risk in doing any further activities prior to shutdown. Ver.: always

Pre Shutdown.

This function is called by the Low Voltage Shutdown plugin just prior to shutting down, allowing the application to do any last-minute clean-up before the chip goes offline until next reset. (Can't prevent shutdown from this context; use Ok To Shutdown callback for that instead.)

Parameters

shutdownVoltage

The voltage (in mV) read from VDD at shutdown time, which can be used to determine the risk in doing any further activities prior to shutdown. Ver.: always

Cancel Message.

This function is called by the Messaging client plugin whenever the application should stop displaying a message.

Parameters

message

The message that should no longer be displayed. Ver.: always

Display Message.

This function is called by the Messaging client plugin whenever the application should display a message.

Parameters

message

The message that should be displayed. Ver.: always

Pre Display Message.

This function is called by the Messaging client plugin when a DisplayMessage command is received. If callback returns true, the plugin assumes the message have been handled and will not do anything with the message. Otherwise, the plugin will go through with its own implementation.

Parameters

messageId	Ver.: always
messageControl	Ver.: always
startTime	Ver.: always
durationInMinutes	Ver.: always
message	Ver.: always
optionalExtendedMessageControl	Ver.: always

Server Process Notification.

This function is called by the metering server plugin when any of the Notification Attribute Set attributes are read or reported by the metering client.

Parameters

attributeId	ID of the attribute being proccessed Ver.: always
attributeValue	value of the attribute being proccessed Ver.: always

Mirror Added.

This function is called by the Meter Mirror plugin whenever a RequestMirror command is successfully processed.

Parameters

requestingDeviceIeeeAddress	Ver.: always
endpoint	Ver.: always

Mirror Removed.

This function is called by the Meter Mirror plugin whenever a RemoveMirror command is successfully processed.

Parameters

requestingDeviceIeeeAddress	Ver.: always
endpoint	Ver.: always

Reporting Complete.

This function is called by the Meter Mirror plugin after processing an AttributeReportingStatus attribute set to ReportingComplete. If the application needs to do any post attribute reporting processing it can do it from within this callback.

Parameters

endpoint

Ver.: always

Get Snapshot.

This function is called by the Meter Snapshot server plugin whenever a GetSnapshot command is received. A plugin implementing backhaul functionality for the snapshot mechanism should proceed to retrieve the snapshot and send a PublishSnapshot command to the requesting client.

Parameters

srcEndpoint	Ver.: always
dstEndpoint	Ver.: always
dest	Ver.: always
snapshotCriteria	Ver.: always

Schedule Snapshot.

This function is called by the Meter Snapshot server plugin whenever a ScheduleSnapshot command is received. A plugin implementing backhaul functionality for the snapshot mechanism should proceed to schedule the snapshot as required.

Parameters

srcEndpoint	Ver.: always
dstEndpoint	Ver.: always
dest	Ver.: always
snapshotPayload	Ver.: always
responsePayload	Ver.: always

Take Snapshot.

This function is called by the Meter Snapshot server plugin whenever a TakeSnapshot command is received. A plugin implementing backhaul functionality for the snapshot mechanism should proceed to manually take a snapshot as required. If for some reason the snapshot could not be taken, this should be reflected in the snapshotConfirmation argument.

Parameters

endpoint	Ver.: always
snapshotCause	Ver.: always
snapshotConfirmation	Ver.: always

This function is called from the Micrium RTOS plugin before the Application (1) task is created.

This function implements the Application (1) task main loop.

Parameters

p_arg

Ver.: always

This function is called from the Micrium RTOS plugin before the Application (2) task is created.

This function implements the Application (2) task main loop.

Parameters

p_arg

Ver.: always

This function is called from the Micrium RTOS plugin before the Application (3) task is created.

This function implements the Application (3) task main loop.

Parameters

p_arg

Ver.: always

Complete.

This callback notifies the user that the network creation process has completed successfully.

Parameters

network	The network that the network creator plugin successfully formed. Ver.: always
usedSecondaryChannels	Whether or not the network creator wants to form a network on the secondary channels Ver.: always

Get Pan Id.

This callback is called when the Network Creator plugin needs the PAN ID for the network it is about to create. By default, the callback will return a random 16-bit value.

Get Power For Radio Channel.

This callback is called when the Network Creator plugin needs the radio power for the network it is about to create. By default, the callback will use the radio power specified in the relevant plugin option.

Finished.

This callback is fired when the network-find plugin is finished with the forming or joining process. The result of the operation will be returned in the status parameter.

Parameters

status

Ver.: always

Get Enable Scanning All Channels.

Returns true is the fallback on scanning all channels is enabled, false if not.

Get Energy Threshold For Channel.

This callback is called during the energy scan when forming the network. Should the energy level exceed the value returned by this callback, the current channel will not be considered a suitable candidate for forming. Should none of the channels in the channel mask be considered suitable, the scan will fall back on all channels, including those not on the channel mask. The return value is RSSI, in dBm. This callback is called only when the fallback functionality is enabled.

Parameters

pgChan

Ver.: always

Get Radio Power For Channel.

This callback is called by the framework when it is setting the radio power during the discovery process. The framework will set the radio power depending on what is returned by this callback.

Parameters

pgChan

Ver.: always

Join.

This callback is called by the plugin when a joinable network has been found. If the application returns true, the plugin will attempt to join the network. Otherwise, the plugin will ignore the network and continue searching. Applications can use this callback to implement a network blacklist.

Parameters

networkFound	Ver.: always
lqi	Ver.: always
rssi	Ver.: always

Complete.

This callback is fired when the Network Steering plugin is complete.

Parameters

status	On success this will be set to EMBER_SUCCESS to indicate a network was joined successfully. On failure this will be the status code of the last join or scan attempt. Ver.: always
totalBeacons	The total number of 802.15.4 beacons that were heard, including beacons from different devices with the same PAN ID. Ver.: always
joinAttempts	The number of join attempts that were made to get onto an open Zigbee network. Ver.: always
finalState	The finishing state of the network steering process. From this, one is able to tell on which channel mask and with which key the process was complete. Ver.: always

Get Distributed Key.

This callback is fired when the Network Steering plugin needs to set the distributed key. The application set the distributed key from Zigbee Alliance thru this callback or the network steering will use the default test key.

Parameters

pointer

to the distributed key struct

Returns

true if the key is loaded successfully, otherwise false. level. Ver.: always

Get Node Type.

This callback allows the application to set the node type that the network steering process will use in joining a network.

Parameters

state

The current ::EmberAfPluginNetworkSteeringJoiningState.

Returns

An EmberNodeType value that the network steering process will try to join a network as.

Get Power For Radio Channel.

This callback is fired when the Network Steering plugin needs to set the power level. The application has the ability to change the max power level used for this particular channel.

Parameters

channel

The channel that the plugin is inquiring about the power level. Ver.: always

Occupancy state changed.

This callback is generated when the occupancy measurement server receives a new occupancy status.

Parameters

occupancyState

The bitmap used to determine occupancy state. At present, only bit 0 is used, and will be set to either HAL_OCCUPANCY_STATE_OCCUPIED or HAL_OCCUPANCY_STATE_UNOCCUPIED. Ver.: always

On/off Cluster Server Post Init.

Following resolution of the On/Off state at startup for this endpoint, perform any additional initialization needed; e.g., synchronize hardware state.

Parameters

endpoint

Endpoint that is being initialized Ver.: always

Pre-Bootload Callback.

Called shortly before installing the downloaded image.

Parameters

srcEndpoint	Ver.: always
serverEndpoint	Ver.: always
serverNodeId	Ver.: always

OTA Server Block Sent Callback.

This function will be called when a block is sent to a device.

Parameters

actualLength	Ver.: always
manufacturerId	Ver.: always
imageTypeId	Ver.: always
firmwareVersion	Ver.: always

GetClientDelayUnits.

Called when the server receives an Image Block Request from a client that supports rate limiting using the Minimum Block Period feature. This callback gives the server a chance to decide which units the client uses for the Minimum Block Period, seconds or milliseconds. The server can also return OTA_SERVER_DISCOVER_CLIENT_DELAY_UNITS, which causes the plugin code to test the client by sending it a preset delay value. The length of time the client delays determines which units it uses. For more information on this feature, please read the plugin option descriptions under the OTA Server plugin.

Parameters

clientNodeId	Ver.: always
clientEui64	Ver.: always

For return values, see ota-server-policy.h. An unknown return value will result in the same behavior as if OTA_SERVER_CLIENT_USES_MILLISECONDS had been returned.

OTA Server Update Complete Callback.

This function will be called when an OTA update has finished.

Parameters

manufacturerId	ManufacturerId.
imageTypeId	Image Type Id.
firmwareVersion	Firmware Version.
source	Source node id.
status	Status of update.

UpdateStarted.

Called when an OTA upgrade starts.

Parameters

manufacturerId	Ver.: always
imageTypeId	Ver.: always
firmwareVersion	Ver.: always
maxDataSize	Ver.: always
offset	Ver.: always

Erase Complete.

This is called when an EEPROM erase operation has completed.

Parameters

success

The result of the erase operation. Ver.: always

CheckInTimeout.

This function is called by the Poll Control Server plugin after a threshold value of poll control check in messages are sent to a trust center and no responses are received. The existence of this callback provides an opportunity for the application to implement its own rejoin algorithm or logic.

Consumer Top Up.

This function is called when a Consumer Top Up command is received. This callback must evaluate the command data and determine if it is a valid Top Up command.

Parameters

originatingDevice	Ver.: always
topUpCode	Ver.: always

Pending Cpp Event.

This function is called by the Price client plugin when a CPP event is received with pending status.

Parameters

cppAuth

The CPP Auth status. Ver.: always

Price Expired.

This function is called by the Price client plugin whenever a price expires.

Parameters

price

The price that has expired. Ver.: always

Price Started.

This function is called by the Price client plugin whenever a price starts.

Parameters

price

The price that has started. Ver.: always

New Active Block Period Information.

This callback is used to notify the application that a new Block Period Information has become active. The application is responsible for updating proper ZCL attributes to reflect the necessary vendor specific behaviors. Argument, priceCommonInfo, would contain common informations such as startTime and etc. Argument, priceBlockPeriod, would contain the BlockPeriod information itself.

Parameters

priceCommonInfo	Ver.: always
priceBlockPeriods	Ver.: always

New Active Block Thresholds Information.

This callback is used to notify the application that a new Block Thresholds Information has become active. The application is responsible for updating proper ZCL attributes to reflect the necessary vendor specific behaviors. Argument, priceCommonInfo, would contain common informations such as startTime and etc. Argument, priceTariffInfo, would contain the BlockThresholds information itself.

Parameters

priceCommonInfo	Ver.: always
priceBlockThresholds	Ver.: always

New Active Price Matrix.

This callback is used to notify the application that a new PriceMatrix has become active. The application is responsible for updating proper ZCL attributes to reflect the necessary vendor specific behaviors. Argument, priceCommonInfo, would contain common informations such as startTime and etc. Argument, priceMatrix, would contain the PriceMatrix information itself.

Parameters

priceCommonInfo	Ver.: always
priceMatrix	Ver.: always

New Active Tariff Information.

This callback is used to notify the application that a new Tariff Information has become active. The application is responsible for updating proper ZCL attributes to reflect the necessary vendor specific behaviors. Argument, priceCommonInfo, would contain common informations such as startTime and etc. Argument, priceTariffInfo, would contain the PriceMatrix information itself.

Parameters

priceCommonInfo	Ver.: always
priceTariffInfo	Ver.: always

Configured.

This callback is called by the Reporting plugin whenever a reporting entry is configured, including when entries are deleted or updated. The application can use this callback for scheduling readings or measurements based on the minimum and maximum reporting interval for the entry. The application should return EMBER_ZCL_STATUS_SUCCESS if it can support the configuration or an error status otherwise. Note: attribute reporting is required for many clusters and attributes, so rejecting a reporting configuration may violate ZigBee specifications.

Parameters

entry

Ver.: always

Configured.

This callback is called by the Reporting plugin to get the default reporting configuration values from user if there is no default value available within af generated default reporting configuration tabel. The application need to write to the minInterval, maxInterval and reportable change in the passed IO pointer in the arguement while handleing this callback, then application shall return true if it has provided the default values or else false for reporting plugin to further handleing.

Parameters

entry

Ver.: always

Called whenever the SB1 receives a gesture.

Parameters

gestureReceived	The (enumerated) gesture received.
switchNumber	The switch that received the gesture.

Security sensor state changed.

This callback is generated when the status of security sensor is changed

Parameters

newStatus,16

bit new status

bit0: 1 - opened or alarmed, 0 - closed or not alarmed bit2: 1 - tampered, 0 - not tampered other bits: reserved.

Ver.: always

Remove Mirror.

This function is called by the Simple Metering client plugin whenever a Remove Mirror command is received. The application should return the endpoint on which the mirror has been removed. If the mirror could not be removed, the application should return 0xFFFF.

Parameters

requestingDeviceIeeeAddress

Ver.: always

Request Mirror.

This function is called by the Simple Metering client plugin whenever a Request Mirror command is received. The application should return the endpoint to which the mirror has been assigned. If no mirror could be assigned, the application should return 0xFFFF.

Parameters

requestingDeviceIeeeAddress

Ver.: always

Process Notification Flags.

This function is called by the metering server plugin when any of the Notification Attribute Set attributes are read or reported by the metering client.

Parameters

attributeId	Ver.: always
attributeValue	Ver.: always

Message Timed Out.

This function is called by the sleepy message queue when a message times out. The plugin will invalidate the entry in the queue after giving the application a chance to perform any actions on the timed-out message.

Parameters

sleepyMsgId

Ver.: always

Allow Bootload Launch.

This function is a callback when the client is being told to launch the standalone bootloader. This is done after authentication has completed successfully.

Parameters

sourceEui64

The EUI64 of the node requesting the bootload. Ver.: always

Allow Incoming Message.

Allows the application to control whether the plugin can respond to incoming bootload messages.

Parameters

sourceEui64	The EUI64 of the sending node. Ver.: always
command	The incoming command ID Ver.: always

Incoming Message.

Indicates an Ember Bootload message has been received by the Standalone Bootloader Common plugin.

Parameters

longId	The sender's EUI64 address Ver.: always
length	The length of the incoming message. Ver.: always
message	The array of bytes for the message. Ver.: always

Finished.

Notifies the application when the standalone bootload has completed, successfully or otherwise.

Parameters

success

Boolean indicating the success or failure of the bootload. Ver.: always

Query Response.

Allows the application to control whether the plugin can respond to incoming bootload messages.

Parameters

queryWasBroadcast	Boolean indicating whether the query was broadcast or unicast Ver.: always
queryData	A data structure providing the details about the local device's bootloader. Ver.: always

Duty cycle state change callback for the use with the Sub-GHz plugin.

The Sub-GHz plugin monitors the duty cycle and calls this callback every time the duty cycle state changes.

Parameters

channel	the channel that registered a Duty Cycle state change
curMode	current Duty Cycle mode
oldState	the previous Duty Cycle state
newState	the current Duty Cycle state

Returns

true to handle in the application, false for default behaviour

The default response is sending the 'Suspend ZCL Messages' command, either by unicast to the most offending client of a broadcast to all clients, depending on the old and new duty cycle state.

Sub-GHz Cluster Get Suspend ZCL Messages Status.

'Get Suspend ZCL Messages Status' is a client command. The client can send it to the server to query the status instead of waiting for the 'Suspend ZCL Messages' command.

The server's default action is sending the 'Suspend ZCL Messages' command with the parameter indicating the remaining suspend time in minutes.

Returns

true to indicate the callback has been handled by the application, false to keep the default behaviour

Sub-GHz Cluster Suspend ZCL Messages.

'Suspend ZCL Messages' is a server command, sent to request the client to temporarily suspend sending any ZCL messages to reduce the duty cycle.

The clients's default action is to suspend ZCL messages for the requested period.

Parameters

period

suspend period in minutes

Returns

true to indicate the callback has been handled by the application, false to keep the default behaviour

Callback to let the application handle the incoming Mgmt_NWK_Unsolicited_Enhanced_Update_notify command.

'Mgmt_NWK_Unsolicited_Enhanced_Update_notify' is a client command. The client sends it to notify the server about the poor link quality. The server should determine whether a channel change is necessary and change the channel if so. There is no default action performed by the application framework. If not handled by the application, no action is taken.

Parameters

channelPage	........ current channel page
channel	............ current channel
macTxUcastTotal	.... total number of Mac Tx transaction attempts
macTxUcastFailures	. total number of Mac Tx transaction failures
macTxUcastRetries	.. total number of Mac Tx transaction retries
period	............. time in minutes over which macTxUcastXxx were measured

Tamper is active.

This function is called whenever the tamper switch detects that it has entered the enclosure, thereby activating tamper monitoring.

Tamper alarm.

This function is called when the plugin detects that the enclosure has been opened.

Over temperature state changed.

This callback is generated when the temperature rises over the assert thresholds (warning and critical) or drops below the deassert thresholds (warning and critical)

Parameters

previousState,the	state prior to the state change
newState,the	new state of the state change

EMBER_TEMPERATURE_MEASUREMENT_SERVER_OVER_TEMPERATURE_NORMAL : normal state EMBER_TEMPERATURE_MEASUREMENT_SERVER_OVER_TEMPERATURE_WARNING : warning state EMBER_TEMPERATURE_MEASUREMENT_SERVER_OVER_TEMPERATURE_CRITICAL : critical state

Ver.: always

MQTT message arrived.

This function is called when the MQTT client for the gateway receives an incoming message on a topic. If the message is processed by the application, return true. If the message is not processed, return false. This function is called on a separate thread, so no stack calls should be made within the implementation of this function. Instead, use a global variable in that function to communicate the message arrival to a stack event or timer running from the main loop.

Parameters

topic	A string containing the topic for the message that arrived. While the underlying MQTT libraries allow NULL characters in a topic, NULL characters are not supported in this implementation so the topic parameter can be assumed to be NULL terminated.
payload	A string containing the payload for the message that arrived.

MQTT client state is changed.

This function is called when the state of the MQTT client changes.

Parameters

state

Contains the new and current EmberAfPluginTransportMqttState state.

ConnectivityRestored This function is called by the Trust Center Keepalive plugin when a read attribute response command from the trust center is received after trust center connectivity had previously been lost.

Timeout.

This function is called by the Trust Center Keepalive plugin when the Trust Center fails to acknowledge enough keepalive messages. Upon timing out, the Trust Center Keepalive plugin code will initiate a search for a new Trust Center, which falls in line with the Trust Center Swapout feature. Applications may consume this callback and have it return true in order to prevent the Trust Center Keepalive plugin code from issuing a Trust Center (insecure) rejoin. Doing so will also give the application a chance to implement its own rejoin algorithm or logic. If this callback returns false, the Trust Center Keepalive plugin code will proceed with issuing a Trust Center rejoin.

Data Error.

This function is called by the Tunneling client plugin whenever a data error occurs on a tunnel. Errors occur if a device attempts to send data on tunnel that is no longer active or if the tunneling does not belong to the device.

Parameters

tunnelIndex	The index of the tunnel on which this data error occurred. Ver.: always
transferDataStatus	The error that occurred. Ver.: always

Data Received.

This function is called by the Tunneling client plugin whenever data is received from a server through a tunnel.

Parameters

tunnelIndex	The index of the tunnel through which the data was received. Ver.: always
data	Buffer containing the raw octets of the data. Ver.: always
dataLen	The length in octets of the data. Ver.: always

Transfer Data Failure.

This function is called when a TransferData command fails to be sent to the intended destination.

Parameters

indexOfDestination	The index or destination address of the TransferData command. Ver.: always
apsFrame	The EmberApsFrame of the command. Ver.: always
msgLen	The length of the payload sent in the command. Ver.: always
message	The payload that was sent in the command. Ver.: always
status	The non-success status code from the transmission of the command. Ver.: always

Tunnel Closed.

This function is called by the Tunneling client plugin whenever a server sends a notification that it preemptively closed an inactive tunnel. Servers are not required to notify clients of tunnel closures, so applications cannot rely on this callback being called for all tunnels.

Parameters

tunnelIndex

The index of the tunnel that has been closed. Ver.: always

Tunnel Opened.

This function is called by the Tunneling client plugin whenever a tunnel is opened. Clients may open tunnels by sending a Request Tunnel command.

Parameters

tunnelIndex	The index of the tunnel that has been opened. Ver.: always
tunnelStatus	The status of the request. Ver.: always
maximumIncomingTransferSize	The maximum incoming transfer size of the server. Ver.: always

Data Error.

This function is called by the Tunneling server plugin whenever a data error occurs on a tunnel. Errors occur if a device attempts to send data on tunnel that is no longer active or if the tunneling does not belong to the device.

Parameters

tunnelIndex	The identifier of the tunnel on which this data error occurred. Ver.: always
transferDataStatus	The error that occurred. Ver.: always

Data Received.

This function is called by the Tunneling server plugin whenever data is received from a client through a tunnel.

Parameters

tunnelIndex	The identifier of the tunnel through which the data was received. Ver.: always
data	Buffer containing the raw octets of the data. Ver.: always
dataLen	The length in octets of the data. Ver.: always