volttron.platform.vip package

VIP - VOLTTRON™ Interconnect Protocol implementation

See https://github.com/VOLTTRON/volttron/wiki/VIP for protocol specification.

This module is useful for using VIP outside of gevent. Please understand that ZeroMQ sockets are not thread-safe and care must be used when using across threads (or avoided all together). There is no locking around the state as there is with the gevent version in the green sub-module.

class volttron.platform.vip.Socket(context=None, socket_type=5, shadow=None)[source]

Bases: volttron.platform.vip.socket._Socket, zmq.sugar.socket.Socket

Submodules

volttron.platform.vip.externalrpcservice module

class volttron.platform.vip.externalrpcservice.ExternalRPCService(socket, routing_service, *args, **kwargs)[source]

Bases: object

Class to manage routing of RPC calls between external platforms and internal agents(peers).

handle_subsystem(frames)[source]
EXT_RPC subsystem handler on the server end.

:frames list of frames :type frames list

volttron.platform.vip.green module

VIP - VOLTTRON™ Interconnect Protocol implementation

See https://github.com/VOLTTRON/volttron/wiki/VIP for protocol specification.

This module is for use within gevent. It provides some locking around send operations to protect the VIP state. It should be safe to use a single socket in multiple greenlets without any kind of locking.

class volttron.platform.vip.green.BaseRouter(context=None, default_user_id=None)[source]

Bases: volttron.platform.vip.router.BaseRouter

class volttron.platform.vip.green.Socket(*args, **kwargs)[source]

Bases: volttron.platform.vip.socket._Socket, zmq.green.core._Socket

volttron.platform.vip.keydiscovery module

exception volttron.platform.vip.keydiscovery.DiscoveryError[source]

Bases: exceptions.StandardError

Raised when a different volttron central tries to register.

class volttron.platform.vip.keydiscovery.KeyDiscoveryAgent(address, serverkey, identity, external_address_config, setup_mode, bind_web_address, *args, **kwargs)[source]

Bases: volttron.platform.vip.agent.Agent

Class to get server key, instance name and vip address of external/remote platforms

startup(sender, **kwargs)[source]

Try to get platform discovery info of all the remote platforms. If unsuccessful, setup events to try again later :param sender: caller :param kwargs: optional arguments :return:

volttron.platform.vip.pubsubservice module

class volttron.platform.vip.pubsubservice.ProtectedPubSubTopics[source]

Bases: object

Simple class to contain protected pubsub topics

add(topic, capabilities)[source]
get(topic)[source]
class volttron.platform.vip.pubsubservice.PubSubService(socket, protected_topics, routing_service, *args, **kwargs)[source]

Bases: object

external_platform_add(instance_name)[source]
external_platform_drop(instance_name)[source]
handle_subsystem(frames, user_id)[source]
Handler for incoming pubsub frames. It checks operation frame and directs it for appropriate action handler.

:param frames list of frames :type frames list :param user_id user id of the publishing agent. This is required for protected topics check. :type user_id UTF-8 encoded User-Id property :returns: response frame to be sent back to the sender :rtype: list

Return Values:

response frame to be sent back to the sender

peer_add(peer)[source]
peer_drop(peer, **kwargs)[source]

Drop/Remove subscriptions related to the peer as it is no longer reachable/available. :param peer agent to be dropped :type peer str :param **kwargs optional arguments :type pointer to arguments

volttron.platform.vip.pubsubwrapper module

class volttron.platform.vip.pubsubwrapper.PubSubWrapper(identity, **kwargs)[source]

Bases: volttron.platform.vip.agent.Agent

PubSubWrapper Agent acts as a wrapper agent for PubSub subsystem when connected to remote platform that which is using old pubsub (RPC based implementation). When it receives PubSub requests from remote platform, - calls the appropriate method of new platform. - returns the result back

add_bus(name)[source]
onsetup(sender, **kwargs)[source]
volttron.platform.vip.pubsubwrapper.decode_peer(peer)[source]
volttron.platform.vip.pubsubwrapper.encode_peer(peer)[source]

volttron.platform.vip.router module

class volttron.platform.vip.router.BaseRouter(context=None, default_user_id=None)[source]

Bases: object

Abstract base class of VIP router implementation.

Router implementers should inherit this class and implement the setup() method to bind to appropriate addresses, set identities, setup authentication, etc, etc. The socket will be created by the start() method, which will then call the setup() method. Once started, the socket may be polled for incoming messages and those messages are handled/routed by calling the route() method. During routing, the issue() method, which may be implemented, will be called to allow for debugging and logging. Custom subsystems may be implemented in the handle_subsystem() method. The socket will be closed when the stop() method is called.

handle_subsystem(frames, user_id)[source]

Handle additional subsystems and provide a response.

