Action Functions

Overview

  • Action functions (AF) are like skills. They are quite simply things that a device knows how to do.
  • Each device type has its own set of AFs, but all devices of the same type share the same AFs.
  • AFs intended to be executed at run time are stored in the Action Function Table (AFT) in each device individually.
  • Some AFs are common to all devices. We call these “Core Internal Action functions”.
  • There are two main groupings of AFs:
    • Internal AFs
      • These AFs are baked into the FW for any device and always have a linkId less than 256
    • External AFs
      • Thes AFs are programmed either directly by a user or commissioning agent, or created automatically by devices at run time using the push to pair (p2p) strategy

Example AFs:

  • Dimmers/Controllers:
    • Set Manual Duty(%,Fade)
      • This function goes to a particular level, over a given fade rate, and ignores input from any daylight harvest groups it may be associated with
    • Set Auto Duty(%,Fade)
      • Here we go to a level, over a given fade rate, then listen for DLH information
    • Enable Relay(0/1)
      • Will close or open the relay depending on the var1. 0 opens it, 1 closes it
    • Daylight Link
      • ‘Subscribes’ a controller to a given daylight sensor and converts the daylighting information it receives into a tangible level change (or lack there of).
  • Sensors:
    • Daylight Harvest
      • Causes a daylight capable sensor to call the applicable linkID when measured light levels change past a hysteresis value, and sends the current value out for any bound controller to interpret into a level change if needed
    • coap_send_action(linkID)
      • Tells the device to mulitcast a particular linkID. This can be used to ‘daisy chain’ events, or simply to schedule a particular action. This function is effectively the same one that is used anytime a Trigger Event occurs (i.e. motion)

Structure:

  • Each Action Function Row (AFR) has the following properties
    • lId
      • This is the 6Lo linkId that is used to reference this row
    • F
      • Is a flag that is not currently used by the system, but could be implemented to add more functionality to the existing structure
    • FM
      • Is a Flag mask that would work in harmony with the flag property if it were implemented to make AFRs more customizeable
    • Val
      • The variable that is passed to the action function. We often refer to it in code as `var1`
    • aFun
      • The memory reference for the action function being called. Amatis uses a cloud reference table that is built out by asking a device for its function_list before asking for its AFT to correlate these references with human readable names.

Example AF directly from a device:

{"lId":"0x3","F":"0xFFFF","FM":"0xFFFF","Val":"0x0","aFun":"0x1051F5"}

Note: The names of these properties as they are returned by the coap engine are intentionally not verbose. Although they still could be named better than they are, every char counts when transmiting ascii over the 15.4 network