Downlink Mechanisms

When a DownlinkMessage conductor needs a route to send the message to. Routes consists of the recipient end-node address, appended by the Gateway that the message will be sent to. The routes are saved in Conductor from the route that the class:.UplinkMessage takes when sending data to Conductor. These routes are persisted in conductor for some time and can be retrieved from both Module and DownlinkMessage objects

my_mod = account.get_module("$301$0-0-0-03000XXXX")
my_mod.get_routes()

dl_msg = my_mod.send_message(b'Hello World')
dl_msg.get_routes()

Which, in both cases, returns

[
    '$301$0-0-0-03000XXXX!101!$101$0-0-0-dbYYYYYYY',
    '$301$0-0-0-03000XXXX!101!$101$0-0-0-dbZZZZZZZ'
]

By default, Conductor will use all routes that the module has used in the recent past to send the message. This means that each gateway in that list will receive the DownlinkMessage. In cases where this is not the desired behavior, the gateway parameter can be used in the Module.send_message() method to use only one route

# Using the Gateay's Address
dl_msg = my_mod.send_message(b'Hello World', gateway="$101$0-0-0-dbYYYYYYY")

# Or a Gateway Object.
my_gw = account.get_gateway("$101$0-0-0-dbYYYYYYY")
dl_msg = my_mod.send_message(b'Hello World', gateway=my_gw)

# Which only uses this route: "$301$0-0-0-03000XXXX!101!$101$0-0-0-dbYYYYYYY"

When the DownlinkMessage is sent, you can check it’s status by getting the Downlink Events for that downlink: DownlinkMessage.get_events(). This returns an array of events, with their correlated timestamps, for each route utilized.

dl_msg = my_mod.send_message(b'Hello World')

dl_msg.get_events()
{
    '$301$0-0-0-03000XXXX!101!$101$0-0-0-dbYYYYYYY': [
        ('Issued', datetime.datetime(2016, 6, 9, 21, 45, 56, 585000)),
        ('Submitting', datetime.datetime(2016, 6, 9, 21, 45, 57, 158000)),
        ('Submitted', datetime.datetime(2016, 6, 9, 21, 45, 57, 349000)),
        ('Sending', datetime.datetime(2016, 6, 9, 21, 45, 57, 403000)),
        ('Sent', datetime.datetime(2016, 6, 9, 21, 45, 57, 945000)),
        ('Expired', datetime.datetime(2016, 6, 9, 21, 47, 36, 531000))
  ],
  '$301$0-0-0-03000XXXX!101!$101$0-0-0-dbZZZZZZZ': [
        ('Issued', datetime.datetime(2016, 6, 9, 21, 45, 56, 585000)),
        ('Expired', datetime.datetime(2016, 6, 9, 21, 47, 36, 531000))
  ]
}

The possible Conductor Events, and their significance are as follows…

Status Message	Description
Pending	Has not yet expired and has not yet met its acknowledgement requirements.
Expired	Has not met its acknowledgement requirements within the Time to Live expiration of the Command given its issuance time.
Failed	Has either not been able to be propagated to its intended targets or the intended targets have not accepted it.
AcknowledgedSuccessful	Has met its successful acknowledgement requirements.
Successful	Has met its acknowledgement requirements of any type.

The only way to be sure that a node received a DownlinkMessage, however, is to use the Acknowledgement Mechanism. This is enabled by default for standard Unicast messages (with one recipient). This can be explicitly set like this

dl_msg = mod.send_message(b'Hello World', acked=True)

This will then add the “AcknowledgedSuccessful” event to the Downlink Events.

Warning

The Acknowledgement Mechanism only works for Unicast Downlink Messages; Multicast Downlink Messages are not Acknowledged. See Application Tokens for more information regarding Multicast Downlink.

When a Downlink is sent, you can also wait for the message to be recieved using the blocking method DownlinkMessage.wait_for_success()

msg = module.send_message(b'hello')
msg.wait_for_success()