This method does nothing by default and may be implemented by subclasses to provide additional subsystems.

frames is a list of zmq.Frame objects with the following elements:

[SENDER, RECIPIENT, PROTOCOL, USER_ID, MSG_ID, SUBSYSTEM, …]

The return value should be None, if the subsystem is unknown, an empty list or False (or other False value) if the message was handled but does not require/generate a response, or a list of containing the following elements:

[RECIPIENT, SENDER, PROTOCOL, USER_ID, MSG_ID, SUBSYSTEM, …]
issue(topic, frames, extra=None)[source]
lookup_user_id(sender, recipient, auth_token)[source]

Find and return a user identifier.

Returns the UTF-8 encoded User-Id property from the sender frame or None if the authenticator did not set the User-Id metadata. May be extended to perform additional lookups.

poll

Returns the underlying socket’s poll method.

poll_sockets()[source]

Called inside run method

Implement this method to poll for sockets for incoming messages.

route()[source]

Route one message and return.

One message is read from the socket and processed. If the recipient is the router (empty recipient), the standard hello and ping subsystems are handled. Other subsystems are sent to handle_subsystem() for processing. Messages destined for other entities are routed appropriately.

run()[source]

Main router loop.

setup()[source]

Called from start() method to setup the socket.

Implement this method to bind the socket, set identities and options, etc.

start()[source]

Create the socket and call setup().

The socket is save in the socket attribute. The setup() method is called at the end of the method to perform additional setup.

stop(linger=1)[source]

Close the socket.

volttron.platform.vip.routingservice module

class volttron.platform.vip.routingservice.RoutingService(socket, context, socket_class, poller, my_addr, instance_name, *args, **kwargs)[source]

Bases: object

This class maintains connection with external platforms.

close_external_connections()[source]

Close external platform socket connections :return:

disconnect_external_instances(instance_name)[source]

Close socket connections to remote platform :param instance_name: :return:

get_connected_platforms()[source]

Get list of connected instances :return:

get_name_for_identity(identity)[source]

Get instance name :param identity: platform identity :return:

handle_monitor_event(monitor_sock)[source]

Monitor external platform socket connections :param monitor_sock: socket to monitor :return:

handle_subsystem(frames)[source]
Handler for incoming routing table frames. It calls appropriate action handler based on operation request.

:param frames list of frames :type frames list :returns: response frame to be sent back to the sender :rtype: list

Return Values:

response frame to be sent back to the sender

my_instance_name()[source]

Name of my instance/platform. :return:

register(type, handler)[source]

Used by PubSubService to register for onconnect and ondisconnect handlers. :param type: on_connect/on_disconnect :param handler: handler function :return:

send_external(instance_name, frames)[source]

Send frames to external instance :param instance_name: name of remote instance :param frames: frames to send :return:

volttron.platform.vip.socket module

VIP - VOLTTRON™ Interconnect Protocol implementation

See https://github.com/VOLTTRON/volttron/wiki/VIP for protocol specification.

This file contains an abstract _Socket class which should be extended to provide missing features for different threading models. The standard Socket class is defined in __init__.py. A gevent-friendly version is defined in green.py.

class volttron.platform.vip.socket.Address(address, **defaults)[source]

Bases: object

Parse and hold a URL-style address.

The URL given by address may contain optional query string parameters and a URL fragment which, if given, will be interpreted as the socket identity for the given address.

Valid parameters:
server: Server authentication method; must be one of NULL,
PLAIN, or CURVE.

domain: ZAP domain for server authentication. serverkey: Encoded CURVE server public key. secretkey: Encoded CURVE secret key. publickey: Encoded CURVE public key. ipv6: Boolean value indicating use of IPv6. username: Username to use with PLAIN authentication. password: Password to use with PLAIN authentication.

bind(sock, bind_fn=None)[source]

Extended zmq.Socket.bind() to include options in the address.

connect(sock, connect_fn=None)[source]

Extended zmq.Socket.connect() to include options in the address.

qs
reset(sock)[source]
exception volttron.platform.vip.socket.ProtocolError[source]

Bases: exceptions.Exception

Error raised for invalid use of Socket object.

class volttron.platform.vip.socket.Message(**kwargs)[source]

Bases: object

Message object returned form Socket.recv_vip_object().

volttron.platform.vip.socket.nonblocking(*args, **kwds)[source]

volttron.platform.vip.tracking module

Utilities for tracking VIP message statistics at the router.

class volttron.platform.vip.tracking.Tracker[source]

Bases: object

Object for sharing data between the router and control objects.

disable()[source]

Disable tracking.

enable()[source]

Enable tracking.

hit(topic, frames, extra)[source]

Increment counters for given topic and frames.

reset()[source]

Reset all counters to default values and set start time.