DeviceLocking

Before an agent can access a device in the TransactionalNetwork, it must request a lock on that device. This is handled by publishing a lock request. If there is no conflict, then the agent is granted the lock and a SUCCESS message is sent. When the agent is finished, it publishes a RELEASE message.

• Publish lock request for device
• Receive SUCCESS lock result
• Perform action
• Publish lock RELEASE message
• Receive RELEASE message

For example, the ExampleControllerAgent uses the lock to change a fan point:

Setup the rtu to control based on values from the agent's config file. The topics module has convenience classes for easily constructing topcs and requests based on an input dictionary.

    rtu_path = {
        'campus': get_config('campus'),
        'building': get_config('building'),
        'unit': get_config('unit'),
    }

Create a header that sets the requesterID as our agentID. The lock will be bound to the agentID. Then publish on the topic to acquire the lock using the topics helper.

    headers = {
        headers_mod.CONTENT_TYPE: headers_mod.CONTENT_TYPE.PLAIN_TEXT,
        'requesterID': agent_id
    }
    self.publish(topics.ACTUATOR_LOCK_ACQUIRE(**rtu_path), headers)

The subscription method listens on the lock result topic. It also filters these messages so we only receive our own. The json message will contain the results of our lock attempt. If it is a failure, the agent should wait and try again later (or wait until its time if a lock schedule is being used). On success it should perform its action.

        @matching.match_exact(topics.ACTUATOR_LOCK_RESULT(**rtu_path))
        @matching.match_headers({headers_mod.REQUESTER_ID: agent_id})
        def on_lock_result(self, topic, headers, message, match):
            '''Respond to lock result events.'''

            print "Topic: {topic}, {headers}, Message: {message}".format(
                    topic=topic, headers=headers, message=message)
            
            msg = jsonapi.loads(message[0])
            #If we got a success then set it at a random value
            if msg == 'SUCCESS':
                setting = random.randint(10, 90)
                headers[headers_mod.CONTENT_TYPE] = (
                        headers_mod.CONTENT_TYPE.PLAIN_TEXT)
                headers['requesterID'] = agent_id
               ''' self.publish(topics.ACTUATOR_SET(point=fan_point, **rtu_path),
                        headers, agent_id)'''
            elif msg == 'RELEASE':
                #Our lock release result was a success
                print "Let go of lock"
            elif msg == 'FAILURE':
                print "Failed to get lock"

The example agent sets a fan point value. This is the only action it needs to perform.

self.publish(topics.ACTUATOR_SET(point=fan_point, **rtu_path),
                        headers, agent_id)

The attempt to set the actuation point succeeded. This agent can then release the lock by publishing to the lock release topic.

        @matching.match_exact(topics.ACTUATOR_VALUE(point=fan_point, **rtu_path))
        @matching.match_headers({headers_mod.REQUESTER_ID: agent_id})
        def on_set_result(self, topic, headers, message, match):
            '''Result received, release the lock'''
            print "Topic: {topic}, {headers}, Message: {message}".format(
                    topic=topic, headers=headers, message=message)
            '''self.publish(topics.ACTUATOR_LOCK_RELEASE(**rtu_path),
                    headers, agent_id)'''