VOLTTRON™ documentation!<a class="headerlink" href="#volttron-documentation" title="Permalink to this headline">¶

Creating a Task requires four things:

The requester of the Task. This is the Agent’s ID.
A name for the Task.
The Task’s priority.
A list of devices and time ranges for each device.

Task Priority¶

There are three valid prioirity levels:

“HIGH”
This Task cannot be preempted under any circumstance. This Task may preempt other conflicting preemptable Tasks.

“LOW”
This Task cannot be preempted once it has started. A Task is considered started once the earliest time slot on any device has been reached. This Task may not preempt other Tasks.

“LOW_PREEMPT”
This Task may be preempted at any time. If the Task is preempted once it has begun running any current time slots will be given a grace period (configurable in the ActuatorAgent configuration file, defaults to 60 seconds) before being revoked. This Task may not preempt other Tasks.

Whenever a Task is preempted the Actuator Agent will publish a message to devices/actuators/schedule/result indicating that the Task has been cancelled due to being preempted. See Preemption Publishes

Even when using the RPC interface agents which schedule low priority tasks may need to subscribe to devices/actuators/schedule/result to learn when its Tasks are canceled due to preemption.

Device Schedule¶

The device schedule is a list of block of time for each device.

Both the RPC and PUB/SUB interface accept schedules in the following format:

[
    ["campus/building/device1", #First time slot.
     "2013-12-06 16:00:00",     #Start of time slot.
     "2013-12-06 16:20:00"],    #End of time slot.
    ["campus/building/device1", #Second time slot.
     "2013-12-06 18:00:00",     #Start of time slot.
     "2013-12-06 18:20:00"],    #End of time slot.
    ["campus/building/device2", #Third time slot.
     "2013-12-06 16:00:00",     #Start of time slot.
     "2013-12-06 16:20:00"],    #End of time slot.
    #etc...
]

Note

Points on Task Scheduling

Task id and requester id (agentid) should be a non empty value of type string
A Task schedule must have at least one time slot.
The start and end times are parsed with dateutil’s date/time parser. The default string representation of a python datetime object will parse without issue.
Two Tasks are considered conflicted if at least one time slot on a device from one task overlaps the time slot of the other on the same device.
The end time of one time slot can be the same as the start time of another time slot for the same device. This will not be considered a conflict. For example, time_slot1(device0, time1, time2) and time_slot2(device0,time2, time3) are not considered a conflict
A request must not conflict with itself.

New Task Response¶

Both the RPC and PUB/SUB interface respond to requests with the result in the following format:

{
    'result': <'SUCCESS', 'FAILURE'>,
    'info': <Failure reason string, if any>,
    'data': <Data about the failure or cancellation, if any>
}

The PUB/SUB interface will respond to requests on the devices/actuators/schedule/result topic.

The PUB/SUB interface responses will have the following header:

{
    'type': 'NEW_SCHEDULE'
    'requesterID': <VIP Identity of requesting agent>,
    'taskID': <Task ID from the request>
}

Failure Reasons¶

In many cases the ActuatorAgent will try to give good feedback as to why a request failed. The type of failure will populate “info” item as a string.

Some of these errors only apply to the PUB/SUB interface.

General Failures¶

“INVALID_REQUEST_TYPE”: Request type was not “NEW_SCHEDULE” or “CANCEL_SCHEDULE”.
“MISSING_TASK_ID”: Failed to supply a taskID.
“MISSING_AGENT_ID”: AgentID not supplied.

Task Schedule Failures¶

“TASK_ID_ALREADY_EXISTS “

The supplied taskID already belongs to an existing task.

“MISSING_PRIORITY”

Failed to supply a priority for a Task schedule request.

“INVALID_PRIORITY”

Priority not one of “HIGH”, “LOW”, or “LOW_PREEMPT”.

“MALFORMED_REQUEST_EMPTY”

Request list is missing or empty.

“REQUEST_CONFLICTS_WITH_SELF”

Requested time slots on the same device overlap.

“MALFORMED_REQUEST”

Reported when the request parser raises an unhandled exception. The exception name and info are appended to this info string.

“CONFLICTS_WITH_EXISTING_SCHEDULES”

This schedule conflict with an existing schedules that it cannot preempt. The data item for the results will contain info about the conflicts in this form:

{
    '<agentID1>': 
    {
        '<taskID1>':
        [
            ["campus/building/device1", 
             "2013-12-06 16:00:00",     
             "2013-12-06 16:20:00"],
            ["campus/building/device1", 
             "2013-12-06 18:00:00",     
             "2013-12-06 18:20:00"]     
        ]
        '<taskID2>':[...]
    }
    '<agentID2>': {...}
}

Device Interaction¶

Getting values¶

While a device driver for a device will periodically broadcast the state of a device you may want an up to the moment value for point on a device.

As of VOLTTRON 3.5 it is no longer required to have the device scheduled before you can use this interface.

Setting Values¶

RPC revert value interface PUB/SUB revert value interface

Failure to schedule the device first will result in an error.

Errors Setting Values¶

If there is an error the RPC interface will raise an exception and the PUB/SUB interface will publish to

devices/actuators/error/<full device path>/<actuation point>

The headder of the publish will take this form:

{
    'requesterID': <VIP Identity of requesting agent>
}

and a message body in this form:

{
    'type': <Class name of the exception raised by the request>
    'value': <Specific info about the error>
}

Common Error Types¶

LockError
Raised when a request is made when we do not have permission to use a device. (Forgot to schedule, preempted and we did not handle the preemption message correctly, ran out of time in time slot, etc…)

ValueError
Message missing (PUB/SUB only) or is the wrong data type.

Most other error types involve problems with communication between the VOLTTRON device drivers and the device itself.

Reverting Values and Devices to a Default State¶

As of VOLTTRON 3.5 device drivers are now required to support reverting to a default state. The exact mechanism used to accomplish this is driver specific.

Failure to schedule the device first will result in a LockError.

RPC revert device interface PUB/SUB revert device interface

Canceling a Task¶

Cancelling a Task requires two things:

The original requester of the Task. The agent’s VIP identity automatically replaces provided parameters.
The name of the Task.

Cancel Task Response¶

Both the RPC and PUB/SUB interface respond to requests with the result in the following format:

{
    'result': <'SUCCESS', 'FAILURE'>,
    'info': <Failure reason, if any>,
    'data': {}
}

Note

There are some things to be aware of when canceling a schedule:

The taskID must match the original value from the

original request header. - After a Tasks time has passed there is no need to cancel it. Doing so will result in a “TASK_ID_DOES_NOT_EXIST” error.

If an attempt cancel a schedule fails than the “info” item will have any of the following values:

“TASK_ID_DOES_NOT_EXIST”
Trying to cancel a Task which does not exist. This error can also occur when trying to cancel a finished Task.

“AGENT_ID_TASK_ID_MISMATCH”
A different agent ID is being used when trying to cancel a Task.

Preemption Publishes¶

If a Task is preempted it will publish the following to the devices/actuators/schedule/result topic:

{
    'result': 'PREEMPTED',
    'info': None,
    'data': {
                'agentID': <Agent ID of preempting task>,
                'taskID': <Task ID of preempting task>
            }
}

Along with the following header:

{
    'type': 'CANCEL_SCHEDULE',
    'requesterID': <VIP id associated with the preempted Task>,
    'taskID': <Task ID of the preempted Task>
}

Note

Remember that if your “LOW_PREEMPT” Task has already started and is preempted you have a grace period to do any clean up before losing access to the device.

Schedule State Publishes¶

Periodically the ActuatorAgent will publish the state of all currently reserved devices. The first publish for a device will happen exactly when the reserved block of time for a device starts.

For each device the ActuatorAgent will publish to an associated topic:

devices/actuators/schedule/announce/<full device path>

With the following header:

{
    'requesterID': <VIP identity of Agent with access>,
    'taskID': <Task associated with the time slot>
    'window': <Seconds remaining in the time slot>
}

The frequency of the updates is configurable with the “schedule_publish_interval” setting in the configuration.

class actuator.agent.ActuatorAgent(heartbeat_interval=60, schedule_publish_interval=60, preempt_grace_time=60, driver_vip_identity='platform.driver', allow_no_lock_write=True, **kwargs)[source]¶

Bases: volttron.platform.vip.agent.Agent

The Actuator Agent regulates control of devices by other agents. Agents request a schedule and then issue commands to the device through this agent.

The Actuator Agent also sends out the signal to drivers to trigger a device heartbeat.

Parameters

heartbeat_interval (float) – Interval in seonds to send out a heartbeat to devices.
schedule_publish_interval (float) – Interval in seonds to publish the currently active schedules.
schedule_state_file – Name of the file to save the current schedule state to. This file is updated every time a schedule changes.
preempt_grace_time (float) – Time in seconds after a schedule is preemted before it is actually cancelled.
driver_vip_identity (str) – VIP identity of the Platform Driver Agent.

configure(config_name, action, contents)[source]¶

get_multiple_points(topics, **kwargs)[source]¶

RPC method

Get multiple points on multiple devices. Makes a single RPC call to the platform driver per device.

Parameters

topics – List of topics or list of [device, point] pairs.
**kwargs – Any driver specific parameters

Returns

Dictionary of points to values and dictonary of points to errors

Warning

This method does not require that all points be returned successfully. Check that the error dictionary is empty.

get_point(topic, point=None, **kwargs)[source]¶

RPC method

Gets up to date value of a specific point on a device. Does not require the device be scheduled.

Parameters

topic (str) –
The topic of the point to grab in the format <device topic>/<point name>

Only the <device topic> if point is specified.
point – Point on the device. Uses old behavior if omitted.
**kwargs – Any driver specific parameters

Returns

point value

Return type

any base python type

handle_get(peer, sender, bus, topic, headers, message)[source]¶

Requests up to date value of a point.

To request a value publish a message to the following topic:

devices/actuators/get/<device path>/<actuation point>

with the fallowing header:

{
    'requesterID': <Ignored, VIP Identity used internally>
}

The ActuatorAgent will reply on the value topic for the actuator:

devices/actuators/value/<full device path>/<actuation point>

with the message set to the value the point.

handle_revert_device(peer, sender, bus, topic, headers, message)[source]¶

Revert all the writable values on a device.

To revert a device publish a message to the following topic:

devices/actuators/revert/device/<device path>

with the fallowing header:

{
    'requesterID': <Ignored, VIP Identity used internally>
}

The ActuatorAgent will reply on the value topic for the actuator:

devices/actuators/reverted/device/<full device path>

to indicate that a point was reverted.

Errors will be published on

devices/actuators/error/<full device path>/<actuation point>

with the same header as the request.

handle_revert_point(peer, sender, bus, topic, headers, message)[source]¶

Revert the value of a point.

To revert a value publish a message to the following topic:

actuators/revert/point/<device path>/<actuation point>

with the fallowing header:

{
    'requesterID': <Ignored, VIP Identity used internally>
}

The ActuatorAgent will reply on

devices/actuators/reverted/point/<full device path>/<actuation point>

This is to indicate that a point was reverted.

Errors will be published on

devices/actuators/error/<full device path>/<actuation point>

with the same header as the request.

handle_schedule_request(peer, sender, bus, topic, headers, message)[source]¶

Schedule request pub/sub handler

An agent can request a task schedule by publishing to the devices/actuators/schedule/request topic with the following header:

{
    'type': 'NEW_SCHEDULE',
    'requesterID': <Ignored, VIP Identity used internally>,
    'taskID': <unique task ID>, #The desired task ID for this
    task. It must be unique among all other scheduled tasks.
    'priority': <task priority>, #The desired task priority,
    must be 'HIGH', 'LOW', or 'LOW_PREEMPT'
}

The message must describe the blocks of time using the format described in Device Schedule.

A task may be canceled by publishing to the devices/actuators/schedule/request topic with the following header:

{
    'type': 'CANCEL_SCHEDULE',
    'requesterID': <Ignored, VIP Identity used internally>,
    'taskID': <unique task ID>, #The task ID for the canceled Task.
}

requesterID: The name of the requesting agent. Automatically replaced with VIP id.
taskID: The desired task ID for this task. It must be unique among all other scheduled tasks.
priority: The desired task priority, must be ‘HIGH’, ‘LOW’, or ‘LOW_PREEMPT’

No message is requires to cancel a schedule.

handle_set(peer, sender, bus, topic, headers, message)[source]¶

Set the value of a point.

To set a value publish a message to the following topic:

devices/actuators/set/<device path>/<actuation point>

with the fallowing header:

{
    'requesterID': <Ignored, VIP Identity used internally>
}

The ActuatorAgent will reply on the value topic for the actuator:

devices/actuators/value/<full device path>/<actuation point>

with the message set to the value the point.

Errors will be published on

devices/actuators/error/<full device path>/<actuation point>

with the same header as the request.

request_cancel_schedule(requester_id, task_id)[source]¶

RPC method

Requests the cancellation of the specified task id.

Parameters

requester_id (str) – Ignored, VIP Identity used internally
task_id (str) – Task name.

Returns

Request result

Return type

dict

Return Values

The return values are described in Cancel Task Response.

request_new_schedule(requester_id, task_id, priority, requests)[source]¶

RPC method

Requests one or more blocks on time on one or more device.

Parameters

requester_id – Ignored, VIP Identity used internally
task_id – Task name.
priority – Priority of the task. Must be either “HIGH”, “LOW”,

or “LOW_PREEMPT” :param requests: A list of time slot requests in the format described in Device Schedule.

Returns: Request result
Return type: dict
Return Values: The return values are described in New Task Response.

revert_device(requester_id, topic, **kwargs)[source]¶

RPC method

Reverts all points on a device to a default state. Requires the device be scheduled by the calling agent.

Parameters

requester_id (str) – Ignored, VIP Identity used internally
topic (str) – The topic of the device to revert
**kwargs – Any driver specific parameters

Warning

Calling without previously scheduling a device and not

within: the time allotted will raise a LockError

revert_point(requester_id, topic, point=None, **kwargs)[source]¶

RPC method

Reverts the value of a specific point on a device to a default state. Requires the device be scheduled by the calling agent.

Parameters

requester_id (str) – Ignored, VIP Identity used internally
topic (str) – The topic of the point to revert in the format <device topic>/<point name>
**kwargs – Any driver specific parameters

Warning

Calling without previously scheduling a device and not

within: the time allotted will raise a LockError

scrape_all(topic)[source]¶

RPC method

Get all points from a device.

Parameters: topic – Device topic
Returns: Dictionary of points to values

set_multiple_points(requester_id, topics_values, **kwargs)[source]¶

RPC method

Set multiple points on multiple devices. Makes a single RPC call to the platform driver per device.

Parameters

requester_id – Ignored, VIP Identity used internally
topics_values – List of (topic, value) tuples
**kwargs – Any driver specific parameters

Returns

Dictionary of points to exceptions raised. If all points were set successfully an empty dictionary will be returned.

Warning

calling without previously scheduling all devices and not within the time allotted will raise a LockError

set_point(requester_id, topic, value, point=None, **kwargs)[source]¶

RPC method

Sets the value of a specific point on a device. Requires the device be scheduled by the calling agent.

Parameters

requester_id (str) – Ignored, VIP Identity used internally
topic (str) – The topic of the point to set in the format <device topic>/<point name> Only the <device topic> if point is specified.
value (any basic python type) – Value to set point to.
point (str) – Point on the device. Uses old behavior if omitted.
**kwargs – Any driver specific parameters

Returns

value point was actually set to. Usually invalid values cause an error but some drivers (MODBUS) will return a different value with what the value was actually set to.

Return type

any base python type

Warning

Calling without previously scheduling a device and not

within: the time allotted will raise a LockError

exception actuator.agent.LockError[source]¶

Bases: Exception

Error raised when the user does not have a device scheuled and tries to use methods that require exclusive access.

actuator.agent.actuator_agent(config_path, **kwargs)[source]¶

Parses the Actuator Agent configuration and returns an instance of the agent created using that configuation.

Parameters: config_path (str) – Path to a configuation file.
Returns: Actuator Agent
Return type: ActuatorAgent

actuator.agent.main()[source]¶: Main method called to start the agent.

actuator.scheduler module¶

class actuator.scheduler.DeviceState(agent_id, task_id, time_remaining)¶

Bases: tuple

property agent_id¶: Alias for field number 0

property task_id¶: Alias for field number 1

property time_remaining¶: Alias for field number 2

class actuator.scheduler.RequestResult(success, data, info_string)¶

Bases: tuple

property data¶: Alias for field number 1

property info_string¶: Alias for field number 2

property success¶: Alias for field number 0

class actuator.scheduler.Schedule[source]¶

Bases: object

check_availability(time_slot)[source]¶

finished(now)[source]¶

get_conflicts(other)[source]¶: Returns a list of our time_slices that conflict with the other schedule

get_current_slot(now)[source]¶

get_next_event_time(now)[source]¶: Run this to know when to the next state change is going to happen with this schedule

get_schedule()[source]¶

make_current(now)[source]¶: Should be called before working with a schedule. Updates the state to the schedule to eliminate stuff in the past.

prune_to_current(grace_time, now)[source]¶: Use this to prune a schedule due to preemption.

schedule_slot(time_slot)[source]¶

exception actuator.scheduler.ScheduleError[source]¶: Bases: Exception

class actuator.scheduler.ScheduleManager(grace_time, now=None, save_state_callback=None, initial_state_string=None)[source]¶

Bases: object

cancel_task(agent_id, task_id, now)[source]¶

get_next_event_time(now)[source]¶

get_schedule_state(now)[source]¶

load_state(now, initial_state_string)[source]¶

request_slots(agent_id, id_, requests, priority, now=None)[source]¶

save_state(now)[source]¶

set_grace_period(seconds)[source]¶

class actuator.scheduler.Task(agent_id, priority, requests)[source]¶

Bases: object

STATE_FINISHED = 'FINISHED'¶

STATE_PREEMPTED = 'PREEMPTED'¶

STATE_PRE_RUN = 'PRE_RUN'¶

STATE_RUNNING = 'RUNNING'¶

change_state(new_state)[source]¶

check_can_preempt_other(other)[source]¶

get_conflicts(other)[source]¶

get_current_slots(now)[source]¶

get_next_event_time(now)[source]¶

make_current(now)[source]¶

populate_schedule(requests)[source]¶

preempt(grace_time, now)[source]¶: Return true if there are time slots that have a grace period left

class actuator.scheduler.TimeSlice(start=None, end=None)[source]¶

Bases: object

contains_include_start(other)[source]¶: Similar to == or “in” but includes time == self.start

property end¶

property start¶

stretch_to_include(time_slice)[source]¶

Actuator Agent¶

The Actuator Agent is used to manage write access to devices. Other agents may request scheduled times, called Tasks, to interact with one or more devices.

Agents may interact with the ActuatorAgent via either PUB/SUB or RPC, but it is recommended agents use RPC to interact with the ActuatorAgent. For an example of an agent using RPC to interact with the ActuatorAgent, see the SchedulerExample agent from the Volttron repository.

The PUB/SUB interface remains primarily for VOLTTRON 2.0 agents.

The Actuator Agent also triggers the heart beat on devices whose drivers are configured to do so.

ActuatorAgent Configuration¶

“schedule_publish_interval”

Interval between published schedule announcements in seconds. Defaults to 30.
“preempt_grace_time”

Minimum time given to Tasks which have been preempted to clean up in seconds. Defaults to 60.
“schedule_state_file”

File used to save and restore Task states if the ActuatorAgent restarts for any reason. File will be created if it does not exist when it is needed.
“heartbeat_interval”

How often to send a heartbeat signal to all devices in seconds. Defaults to 60.

Sample configuration file¶

{
    "schedule_publish_interval": 30,
    "schedule_state_file": "actuator_state.pickle"
}

Ambient¶

ambient package¶

ambient.agent module¶

class ambient.agent.Ambient(application_key='', **kwargs)[source]¶

Bases: volttron.platform.agent.base_weather.BaseWeatherAgent

The Ambient agent requires having an API key to interact with the remote API. The agent offers a performance_mode configuration option which allows users to limit the amount of data returned by the API.

generate_response_error(url, response_code)[source]¶: Raises a descriptive runtime error based on the response code returned by a service. :param url: actual url used for requesting data from Ambient :param response_code: Http response code returned by a service following a request

get_api_description(service_name)[source]¶: Provides a human-readable description of the various endpoints provided by the agent :param service_name: requested service endpoint :return: Human-readable description string

get_point_name_defs_file()[source]¶: Constructs the point name mapping dict from the mapping csv. :return: dictionary containing a mapping of service point names to standard point names with optional

get_update_interval(service_name)[source]¶: Indicates the interval between remote API updates :param service_name: requested service endpoint :return: datetime timedelta representing the time interval

get_version()[source]¶: Provides the current version of the agent. :return: current version number in string format.

make_request()[source]¶

Request data from the Ambient Weather API An example of the return value is as follows

[

{

“macAddress”: “18:93:D7:3B:89:0C”, “lastData”: {

“dateutc”: 1556212140000, “tempinf”: 71.9, “humidityin”: 31, “battout”: “1”, “temp1f”: 68.7, “humidity1”: 36, “batt1”: “1”, “date”: “2019-04-25T17:09:00.000Z”

}, “info”: {

“name”: “Home B WS”, “location”: “Lab Home B”

}

}, {

“macAddress”: “50:F1:4A:F7:3C:C4”, “lastData”: {

“dateutc”: 1556211960000, “tempinf”: 82.5, “humidityin”: 27, “battout”: “1”, “temp1f”: 68.5, “humidity1”: 42, “batt1”: “1”, “date”: “2019-04-25T17:06:00.000Z”

}, “info”: {

“name”: “Home A WS”, “location”: “Lab Home A”

}

}

] :return:

query_current_weather(location)[source]¶: Retrieve data from the Ambient API, return formatted current data and store forecast data in cache :param location: location dictionary requested by the user :return: Timestamp and data for current data from the Ambient API

query_forecast_service(service, location, quantity, forecast_start)[source]¶: Unimplemented method stub :param service: forecast service type of weather data to return :param location: location dictionary requested during the RPC call :param quantity: number of records to return, used to generate Time Machine requests after the forecast request :param forecast_start: forecast results that are prior to this timestamp will be filtered by base weather agent :return: Timestamp and data returned by the Ambient weather API response

query_hourly_forecast(location)[source]¶: Unimplemented method stub :param location: currently accepts lat/long location dictionary format only :return: time of forecast prediction as a timestamp string, and a list of

query_hourly_historical(location, start_date, end_date)[source]¶: Unimplemented method stub :param location: no format currently determined for history. :param start_date: Starting date for historical weather period. :param end_date: Ending date for historical weather period. :return: NotImplementedError

validate_location(service_name, location)[source]¶: Indicates whether the location dictionary provided matches the format required by the remote weather API :param service_name: name of the remote API service :param location: location dictionary to provide in the remote API url :return: True if the location matches the required format else False

ambient.agent.ambient(config_path, **kwargs)[source]¶: Parses the Agent configuration and returns an instance of the agent created using that configuration. :param config_path: Path to a configuration file. :type config_path: str :returns: Ambient :rtype: Ambient

ambient.agent.main()[source]¶: Main method called to start the agent.

Ambient Weather Agent¶

The Ambient weather agent provides the ability to query for current weather data from Ambient weather stations via the Ambient weather API. The agent inherits features of the Volttron BaseWeatherAgent which provides caching of recently recieved data, as well as point name mapping and unit conversion using the standardized CF-conventions scheme.lu

The values from the Ambient weather station can be accessed through the cloud platform which can be accessed at https://dashboard.ambientweather.net/dashboard

Two API Keys are required for all REST API requests:

applicationKey - identifies the developer / application. To request an application key please email support@ambientweather.com

apiKey - grants access to past/present data for a given user's devices. A typical consumer-facing application will initially ask the user to create an apiKey on thier AmbientWeather.net account page (https://dashboard.ambientweather.net/account) and paste it into the app. Developers for personal or in-house apps will also need to create an apiKey on their own account page.

API requests are capped at 1 request/second for each user's apiKey and 3 requests/second per applicationKey. When this limit is exceeded, the API will return a 429 response code. This will result in a response from the Ambient agent containing "weather_error" and no weather data.

Ambient Endpoints¶

The Ambient Weather agent provides only current weather data (all other base weather endpoints are unimplemented, and will return a record containing "weather_error" if used).

The location format for the Ambient agent is as follows:

{"location": "<location_string>"}

Ambient locations are Arbitrary string identifiers given to a weather station by the weather station owner/operator.

This is an example response:

2019-12-17 15:35:56,395 (listeneragent-3.3 3103) listener.agent INFO: Peer: pubsub, Sender: platform.ambient:, Bus: , Topic: weather/poll/current/all, Headers: {'Date': '2019-12-17T23:35:56.392709+00:00', 'Content-Type': 'Content-Type', 'min_compatible_version': '3.0', 'max_compatible_version': ''}, Message:
[{'location': 'Lab Home A',
  'observation_time': '2019-12-18T07:33:00.000000+00:00',
  'weather_results': {'batt1': 1,
                      'battout': 1,
                      'dateutc': 1576625580000,
                      'dewPointin': 39.6,
                      'feelsLikein': 70.2,
                      'humidity1': 1,
                      'humidityin': 31,
                      'macAddress': '50:F1:4A:F7:3C:C4',
                      'name': 'Home A WS',
                      'tempinf': 71.9,
                      'tz': 'Etc/GMT'}},
 {'location': 'Lab Home B',
  'observation_time': '2019-12-18T07:33:00.000000+00:00',
  'weather_results': {'batt1': 1,
                      'battout': 1,
                      'dateutc': 1576625580000,
                      'dewPoint1': 28.6,
                      'dewPointin': 23.5,
                      'feelsLike1': 35.7,
                      'feelsLikein': 53.4,
                      'humidity1': 75,
                      'humidityin': 31,
                      'macAddress': '18:93:D7:3B:89:0C',
                      'name': 'Home B WS',
                      'temp1f': 35.7,
                      'tempinf': 53.4,
                      'tz': 'Etc/GMT'}}]

The selection of weather data points which are included may depend upon the type of Ambient device.

Configuration¶

The following is an example configuration for the Ambient agent. The "api_key" and "app_key" parameters are required while all others are optional.

Parameters

“api_key” - api key string provided by Ambient - this is required and will not be provided by the VOLTTRON team.
“appplication_key” - application key string provided by Ambient - this is required and will not be provided by the VOLTTRON team.
“database_file” - sqlite database file for weather data caching. Defaults to "weather.sqlite" in the agent's data directory.
“max_size_gb” - maximum size of cache database. When cache exceeds this size, data will get purged from cache till cache is within the configured size.
“poll_locations” - list of locations to periodically poll for current data.
“poll_interval” - polling frequency or the number of seconds between each poll.

Example configuration:

{
    "application_key" : "<api_key>",
    "api_key":"<application_key>",
    "poll_locations": [
      {"location": "Lab Home A"},
      {"location": "Lab Home B"}
    ],
    "poll_interval": 60,
    "identity": "platform.ambient"
}

Registry Configuration¶

The registry configuration file for this agent can be found in agent's data directory. This configuration provides the point name mapping from the Ambient API's point scheme to the CF-conventions scheme by default. Points that do not specify "Standard_Point_Name" were found to not have a logical match to any point found in the CF-Conventions. For these points Ambient point name convention (Service_Point_Name) will be used.

Running Ambient Agent Tests¶

The following instructions can be used to run PyTests for the Ambient agent.

1. Set up the test file - test_ambient_agent.py is the PyTest file for the ambient agent. The test file features a few variables at the top of the tests. These will need to be filled in by the runner of the Ambient agent tests. The LOCATIONS variable specifies a list of "locations" of Ambient devices. The required format is a list of dictionaries of the form {"location": <ambient weather station location>}. Locations are determined by the user when configuring a weather station for the Ambient service using the Ambient app. For more information about the Ambient API, visit https://www.ambientweather.com/api.html

2. Set up the test environment - The tests are intended to be run from the Volttron root directory using the Volttron environment. Setting the environment variable, DEBUG_MODE=True or DEBUG=1 will preserve the test setup and can be useful for debugging purposes. When testing from pycharm set the Working Directory value to be the root of volttron source/checkout directory.

Example command line:

(volttron) <user>@<host>:~/volttron$ pytest -s ~/house-deployment/Ambient

BACnetProxy¶

bacnet_proxy package¶

bacnet_proxy.agent module¶

BACnet Proxy Agent¶

Communication with BACnet device on a network happens via a single virtual BACnet device. In VOLTTRON driver framework, we use a separate agent specifically for communicating with BACnet devices and managing the virtual BACnet device.

Dependencies¶

The BACnet Proxy agent requires the BACPypes package. This package can be installed in an activated environment with:
```
pip install bacpypes
```
Current versions of VOLTTRON support only BACPypes version 0.16.7

Agent Configuration¶

{
    "device_address": "10.0.2.15",
    "max_apdu_length": 1024,
    "object_id": 599,
    "object_name": "Volttron BACnet driver",
    "vendor_id": 15,
    "segmentation_supported": "segmentedBoth"
}

device_address - Address bound to the network port over which BACnet communication will happen on the computer running VOLTTRON. This is NOT the address of any target device.
object_id - ID of the Device object of the virtual BACnet device. Defaults to 599. Only needs to be changed if there is a conflicting BACnet device ID on your network.
max_apdu_length - Maximum size message the device can handle
object_name - Name of the object. Defaults to “Volttron BACnet driver”. (Optional)
vendor_id - Vendor ID of the virtual BACnet device. Defaults to 15. (Optional)
segmentation_supported - Segmentation allows larger messages to be broken up into segments and spliced back together. Possible setting are “segmentedBoth” (default), “segmentedTransmit”, “segmentedReceive”, or “noSegmentation” (Optional)

CrateHistorian¶

cratedb package¶

cratedb.historian module¶

Crate Historian¶

Crate is an open source SQL database designed on top of a No-SQL design. It allows automatic data replication and self-healing clusters for high availability, automatic sharding, and fast joins, aggregations and sub-selects.

Find out more about crate from https://crate.io/.

Upgrading¶

As of version 3 of the CrateHistorian the default topics table is topics instead of topic. To continue using the same table name for topics please add a tabledef section to your configuration file

{
    "connection": {
        "type": "crate",
        # Optional table prefix defaults to historian
        "schema": "testing",
        "params": {
            "host": "localhost:4200"
        }
    },
    "tables_def": {
        "table_prefix": "",
        "data_table": "data",
        "topics_table": "topics",
        "meta_table": "meta"
    }
}

**NOTE:** CrateHistorian is still alpha, schemas could change in the future, do not use this for production data until schema is confirmed as final Currently the historian supports two schemas for numerical data, the primary schema closely resembles the SQLHistorian schema but there is an optional "raw" schema that can be enabled in the config below that utilizes some of the advanced indexing features of crate

Prerequisites¶

1. Crate Database¶

Install crate version 3.3.3 from https://cdn.crate.io/downloads/releases/crate-3.3.3.tar.gz. Untar the file and run crate-3.3.3/bin/crate to start crate. After the installation the service will be available for viewing at http://localhost:4200 by default.

**NOTE:** Authentication for crate is an enterprise subscription only feature.

2. Crate Driver¶

There is a python library for crate that must be installed in the volttron python environment in order to access crate. From an activated environment, in the root of the volttron folder, execute the following command:

python bootstrap.py --crate

or

pip install crate

Configuration¶

The following is an example of the crate historian's configuration.

{
    "connection": {
        "type": "crate",
        # Optional table prefix defaults to historian
        "schema": "testing",
        "params": {
            "host": "localhost:4200"
        }
    }
}

Darksky¶

darksky package¶

darksky.agent module¶

class darksky.agent.Darksky(performance_mode=True, **kwargs)[source]¶

Bases: volttron.platform.agent.base_weather.BaseWeatherAgent

The Darksky agent requires having an API key to interact with the remote API. The agent offers a performance_mode configuration option which allows users to limit the amount of data returned by the API.

*Powered by Dark Sky*

create_forecast_entry(service, location, timestamp, forecast_start)[source]¶

Helper method used for removing extraneous data from a forecast request response based on request time :param service: weather agent service endpoint :param location: request location dictionary :param timestamp: timestamp for the forecast request. If None, the default forecast result of

are returned - a minute-by-minute forecast for the next hour (where available), or an hour-by-hour forecast for the next 48 hours, or a day-by-day forecast for the next week

Returns: (the last time stamp for which forecast is returned, filtered Dark Sky forecast response)

format_multientry_response(location, response, service, timezone)[source]¶: Used to extract the data not used by the RPC method, and store it in the cache, helping to limit the number of API calls used to obtain data :param location: location dictionary to include with cached data :param response: Darksky forecast response :param service: :param timezone: timezone string extracted from Darksky response :return: formatted response data by service

generate_response_error(url, response_code)[source]¶: raises a descriptive runtime error based on the response code returned by a service. :param url: actual url used for requesting data from Darksky :param response_code: Http response code returned by a service following a request

get_api_calls_interval()[source]¶

Returns: Returns a datetime object representing the time period for API

calls to expire as well as a number representing the number of API calls alloted during the period

get_api_description(service_name)[source]¶: Provides a human-readable description of the various endpoints provided by the agent :param service_name: requested service endpoint :return: Human-readable description string

get_daily_forecast(locations, days=7)[source]¶: RPC method for getting time series forecast weather data by full day. :param locations: list of location dictionaries from the RPC call :param days: Number of minutes of weather data to be returned :return: List of daily forecast weather dictionaries

get_darksky_data(service, location, timestamp=None)[source]¶: Generic method called by the current and forecast service endpoint methods to fetch a forecast request from the Darksky API. If performance mode is set to True, the url adds exclusions for the services provided by the API that were not requested. :param service: requested service endpoint :param location: location dictionary for building url :param timestamp: timestamp of a record if this request is for the Time Machine end point :return: Darksky forecast request response

get_generation_time_for_service(service)[source]¶: Calculates generation time of forecast request response. “Next-hour minutely forecast data is updated every five minutes. Hourly and daily forecast data are updated every hour.” (https://darksky.net/dev/docs/faq#data-update) :param service: requested weather agent service endpoint :return: Datetime object representing the timestamp when the weather was forecasted

get_hourly_forecast(locations, hours=48)[source]¶: Overload of get_hourly_forecast method of base weather agent - sets default hours to 48 as this is the quantity provided by a Dark Sky forecast request :param locations: ist of location dictionaries from the RPC call :param hours: Number of hours of weather data to be returned :return: Dark Sky forecast data by the hour

get_minutely_forecast(locations, minutes=60)[source]¶: RPC method for getting time series forecast weather data minute by minute. Dark Sky does not provide more than 1 hour into the future of minutely forecast data. :param locations: list of location dictionaries from the RPC call :param minutes: Number of minutes of weather data to be returned :return: List of minutely forecast weather dictionaries

get_point_name_defs_file()[source]¶: Constructs the point name mapping dict from the mapping csv. :return: dictionary containing a mapping of service point names to standard point names with optional

get_update_interval(service_name)[source]¶: Indicates the interval between remote API updates :param service_name: requested service endpoint :return: datetime timedelta representing the time interval

get_version()[source]¶: Provides the current version of the agent. :return: current version number in string format.

query_current_weather(location)[source]¶: Retrieve data from the Darksky API, return formatted current data and store forecast data in cache :param location: location dictionary requested by the user :return: Timestamp and data for current data from the Darksky API

query_forecast_service(service, location, quantity, forecast_start)[source]¶

Generic method for requesting forecast data from the various RPC forecast methods. If the user requests a number of records to return greater than the default for the forecast request(7 daily records) additional API calls will be made to the Dark Sky Time Machine endpoint. If the number of API calls required to fulfill the additional records is greater than the amount of available API calls, the user will receive only the records returned by the forecast request. :param service: forecast service type of weather data to return :param location: location dictionary requested during the RPC call :param quantity: number of records to return, used to generate Time Machine requests after the forecast request :param forecast_start: forecast results that are prior to this

timestamp will be filtered by base weather agent

Returns: Timestamp and data returned by the Darksky weather API response

validate_location(service_name, location)[source]¶: Indicates whether the location dictionary provided matches the format required by the remote weather API :param service_name: name of the remote API service :param location: location dictionary to provide in the remote API url :return: True if the location matches the required format else False

darksky.agent.darksky(config_path, **kwargs)[source]¶

Parses the Agent configuration and returns an instance of the agent created using that configuration.

Parameters: config_path (str) – Path to a configuration file.
Returns: Darksky
Return type: Darksky

darksky.agent.main()[source]¶: Main method called to start the agent.

Dark Sky Agent¶

Powered by Dark Sky

This agent provides the ability to query for current and forecast weather data from Dark Sky. The agent extends BaseWeatherAgent that provides caching of recently requested data, API call tracking, as well as mapping of weather point names from Darksky's naming scheme to the standardized CF-conventions scheme.

Requirements¶

The Dark Sky agent requires the Pint package. This package can be installed in an activated environment with:

pip install pint

Dark Sky Endpoints¶

The Dark Sky agent provides the following endpoints in addition to those included with the base weather agent:

Get Minutely Forecast Data¶

RPC call to weather service method ‘get_minutely_forecast’

Parameters:

locations - List of dictionaries containing location details. Dark Sky requires

[{"lat": <lattitude>, "long": <longitude>},...]

optional parameters:

minutes - The number of minutes for which forecast data should
be returned. By default, it is 60 minutes as well as the current minute. Dark Sky does not provide minutely data for more than one hour (60 minutes) into the future.

Get Daily Forecast Data¶

RPC call to weather service method ‘get_minutely_forecast’

Parameters:

locations - List of dictionaries containing location details. Dark Sky requires

[{"lat": <lattitude>, "long": <longitude>},...]

optional parameters:

days - The number of days for which forecast data should be returned. By default, it is the next 7 days as well as the current day.

Please note: If your forecast request to the Dark Sky agent asks for more data points than the default, the agent must use an additional API calls; an additional API call will be used to fetch any records not included in the default forecast request for the current day, and one additional call for each subsequent day of data the request would require, regardless of Dark Sky agent endpoint (If requesting 60 hours of hourly data Monday night at 8PM, 3 API calls must be made to fulfill the request: one for the initial request containing 48 hours of data, one for the remaining 4 hours of Wednesday evening's data, and one for records in Thursday's forecast).

Configuration¶

The following is an example configuration for the Dark Sky agent. The "api_key" parameter is required while all others are optional.

Parameters

"api_key" - api key string provided by Dark Sky - this is required and will not be provided by the VOLTTRON team.
"api_calls_limit" - limit of api calls that can be made to the remote before the agent no longer returns weather results. The agent will keep track of number of api calls and return an error when the limit is reached without attempting a connection to dark sky server. This is primarily used to prevent possible charges. If set to -1, no limit will be applied by the agent. Dark sky api might return a error after limit is exceeded. Defaults to -1
"database_file" - sqlite database file for weather data caching. Defaults to "weather.sqlite" in the agent's data directory.
"max_size_gb" - maximum size of cache database. When cache exceeds this size, data will get purged from cache till cache is within the configured size.
"poll_locations - list of locations to periodically poll for current data.
"poll_interval" - polling frequency or the number of seconds between each poll.
"performance_mode" - If set to true, request response will exclude extra data points (this is primarily useful for reducing network traffic). If set to false, all data points are included in the response, and extra data is cached (to reduce the number of API calls used for future RPC calls). Defaults to True.

Example configuration:

{
    "api_key": "<api key string>",
    "api_calls_limit": 1000,
    "database_file": "weather.sqlite",
    "max_size_gb": 1,
    "poll_locations": [{"lat": 39.7555, "long": -105.2211},
                       {"lat": 46.2804, "long": -119.2752}],
    "poll_interval": 60
}

Registry Configuration¶

The registry configuration file for this agent can be found in agent's data directory. This configuration provides the point name mapping from the Dark Sky API's point scheme to the CF-conventions scheme by default. Points that do not specify "Standard_Point_Name" were found to not have a logical match to any point found in the CF-Conventions. For these points Dark Sky point name convention (Service_Point_Name) will be used.

Service_Point_Name	Standard_Point_Name	Service_Units	Standard_Units
precipIntensity	lwe_precipitation_rate	millimeter / hour	meter / second
precipProbability
temperature	surface_temperature	degC	degK
apparentTemperature		degC	degK
dewPoint	dew_point_temperature	degC	degK

Notes¶

The Dark Sky agent requires an API key to be configured in order for users to request data. A user of the Dark Sky agent must obtain the key themselves.

API call tracking features will work only when each agent instance uses its own api key. If API key is shared across multiple dark sky agent instances, disable this feature by setting api_calls_limit = -1.

As of writing, dark sky gives 1000 daily API calls free for a trial account. Once this limit is reached, the error "daily usage limit exceeded" is returned. See https://darksky.net/dev for details

By default performance mode is set to True and for a given location and time period only the requested data points are returned. Set performance_mode to False to query all available data for a given location and time period if you want to cache all the data points for future retrieval there by reducing number of API calls.

DataMover¶

datamover package¶

datamover.agent module¶

class datamover.agent.DataMover(destination_vip, destination_serverkey, destination_historian_identity='platform.historian', remote_identity=None, **kwargs)[source]¶

Bases: volttron.platform.agent.base_historian.BaseHistorian

This historian forwards data to another platform.

capture_data(peer, sender, bus, topic, headers, message)[source]¶

configure(configuration)[source]¶

Optional, may be implemented by a concrete implementation to add support for the configuration store. Values should be stored in this function only.

The process thread is stopped before this is called if it is running. It is started afterwards.

historian_setup is called after this is called.

historian_setup()[source]¶: Optional setup routine, run in the processing thread before main processing loop starts. Gives the Historian a chance to setup connections in the publishing thread.

historian_teardown()[source]¶: Optional teardown routine, run in the processing thread if the main processing loop is stopped. This happened whenever a new configuration arrives from the config store.

publish_to_historian(to_publish_list)[source]¶

Main publishing method for historian Agents.

Parameters: to_publish_list (list) – List of records

to_publish_list takes the following form:

[
    {
        'timestamp': timestamp1.replace(tzinfo=pytz.UTC),
        'source': 'scrape',
        'topic': "pnnl/isb1/hvac1/thermostat",
        'value': 73.0,
        'meta': {"units": "F", "tz": "UTC", "type": "float"}
    },
    {
        'timestamp': timestamp2.replace(tzinfo=pytz.UTC),
        'source': 'scrape',
        'topic': "pnnl/isb1/hvac1/temperature",
        'value': 74.1,
        'meta': {"units": "F", "tz": "UTC", "type": "float"}
    },
    ...
]

The contents of meta is not consistent. The keys in the meta data values can be different and can change along with the values of the meta data. It is safe to assume that the most recent value of the “meta” dictionary are the only values that are relevant. This is the way the cache treats meta data.

Once one or more records are published either BaseHistorianAgent.report_all_handled() or BaseHistorianAgent.report_handled() must be called to report records as being published.

timestamp()[source]¶

datamover.agent.historian(config_path, **kwargs)[source]¶

datamover.agent.main(argv=['/home/docs/checkouts/readthedocs.org/user_builds/volttron/envs/releases-8.1.1/lib/python3.6/site-packages/sphinx/__main__.py', '-T', '-b', 'readthedocssinglehtmllocalmedia', '-d', '_build/doctrees', '-D', 'language=en', '.', '_build/localmedia'])[source]¶

DataMover Historian¶

The DataMover Historian is used to send data from one instance of VOLTTRON to another. This agent is similar to the Forward Historian but does not publish data on the target platform's message bus. Messages are instead inserted into the backup queue in the target's historian. This helps to ensure that messages are recorded.

If the target instance becomes unavailable or the target historian is stopped then this agent's cache will build up until it reaches it's maximum capacity or the instance and agent comes back online.

The DataMover now uses the configuration store for storing its configurations. This allows dynamic updating of configuration without having to rebuild the agent.

Configuration Options¶

The following JSON configuration file shows all the options currently supported by the DataMover agent.

{
    # destination-serverkey
    #   The destination instance's publickey. Required if the
    #   destination-vip-address has not been added to the known-host file.
    #   See vctl auth --help for all instance security options.
    #
    #   This can be retrieved either through the command:
    #       vctl auth serverkey
    #   Or if the web is enabled on the destination through the browser at:
    #       http(s)://hostaddress:port/discovery/
    "destination-serverkey": null,

    # destination-vip-address - REQUIRED
    #   Address of the target platform.
    #   Examples:
    #       "destination-vip": "ipc://@/home/volttron/.volttron/run/vip.socket"
    #       "destination-vip": "tcp://127.0.0.1:23916"
    "destination-vip": "tcp://<ip address>:<port>",

    # destination_historian_identity
    #   Identity of the historian to send data to. Only needed if data
    #   should be sent an agent other than "platform.historian"
    "destination-historian-identity": "platform.historian",

    # remote_identity - OPTIONAL
    #    identity that will show up in peers list on the remote platform
    #    By default this identity is randomly generated
    "remote-identity": "22916.datamover"
}

ExternalData¶

external_data package¶

external_data.agent module¶

class external_data.agent.ExternalData(interval, default_user, default_password, sources, global_topic_prefix, **kwargs)[source]¶

Bases: volttron.platform.vip.agent.Agent

Gathers and publishes JSON data available via a web api.

external_data.agent.external_data_agent(config_path, **kwargs)[source]¶

external_data.agent.main(argv=['/home/docs/checkouts/readthedocs.org/user_builds/volttron/envs/releases-8.1.1/lib/python3.6/site-packages/sphinx/__main__.py', '-T', '-b', 'readthedocssinglehtmllocalmedia', '-d', '_build/doctrees', '-D', 'language=en', '.', '_build/localmedia'])[source]¶: Main method called by the eggsecutable.

External Data Agent¶

This agent gathers and publishes JSON data available via a web api

Configuration¶

The following is an example configuration file for the External Data Agent:

{
#Interval at which to scrape the sources.
"interval":300,

#Global topic prefix for all publishes.
"global_topic_prefix": "record",

#Default user name and password if all sources require the same
#credentials. Can be overridden in individual sources.
#"default_user":"my_user_name",
#"default_password" : "my_password",

"sources":
[
 {
    #Valid types are "csv", "json", and "raw"
    #Defaults to "raw"
    "type": "csv",
    #Source URL for CSV data.
    "url": "https://example.com/example",

    #URL parameters for data query (optional).
    # See https://en.wikipedia.org/wiki/Query_string
    "params": {"period": "currentinterval",
               "format": "csv"},

    #Topic to publish on.
    "topic": "example/examplecsvdata1",

    #Column used to break rows in CSV out into separate publishes.
    #The key will be removed from the row data and appended to the end
    # of the publish topic.
    # If this option is missing the entire CSV will be published as a list
    # of objects.
    #If the column does not exist nothing will be published.
    "key": "Key Column",

    #Attempt to parse these columns in the data into numeric types.
    #Currently columns are parsed with ast.literal_eval()
    #Values that fail to parse are left as strings unless the
    # values is an empty string. Empty strings are changed to None.
    "parse": ["Col1", "Col2"],

    #Source specific authentication.
    "user":"username",
    "password" : "password"
 },
 {
    #Valid types are "csv", "json", and "raw"
    #Defaults to "raw"
    "type": "csv",
    #Source URL for CSV data.
    "url": "https://example.com/example_flat",

    #URL parameters for data query (optional).
    # See https://en.wikipedia.org/wiki/Query_string
    "params": {"format": "csv"},

    #Topic to publish on. (optional)
    "topic": "example/examplecsvdata1",

    #If the rows in a csv represent key/value pairs use this
    #setting to reduce this format to a single object for publishing.
    "flatten": true,

    #Attempt to parse these columns in the data into numeric types.
    #Currently columns are parsed with ast.literal_eval()
    #Values that fail to parse are left as strings unless the
    # values is an empty string. Empty strings are changed to None.
    "parse": ["Col1", "Col2"]
 },
 {
    #Valid types are "csv", "json", and "raw"
    #Defaults to "raw"
    "type": "json",
    #Source URL for JSON data.
    "url": "https://example.com/api/example1",

    #URL parameters for data query (optional)
    # See https://en.wikipedia.org/wiki/Query_string
    "params": {"format": "json"},

    #Topic to publish on. (optional)
    "topic": "example/exampledata1",

    #Path to desired data withing the JSON. Optional.
    #Elements in a path may be either a string or an integer.
    #Useful for peeling off unneeded layers around the wanted data.
    "path": ["parentobject", "0"],

    #After resolving the path above if the resulting data is a list
    # the key is the path to a value in a list item. Each item in the list
    # is published separately with the key appended to the end of the topic.
    # Elements in a key may be a string or an integer. (optional)
    "key": ["Location", "$"],

    #Source specific authentication.
    "user":"username",
    "password" : "password"
 }
]

}

ForwardHistorian¶

forwarder package¶

forwarder.agent module¶

class forwarder.agent.ForwardHistorian(destination_vip, destination_serverkey, custom_topic_list=[], topic_replace_list=[], required_target_agents=[], cache_only=False, destination_address=None, **kwargs)[source]¶

Bases: volttron.platform.agent.base_historian.BaseHistorian

This historian forwards data to another instance as if it was published originally to the second instance.

capture_data(peer, sender, bus, topic, headers, message)[source]¶

configure(configuration)[source]¶

Optional, may be implemented by a concrete implementation to add support for the configuration store. Values should be stored in this function only.

The process thread is stopped before this is called if it is running. It is started afterwards.

historian_setup is called after this is called.

historian_setup()[source]¶: Optional setup routine, run in the processing thread before main processing loop starts. Gives the Historian a chance to setup connections in the publishing thread.

historian_teardown()[source]¶: Optional teardown routine, run in the processing thread if the main processing loop is stopped. This happened whenever a new configuration arrives from the config store.

publish_to_historian(to_publish_list)[source]¶

Main publishing method for historian Agents.

Parameters: to_publish_list (list) – List of records

to_publish_list takes the following form:

[
    {
        'timestamp': timestamp1.replace(tzinfo=pytz.UTC),
        'source': 'scrape',
        'topic': "pnnl/isb1/hvac1/thermostat",
        'value': 73.0,
        'meta': {"units": "F", "tz": "UTC", "type": "float"}
    },
    {
        'timestamp': timestamp2.replace(tzinfo=pytz.UTC),
        'source': 'scrape',
        'topic': "pnnl/isb1/hvac1/temperature",
        'value': 74.1,
        'meta': {"units": "F", "tz": "UTC", "type": "float"}
    },
    ...
]

The contents of meta is not consistent. The keys in the meta data values can be different and can change along with the values of the meta data. It is safe to assume that the most recent value of the “meta” dictionary are the only values that are relevant. This is the way the cache treats meta data.

Once one or more records are published either BaseHistorianAgent.report_all_handled() or BaseHistorianAgent.report_handled() must be called to report records as being published.

timestamp()[source]¶

forwarder.agent.historian(config_path, **kwargs)[source]¶

forwarder.agent.main(argv=['/home/docs/checkouts/readthedocs.org/user_builds/volttron/envs/releases-8.1.1/lib/python3.6/site-packages/sphinx/__main__.py', '-T', '-b', 'readthedocssinglehtmllocalmedia', '-d', '_build/doctrees', '-D', 'language=en', '.', '_build/localmedia'])[source]¶: Main method called by the aip.

Forward Historian¶

The Forward Historian is used to send data from one instance of VOLTTRON to another. This agents primary purpose is to allow the target instance's pubsub bus to simulate data coming from a real device. If the target instance becomes unavailable or one of the "required agents" becomes unavailable then the cache of this agent will build up until it reaches it's maximum capacity or the instance and agents come back online.

The Forward Historian now uses the configuration store for storing its configurations. This allows dynamic updating of configuration without having to rebuild the agent.

FAQ /Notes¶

By default the Forward Historian adds an X-Forwarded and X-Forwarded-From header to the forwarded message. The X-Forwarded-From uses the instance-name of the platform (ip address:port by default).

Configuration Options¶

The following JSON configuration file shows all the options currently supported by the ForwardHistorian agent.

{
    # destination-serverkey
    #   The destination instance's publickey. Required if the
    #   destination-vip-address has not been added to the known-host file.
    #   See vctl auth --help for all instance security options.
    #
    #   This can be retrieved either through the command:
    #       vctl auth serverkey
    #   Or if the web is enabled on the destination through the browser at:
    #       http(s)://hostaddress:port/discovery/
    "destination-serverkey": null,

    # destination-vip-address - REQUIRED
    #   Address of the target platform.
    #   Examples:
    #       "destination-vip": "ipc://@/home/volttron/.volttron/run/vip.socket"
    #       "destination-vip": "tcp://127.0.0.1:22916"
    "destination-vip": "tcp://<ip address>:<port>"

    # required_target_agents
    #   Allows checking on the remote instance to verify peer identtites
    #   are connected before publishing.
    #
    #   Example:
    #       Require the platform.historian agent to be present on the
    #       destination instance before publishing.
    #       "required_target_agent" ["platform.historian"]
    "required_target_agents": [],

    # capture_device_data
    #   This is True by default and allows the Forwarder to forward
    #   data published from the device topic
    "capture_device_data": true,

    # capture_analysis_data
    #   This is True by default and allows the Forwarder to forward
    #   data published from the device topic
    "capture_analysis_data": true,

    # capture_log_data
    #   This is True by default and allows the Forwarder to forward
    #   data published from the datalogger topic
    "capture_log_data": true,

    # capture_record_data
    #   This is True by default and allows the Forwarder to forward
    #   data published from the record topic
    "capture_record_data": true,

    # custom_topic_list
    #   Unlike other historians, the forward historian can re-publish from
    #   any topic.  The custom_topic_list is prefixes to subscribe to on
    #   the local bus and forward to the destination instance.
    "custom_topic_list": ["actuator", "alert"],

    # cache_only
    #   Allows one to put the forward historian in a cache only mode so that
    #   data is backed up while doing operations on the destination
    #   instance.
    #
    #   Setting this to true will start cache to backup and not attempt
    #   to publish to the destination instance.
    "cache_only": false,

    # topic_replace_list - Deprecated in favor of retrieving the list of
    #   replacements from the VCP on the current instance.
    "topic_replace_list": [
        #{"from": "FromString", "to": "ToString"}
    ],

    # Publish a message to the log after a certain number of "successful"
    # publishes.  To disable the message to not print anything set the
    # count to 0.
    #
    # Note "successful" means that it was removed from the backup cache.
    "message_publish_count": 10000

}

MQTTHistorian¶

mqtt_historian package¶

mqtt_historian.agent module¶

class mqtt_historian.agent.MQTTHistorian(connection, **kwargs)[source]¶

Bases: volttron.platform.agent.base_historian.BaseHistorian

This historian publishes data to a MQTT Broker.

publish_to_historian(to_publish_list)[source]¶

Main publishing method for historian Agents.

Parameters: to_publish_list (list) – List of records

to_publish_list takes the following form:

[
    {
        'timestamp': timestamp1.replace(tzinfo=pytz.UTC),
        'source': 'scrape',
        'topic': "pnnl/isb1/hvac1/thermostat",
        'value': 73.0,
        'meta': {"units": "F", "tz": "UTC", "type": "float"}
    },
    {
        'timestamp': timestamp2.replace(tzinfo=pytz.UTC),
        'source': 'scrape',
        'topic': "pnnl/isb1/hvac1/temperature",
        'value': 74.1,
        'meta': {"units": "F", "tz": "UTC", "type": "float"}
    },
    ...
]

The contents of meta is not consistent. The keys in the meta data values can be different and can change along with the values of the meta data. It is safe to assume that the most recent value of the “meta” dictionary are the only values that are relevant. This is the way the cache treats meta data.

Once one or more records are published either BaseHistorianAgent.report_all_handled() or BaseHistorianAgent.report_handled() must be called to report records as being published.

timestamp()[source]¶

mqtt_historian.agent.historian(config_path, **kwargs)[source]¶

mqtt_historian.agent.main(argv=['/home/docs/checkouts/readthedocs.org/user_builds/volttron/envs/releases-8.1.1/lib/python3.6/site-packages/sphinx/__main__.py', '-T', '-b', 'readthedocssinglehtmllocalmedia', '-d', '_build/doctrees', '-D', 'language=en', '.', '_build/localmedia'])[source]¶

mqttlistener module¶

mqttlistener.listen(client, userdata, message)[source]¶

MQTT Historian¶

Overview¶

The MQTT Historian agent publishes data to an MQTT broker.

The mqttlistener.py script will connect to the broker and print all messages.

Dependencies¶

The Paho MQTT library from Eclipse is needed for the agent and can be installed with:

pip install paho-mqtt

The Mosquitto MQTT broker may be useful for testing and can be installed with

apt-get install mosquitto

Configuration¶

The following is an example configuration file:

{
    "connection: {
        # Optional backup limit in gigabytes. Default is no backup limit.
        # "backup_storage_limit_gb": null,

        # Quality of service level for MQTT publishes. Default is 0.
        # "mqtt_qos": 0,

        # Set messages to be retained. Default is False
        # "mqtt_retain": false,

        # Address of broker to connect to. Default is localhost.
        "mqtt_hostname": "localhost",

        # Port on broker accepting connections. Default is 1883
        "mqtt_port": 1883

        # If a client id is not provided one will be generated by paho-mqtt.
        # Default is an empty string.
        # "mqtt_client_id": "",

        # Keepalive timeout for the client. Default is 60 seconds
        # "mqtt_keepalive": 60,

        # Optional will is published when the client disconnects. Default is None.
        # If used then QOS defaults to 0 and retain defaults to False.
        # "mqtt_will": {
        #     "topic": "<topic>",
        #     "payload":"<payload">,
        #     "qos":<qos>,
        #     "retain":<retain>
        # },

        # MQTT authentication info. Defaults to None.
        # "mqtt_auth": {
        #    "username": "<username>",
        #    "password": "<password>"
        # },

        # MQTT TLS parameters. If used then CA Certs is required. Otherwise the
        # default is None.
        # "mqtt_tls": {
        #     "ca_certs":"<ca_certs>",
        #     "certfile":"<certfile>",
        #     "keyfile":"<keyfile>",
        #     "tls_version":"<tls_version>",
        #     "ciphers":"<ciphers">
        # }

        # Protocol versions MQTTv311 and MQTTv31 are supported. Default is MQTTv311.
        # "mqtt_protocol": "MQTTv311"
    }
}

MongodbTaggingService¶

mongotagging package¶

mongotagging.tagging module¶

class mongotagging.tagging.MongodbTaggingService(connection, table_prefix=None, **kwargs)[source]¶

Bases: volttron.platform.agent.base_tagging.BaseTaggingService

This is a tagging service agent that writes data to a Mongo database. For instance with large amount of tags and frequent tag queries, a NOSQL database such as Mongodb would provide better efficiency than SQLite.

insert_topic_tags(tags, update_version=False)[source]¶

Add tags to multiple topics.

Parameters

tags (dict) –
dictionary object or file containing the topic and the tag details. dictionary object or the file content should be of the format:
```
<topic_name or prefix or topic_name pattern>: {<valid
tag>:<value>, ... }, ... }
```
update_version (bool) – True/False. Default to False. If set to True and if any of the tags update an existing tag value the older value would be preserved as part of tag version history. Note: this feature is not implemented in the current version of sqlite and mongodb tagging service.

load_tag_refs()[source]¶: Called right after setup to load a dictionary of reference tags and its corresponding parent tag. Implementing methods should load self.tag_refs with tag and parent tag information

load_valid_tags()[source]¶: Called right after setup to load a dictionary of valid tags. It should load self.valid_tags with tag and type information

query_categories(include_description=False, skip=0, count=None, order='FIRST_TO_LAST')[source]¶

Get the available list tag categories. category can have multiple tags and tags could belong to multiple categories

Parameters

include_description (bool) – indicate if result should include available description for categories returned
skip (int) – number of tags to skip. usually used with order
count (int) – limit on the number of tags to return
order (str) – order of result - “FIRST_TO_LAST” or “LAST_TO_FIRST”

Returns

list of category names if include_description is False, list of (category name, description) if include_description is True

Return type

query_tags_by_category(category, include_kind=False, include_description=False, skip=0, count=None, order='FIRST_TO_LAST')[source]¶

Get the list of tags for a given category name. category can have multiple tags and tags could belong to multiple categories

Parameters

category (str) – name of the category for which associated tags should be returned
include_kind (bool) – indicate if result should include the kind/datatype for tags returned
include_description (bool) – indicate if result should include available description for tags returned
skip (int) – number of tags to skip. usually used with order
count (int) – limit on the number of tags to return
order (str) – order of result - “FIRST_TO_LAST” or “LAST_TO_FIRST”

Returns

Will return one of the following

list of tag names
list of (tags, its data type/kind) if include_kind is True
list of (tags, description) if include_description is True
list of (tags, its data type/kind, description) if include_kind is True and include_description is true

Return type

query_tags_by_topic(topic_prefix, include_kind=False, include_description=False, skip=0, count=None, order='FIRST_TO_LAST')[source]¶

Get the list of tags for a given topic prefix or name.

Parameters

topic_prefix (str) – topic_prefix for which associated tags should be returned
include_kind (bool) – indicate if result should include the kind/datatype for tags returned
include_description (bool) – indicate if result should include available description for tags returned
skip (int) – number of tags to skip. usually used with order
count (int) – limit on the number of tags to return
order (str) – order of result - “FIRST_TO_LAST” or “LAST_TO_FIRST”

Returns

Will return one of the following

list of (tag name, value)
list of (tag name, value, data type/kind) if include_kind is True
list of (tag name, value, description) if include_description is True
list of (tags, value, data type/kind, description) if include_kind is True and include_description is true

Return type

query_topics_by_tags(ast, skip=0, count=None, order=None)[source]¶

Get list of topic names and topic name prefixes based on query condition. Query condition is passed as an abstract syntax tree.

Parameters

ast (tuple) –
Abstract syntax tree that represents conditional statement to be used for matching tags. The abstract syntax tree represents query condition that is created using the following specification

Query condition is a boolean expression that contains one or more query conditions combined together with an “AND” or “OR”. Query conditions can be grouped together using parenthesis. Each condition in the expression should conform to one of the following format:
1. <tag name/ parent.tag_name> <binary_operator> <value>
2. <tag name/ parent.tag_name>
3. <tag name/ parent.tag_name> LIKE <regular expression within single quotes
4. the word NOT can be prefixed before any of the above three to negate the condition.
5. expressions can be grouped with parenthesis. For example
  condition="(tag1 = 1 or tag1 = 2) and (tag2 < '' and tag2 > '') and tag3 and (tag4 LIKE '^a.*b$')" condition="NOT (tag5='US' OR tag5='UK') AND NOT tag3 AND NOT (tag4 LIKE 'a.*')" condition="campusRef.geoPostalCode='20500' and equip and boiler"
skip (int) – number of tags to skip. usually used with order
count (int) – limit on the number of tags to return
order (str) – order of result - “FIRST_TO_LAST” or “LAST_TO_FIRST”

Returns

list of topics/topic_prefix that match the given query conditions

Return type

setup()[source]¶: Called on start of agent Method to establish database connection, do any initial bootstrap necessary. Example - load master list of tags, units, categories etc. into data store/memory

mongotagging.tagging.main(argv=['/home/docs/checkouts/readthedocs.org/user_builds/volttron/envs/releases-8.1.1/lib/python3.6/site-packages/sphinx/__main__.py', '-T', '-b', 'readthedocssinglehtmllocalmedia', '-d', '_build/doctrees', '-D', 'language=en', '.', '_build/localmedia'])[source]¶

Main entry point for the agent.

Parameters: argv –
Returns

mongotagging.tagging.tagging_service(config_path, **kwargs)[source]¶

This method is called by the tagging.main() to parse the passed config file or configuration dictionary object, validate the configuration entries, and create an instance of MongodbTaggingService

Parameters

config_path – could be a path to a configuration file or can be a dictionary object
kwargs – additional keyword arguments if any

Returns

an instance of tagging.MongodbTaggingService

Mongodb Tagging Service¶

Mongodb tagging service provide APIs to tag both topic names(device points) and topic name prefixes (campus, building, unit/equipment, sub unit) and then query for relevant topics based on saved tag names and values. This agent stores the tags in a mongodb database.

Tags used by this agent are not user defined. They have to be pre-defined in a resource file at volttron_data/tagging_resources. The agent validates against this predefined list of tags every time user add tags to topics. Tags can be added to one topic at a time or multiple topics by using a topic name pattern(regular expression). This agent uses tags from project haystack. and adds a few custom tags for campus and VOLTTRON point name.

Each tag has an associated value and users can query for topic names based tags and its values using a simplified sql-like query string. Queries can specify tag names with values or tags without values for boolean tags(markers). Queries can combine multiple conditions with keyword AND and OR, and use the keyword NOT to negate a conditions.

Requirements¶

This historian requires a mongodb connector installed in your activated volttron environment to talk to mongodb. Please execute the following from an activated shell in order to install it.

pip install pymongo

Dependencies and Limitations¶

When adding tags to topics, this agent calls the platform.historian's get_topic_list and hence requires the platform.historian to be running but it doesn't require the historian to use any specific database. It does not require platform.historian to be running for using its query APIs.
Resource files that provides the list of valid tags is mandatory and should be in volttron_data/tagging_reosurces/tags.csv
Tagging service only provides APIs query for topic names based on tags. Once the list of topic names is retrieved, users should use the historian APIs to get the data corresponding to those topics.
Current version of tagging service does not support versioning of tag/values. When tags values set using tagging service APIs update/overwrite any existing tag entries in the database

Configuration Options¶

The following JSON configuration file shows all the options currently supported by this agent.

{
    "connection": {
        "type": "mongodb",
        "params": {
            "host": "localhost",
            "port": 27017,
            "database": "test_historian",
            "user": "username for this db. should have read write access",
            "passwd": "password for this db"
        }
    },
    # optional. Specify if collections created for tagging should have names
    # starting with a specific prefix <given prefix>_<collection_name>
    "table_prefix":"volttron",

    # optional. Specify if you want tagging service to query the historian
    # with this vip identity. defaults to platform.historian
    "historian_vip_identity": "mongo.historian"
}

PlatformDriverAgent¶

platform_driver package¶

Subpackages¶

platform_driver.interfaces package¶

Driver Development¶

New drivers are implemented by subclassing BaseInterface.

While it is possible to create an Agent which handles communication with a new device it will miss out on the benefits of creating a proper interface for the Platform Driver Agent.

Creating an Interface for a device allows users of the device to automatically benefit from the following platform features:

Existing Agents can interact with the device via the Actuator Agent without any code changes.
Configuration follows the standard form of other devices. Existing and future tools
for configuring devices on the platform will work with the new device driver.
Historians will automatically capture data published by the new device driver.
Device data can be graphed in VOLTTRON Central in real time.
If the device can receive a heartbeat signal the driver framework can be configured to
automatically send a heartbeat signal.
When the configuration store feature is rolled out the device can by dynamically configured
through the platform.

Creating a New Interface¶

To create a new device driver create a new module in the PlatformDriverAgent.platform_driver.interfaces package. The name of this module will be the name to use in the “driver_type” setting in a driver configuration file in order to load the new driver.

In the new module create a subclass of BaseInterface called Interface.

The Interface class must implement the following methods:

BaseInterface.configure()
BaseInterface.set_point()
BaseInterface.get_point()
BaseInterface.scrape_all()

These methods are required but can be implemented using the BasicRevert mixin.

BaseInterface.revert_point()
BaseInterface.revert_all()

Each point on the device must be represented by an instance of the BaseRegister. Create one or more subclasses of BaseRegister as needed to represent the points on a device.

Interface Configuration and Startup¶

When processing a driver configuration file the Platform Driver Agent will use the “driver_type” setting to automatically find and load the appropriate Interface class for the desired driver.

After loading the class the Platform Driver Agent will call BaseInterface.configure() with the contents of the “driver_config” section of the driver configuration file parsed into a python dictionary and the contents of the file referenced in “registry_config” entry.

BaseInterface.configure() must setup register representations of all points on a device by creating instances of BaseRegister (or a subclass) and adding them to the Interface with BaseInterface.insert_register().

After calling BaseInterface.configure() the Platform Driver Agent will use the created registers to create meta data for each point on the device.

Device Scraping¶

The work scheduling and publish periodic device scrapes is handled by the Platform Driver Agent. When a scrape starts the Platform Driver Agent calls the BaseInterface.scrape_all(). It will take the results of the call and attach meta data and and publish as needed.

Device Interaction¶

Requests to interact with the device via any method supported by the platform are routed to the correct Interface instance by the Platform Driver Agent.

Most commands originate from RPC calls to the Actuator Agent and are forwarded to the Platform Driver Agent.

A command to set the value of a point on a device results in a call to
BaseInterface.set_point().
A request for the current value of a point on a device results in a call to
BaseInterface.get_point().
A request to revert a point on a device to its default state results in a call to
BaseInterface.revert_point().
A request to revert an entire device to its default state results in a call to
BaseInterface.revert_all().

Registers¶

The Platform Driver Agent uses the BaseInterface.get_register_names() and BaseInterface.get_register_by_name() methods to get registers to setup meta data.

This means that its a requirement to use the BaseRegister class to store information about points on a devices.

Using the BasicRevert Mixin¶

If the device protocol has no support for reverting to a default state an Interface this functionality can be implemented with the BasicRevert mixin.

When using the BasicRevert mixin you must specify it first in the list of parent classes, otherwise it won’t Python won’t detect that the BaseInterface.revert_point() and BaseInterface.revert_all() have been implemented.

If desired the BasicRevert.set_default() can be used by the Interface class to set values for each point to revert to.

class platform_driver.interfaces.BaseInterface(vip=None, core=None, **kwargs)[source]¶

Bases: object

Main class for implementing support for new devices.

All interfaces must subclass this.

Parameters

vip – A reference to the PlatformDriverAgent vip subsystem.
core – A reference to the parent driver agent’s core subsystem.

build_register_map()[source]¶

abstract configure(config_dict, registry_config_str)[source]¶

Configures the Interface for the specific instance of a device.

Parameters

config_dict (dict) – The “driver_config” section of the driver configuration file.
registry_config_str (str) – The contents of the registry configuration file.

This method must setup register representations of all points on a device by creating instances of BaseRegister (or a subclass) and adding them to the Interface with BaseInterface.insert_register().

get_multiple_points(path, point_names, **kwargs)[source]¶

Read multiple points from the interface.

Parameters

path (str) – Device path
point_names ([str]) – Names of points to retrieve
kwargs (dict) – Any interface specific parameters

Returns

Tuple of dictionaries to results and any errors

Return type

(dict, dict)

abstract get_point(point_name, **kwargs)[source]¶

Get the current value for the point name given.

Parameters

point_name (str) – Name of the point to retrieve.
kwargs – Any interface specific parameters.

Returns

Point value

get_register_by_name(name)[source]¶

Get a register by it’s point name.

Parameters: name (str) – Point name of register.
Returns: An instance of BaseRegister
Return type: BaseRegister

get_register_names()[source]¶: Get a list of register names. :return: List of names :rtype: list

get_register_names_view()[source]¶: Get a dictview of register names. :return: Dictview of names :rtype: dictview

get_registers_by_type(reg_type, read_only)[source]¶

Get a list of registers by type. Useful for an Interface that needs to categorize registers by type when doing a scrape.

Parameters

reg_type (str) – Register type. Either “bit” or “byte”.
read_only (bool) – Specify if the desired registers are read only.

Returns

An list of BaseRegister instances.

Return type

insert_register(register)[source]¶

Inserts a register into the Interface.

Parameters: register (BaseRegister) – Register to add to the interface.

abstract revert_all(**kwargs)[source]¶

Revert entire device to it’s default state

Parameters: kwargs – Any interface specific parameters.

abstract revert_point(point_name, **kwargs)[source]¶

Revert point to it’s default state.

Parameters: kwargs – Any interface specific parameters.

abstract scrape_all()[source]¶

Method the Platform Driver Agent calls to get the current state of a device for publication.

Returns: Point names to values for device.
Return type: dict

set_multiple_points(path, point_names_values, **kwargs)[source]¶

Set multiple points on the interface.

Parameters

path (str) – Device path
point_names_values – Point names and values to be set to.
kwargs (dict) – Any interface specific parameters

Returns

Dictionary of points to any exceptions raised

Return type

dict

abstract set_point(point_name, value, **kwargs)[source]¶

Set the current value for the point name given.

Implementations of this method should make a reasonable effort to return the actual value the point was set to. Some protocols/devices make this difficult. (I’m looking at you BACnet) In these cases it is acceptable to return the value that was requested if no error occurs.

Parameters

point_name (str) – Name of the point to retrieve.
value – Value to set the point to.
kwargs – Any interface specific parameters.

Returns

Actual point value set.

class platform_driver.interfaces.BaseRegister(register_type, read_only, pointName, units, description='')[source]¶

Bases: object

Class for containing information about a point on a device. Should be extended to support the device protocol to be supported.

The member variable python_type should be overridden with the equivalent python type object. Defaults to int. This is used to generate meta data.

Parameters

register_type (str) – Type of the register. Either “bit” or “byte”. Usually “byte”.
read_only (bool) – Specify if the point can be written to.
pointName (str) – Name of the register.
units (str) – Units of the value of the register.
description (str) – Description of the register.

The Platform Driver Agent will use BaseRegister.get_units() to populate metadata for publishing. When instantiating register instances be sure to provide a useful string for the units argument.

get_description()[source]¶

Returns: Register description
Return type: str

get_register_python_type()[source]¶

Returns: The python type of the register.
Return type: type

get_register_type()[source]¶

Returns: (register_type, read_only)
Return type: tuple

get_units()[source]¶

Returns: Register units
Return type: str

class platform_driver.interfaces.BasicRevert(**kwargs)[source]¶

Bases: object

A mixin that implements the BaseInterface.revert_all() and BaseInterface.revert_point() methods on an Interface.

It works by tracking change to all writable points until a set_point call is made. When this happens the point is marked dirty and the previous value is remembered. When a point is reverted via either a revert_all or revert_point call the dirty values are set back to the clean value using the BasicRevert._set_point() method.

As it must hook into the setting and scraping of points it implements the BaseInterface.scrape_all() and BaseInterface.set_point() methods. It then adds BasicRevert._set_point() and BasicRevert._scrape_all() to the abstract interface. An existing interface that wants to use this class can simply mix it in and rename it’s set_point and scrape_all methods to _set_point and _scrape_all respectively.

An BaseInterface may also override the detected clean value with its own value to revert to by calling BasicRevert.set_default(). While default values can be set anytime they should be set in the BaseInterface.configure() call.

revert_all(**kwargs)[source]¶

Implementation of BaseInterface.revert_all()

Calls BasicRevert._set_point() with point_name and the value to revert the point to for every writable point on a device.

Currently **kwargs is ignored.

revert_point(point_name, **kwargs)[source]¶

Implementation of BaseInterface.revert_point()

Revert point to its default state.

Calls BasicRevert._set_point() with point_name and the value to revert the point to.

Parameters: point_name (str) – Name of the point to revert.

Currently **kwargs is ignored.

scrape_all()[source]¶: Implementation of BaseInterface.scrape_all()

set_default(point, value)[source]¶

Set the value to revert a point to.

Parameters

point (str) – name of point to set.
value – value to set the point to.

set_point(point_name, value)[source]¶

Implementation of BaseInterface.set_point()

Passes arguments through to BasicRevert._set_point()

exception platform_driver.interfaces.DriverInterfaceError[source]¶: Bases: Exception

class platform_driver.interfaces.RevertTracker[source]¶

Bases: object

A helper class for tracking the state of writable points on a device.

clear_dirty_point(point)[source]¶

Clears the dirty flag on a point.

Parameters: point (str) – Name of dirty point flag to clear.

get_all_revert_values()[source]¶

Returns a dict of points to revert values.

If no default is set use the clean value, otherwise returns the default value.

If no default value is set and a no clean values have been submitted a point value will be an instance of DriverInterfaceError.

Parameters: point (str) – Name of point to get.
Returns: Values to revert to.
Return type: dict

get_revert_value(point)[source]¶

Returns the clean value for a point if no default is set, otherwise returns the default value.

If no default value is set and a no clean values have been submitted raises DriverInterfaceError.

Parameters: point (str) – Name of point to get.
Returns: Value to revert to.

mark_dirty_point(point)[source]¶

Sets the dirty flag on a point.

Ignores points with a default value.

Parameters: point (str) – Name of point flag to dirty.

set_default(point, value)[source]¶

Set the value to revert a point to. Overrides any clean value detected.

Parameters

point (str) – name of point to set.
value – value to set the point to.

update_clean_values(points)[source]¶

Update all state of all the clean point values for a device.

If a point is marked dirty it will not be updated.

Parameters: points (dict) – dict of point names to values.

Subpackages¶

platform_driver.interfaces.chargepoint package¶

class platform_driver.interfaces.chargepoint.AlarmRegister(read_only, point_name, attribute_name, units, data_type, station_id, default_value=None, description='', port_number=None, username=None, timeout=0)[source]¶

Bases: platform_driver.interfaces.chargepoint.ChargepointRegister

Register designated for all attributes returned from the Chargepoint API getAlarms call.

Input parameters are the same as parent ChargepointRegister class.

Readable attributes: alarmType and alarmTime: Return the most recent alarm registered for the given station. If a port is defined for the register, only alarms ascribed to the port will be returned. If value is None, then there are no active alarms describing the station and/or port (depending on config).

Writeable attributes:

clearAlarms: Only accepts a write-value of 1 or True. This indicates that the Chargepoint station should be cleared of any alarms. If a point is defined for the register, only alarms ascribed to the port will be cleared. This value, when read, will always return None, as it does not exist as a returnable Chargepoint attribute.

attribute_list = ['alarmType', 'alarmTime', 'clearAlarms']¶

property value¶

writeable_list = ['clearAlarms']¶

class platform_driver.interfaces.chargepoint.ChargepointRegister(read_only, point_name, attribute_name, units, data_type, station_id, default_value=None, description='', port_number=None, username=None, timeout=0)[source]¶

Bases: platform_driver.interfaces.BasicRevert, platform_driver.interfaces.BaseInterface

Base class for any Chargepoint related register

Defines init-level operations for all Chargepoint registers. Also requires abstract get and set methods for value property.

Parameters

read_only – True = Read-only, False = Read/Write.
point_name – Volttron-given name of point.
attribute_name – Name used in Chargepoint API call. Needs to syntacticly match any value in class

‘attribute_list’ variables. :param units: Required by parent class. Not used by Chargepoint. :param data_type: Python type of register. Used to cast API call results. :param station_id: ID of Chargepoint Station register describes. :param default_value: Default value of register. :param description: Basic description of register. :param port_number: (Optional) Port number of Chargepoint Station register describes. Some registers describe port level granularity while others describe the Chargepoint Station as a whole. :param username: Username for Chargepoint API login

get_register(result, method, port_flag=True)[source]¶

Gets correct register from API response.

Parameters

result – API result from which to grab register value.
method – Name of Chargepoint API call that was made.
port_flag – Flag indicating whether or not Port-level parameters can be used. GetAlarms and

GetChargingSessionData methods use ports in their queries, but have a different reply structure than other API method calls.

Returns: Correct register value cast to appropriate python type. Returns None if there is an error.

read_only_check()[source]¶

static sanitize_output(data_type, value)[source]¶

abstract value(x)[source]¶

class platform_driver.interfaces.chargepoint.ChargingSessionRegister(read_only, point_name, attribute_name, units, data_type, station_id, default_value=None, description='', port_number=None, username=None, timeout=0)[source]¶

Bases: platform_driver.interfaces.chargepoint.ChargepointRegister

Register designated for all attributes returned from the Chargepoint API getChargingSessions call.

Input parameters are the same as parent ChargepointRegister class. No attribute in this register is writeable.

attribute_list = ['sessionID', 'startTime', 'endTime', 'Energy', 'rfidSerialNumber', 'driverAccountNumber', 'driverName']¶

property value¶

writeable_list = []¶

class platform_driver.interfaces.chargepoint.Interface(**kwargs)[source]¶

configure(config_dict, registry_config_str)[source]¶

Configure interface for driver.

References global CPService object and configures with username and password if not already configured.

Parameters

config_dict – Input from driver config.
registry_config_str – Input from csv file.

get_point(point_name)[source]¶

Get the current value for the point name given.

Parameters

point_name (str) – Name of the point to retrieve.
kwargs – Any interface specific parameters.

Returns

Point value

parse_config(config_dict, registry_config_str)[source]¶: Main method to parse the CSV registry config file.

class platform_driver.interfaces.chargepoint.LoadRegister(read_only, point_name, attribute_name, units, data_type, station_id, default_value=None, description='', port_number=None, username=None, timeout=0)[source]¶

Bases: platform_driver.interfaces.chargepoint.ChargepointRegister

Register designated for all attributes returned from the Chargepoint API getLoad call.

Input parameters are the same as parent ChargepointRegister class.

Writeable attributes (Note, if either allowedLoad or percentShed are set, the other will be set to None. In addition, shedState will be set to 1 or True):

allowedLoad: Amount of load to shed in an absolute value. Limits charging to x kW. percentShed: Percent of load to shed. Limits charging to x% of load. shedState: Only accepts a write-value of 0 or False. This indicates that the Chargepoint station should be cleared of any load shed constraints

attribute_list = ['portLoad', 'allowedLoad', 'percentShed', 'shedState']¶

property value¶

writeable_list = ['allowedLoad', 'percentShed', 'shedState']¶

class platform_driver.interfaces.chargepoint.StationRegister(read_only, point_name, attribute_name, units, data_type, station_id, default_value=None, description='', port_number=None, username=None, timeout=0)[source]¶

Bases: platform_driver.interfaces.chargepoint.ChargepointRegister

Register designated for all attributes returned from the Chargepoint API getStations call.

Input parameters are the same as parent ChargepointRegister class. No attribute in this register is writeable.

attribute_list = ['stationID', 'stationManufacturer', 'stationModel', 'portNumber', 'stationName', 'stationMacAddr', 'stationSerialNum', 'Address', 'City', 'State', 'Country', 'postalCode', 'Lat', 'Long', 'Level', 'Reservable', 'Mode', 'Voltage', 'Current', 'Power', 'numPorts', 'Type', 'startTime', 'endTime', 'minPrice', 'maxPrice', 'unitPricePerHour', 'unitPricePerSession', 'unitPricePerKWh', 'orgID', 'unitPriceForFirst', 'unitPricePerHourThereafter', 'sessionTime', 'Description', 'mainPhone', 'organizationName', 'sgID', 'sgName', 'currencyCode', 'Connector']¶

property value¶

writeable_list = []¶

class platform_driver.interfaces.chargepoint.StationRightsRegister(read_only, point_name, attribute_name, units, data_type, station_id, default_value=None, description='', port_number=None, username=None, timeout=0)[source]¶

Bases: platform_driver.interfaces.chargepoint.ChargepointRegister

Register designated for all attributes returned from the Chargepoint API getStationRights call.

Input parameters are the same as parent ChargepointRegister class. No attribute in this register is writeable.

Unlike any other ChargepointRegister subclasses, the stationRightsProfile is of type ‘dictionary.’ This calls the global method recursive_asdict, which takes the returned SUDS object and converts it, recursively, into a python dictionary. As such, this register does not go through the parent class get_register method to return its value.

attribute_list = ['stationRightsProfile']¶

property value¶

writeable_list = []¶

class platform_driver.interfaces.chargepoint.StationStatusRegister(read_only, point_name, attribute_name, units, data_type, station_id, default_value=None, description='', port_number=None, username=None, timeout=0)[source]¶

Bases: platform_driver.interfaces.chargepoint.ChargepointRegister

Register designated for all attributes returned from the Chargepoint API getStationStatus call.

Input parameters are the same as parent ChargepointRegister class. No attribute in this register is writeable.

attribute_list = ['Status', 'TimeStamp']¶

property value¶

writeable_list = []¶

platform_driver.interfaces.chargepoint.recursive_asdict(d)[source]¶

Convert Suds object into serializable format.

Credit goes to user plaes as found here: http://stackoverflow.com/questions/2412486/serializing-a-suds-object-in-python

platform_driver.interfaces.chargepoint.async_service module¶

This module is used to process asynchronous requests and cache results for later use. It was written to handle Web API calls to the Chargepoint service but could be used for any long-ish running, gevent friendly function calls.

A single queue is managed by the web_service() function. Requests are placed on the queue by client code, usually with a call to CPRequest.request(). The web_service() function records the request in a dictionary using the method signature (name + parameters). This dictionary maintains a set of AsyncResult objects, one for each request with the same signature.

After recording the request in the dictionary, the web_service() executes the request method in a short-lived greenlet (web_call()). The response is placed on the queue. When the web_service() encounters a response, it sets the values of all the AsyncResults waiting on that request, causing the client greenlets to ‘wake-up’ on an AsyncResult.wait().

The request and response is left in the dictionary until a configurable expiration time so that subsequent requests with the same signature can use the cached result if it has not expired. In this case, the AsyncResult is set immediately.

class platform_driver.interfaces.chargepoint.async_service.CPRequest(method, timeout, *args, **kwargs)[source]¶

Bases: object

Encapsulates a method to be called asynchronously.

The result is returned as AsyncResult. The request() classmethod is used to create a request, queue it to the web_service() and return an AsyncResult that the caller can wait() on.

is_request()[source]¶

key()[source]¶

classmethod request(method, timeout, *args, **kwargs)[source]¶

Generate a new request and put it on the web service queue.

Returns the requests AsyncResult instance which will be filled in after the request has been executed.

result()[source]¶

property timeout¶

class platform_driver.interfaces.chargepoint.async_service.CPResponse(key, response, client)[source]¶

Bases: object

A response to to a CPRequest invocation.

property client¶

is_request()[source]¶

key()[source]¶

response()[source]¶

class platform_driver.interfaces.chargepoint.async_service.CacheItem(cache_life)[source]¶

Bases: object

A cached request/response.

As responses come in, they are matched to the originating request and waiting_results are ‘set’. Subsequent requests with the same signature (key) are satisfied immediately, if not expired, by setting the async result on the incoming request.

property expiration¶

property request¶

property response¶

property waiting_results¶

platform_driver.interfaces.chargepoint.async_service.web_call(request, client)[source]¶

Wraps the request to be executed.

This is spawned as a greenlet and puts the request result on the queue.

platform_driver.interfaces.chargepoint.async_service.web_service()[source]¶

Cache/service request loop.

Reads items from the web_service_queue. It is intended to be spawned as a greenlet: that runs forever.

If the de-queued item is a CPRequest, the cache is checked for an existing response. If not found, the request is added to cache and a greenlet is spawned to complete the request.

If the de-queued item is a CPResponse, the item is found in cache and all waiting AsyncResults are set with the response. The response will stay in cache until expiration.

platform_driver.interfaces.chargepoint.credential_check module¶

platform_driver.interfaces.chargepoint.service module¶

exception platform_driver.interfaces.chargepoint.service.CPAPIException(response_code, response_text)[source]¶

Bases: Exception

Generic Chargepoint API Exception.

Parameters

response_code – Exception code.
response_text – Exception description.

class platform_driver.interfaces.chargepoint.service.CPAPIGetAlarmsResponse(response)[source]¶

Bases: platform_driver.interfaces.chargepoint.service.CPAPIResponse

alarmTime(port=None)[source]¶

alarmType(port=None)[source]¶

property alarms¶

clearAlarms(port=None)[source]¶

class platform_driver.interfaces.chargepoint.service.CPAPIGetChargingSessionsResponse(response)[source]¶

Bases: platform_driver.interfaces.chargepoint.service.CPAPIResponse

Energy(port=None)[source]¶

property charging_sessions¶

driverAccountNumber(port=None)[source]¶

driverName(port=None)[source]¶

endTime(port=None)[source]¶

rfidSerialNumber(port=None)[source]¶

sessionID(port=None)[source]¶

startTime(port=None)[source]¶

class platform_driver.interfaces.chargepoint.service.CPAPIGetLoadResponse(response)[source]¶

Bases: platform_driver.interfaces.chargepoint.service.CPAPIResponse

allowedLoad(port=None)[source]¶

percentShed(port=None)[source]¶

portLoad(port=None)[source]¶

shedState(port=None)[source]¶

stationLoad(port=None)[source]¶

property station_data¶

class platform_driver.interfaces.chargepoint.service.CPAPIGetStationRightsResponse(response)[source]¶

Bases: platform_driver.interfaces.chargepoint.service.CPAPIResponse

property rights¶

class platform_driver.interfaces.chargepoint.service.CPAPIGetStationStatusResponse(response)[source]¶

Bases: platform_driver.interfaces.chargepoint.service.CPAPIResponse

Status(port=None)[source]¶

TimeStamp(port=None)[source]¶

property status¶

class platform_driver.interfaces.chargepoint.service.CPAPIGetStationsResponse(response)[source]¶

Bases: platform_driver.interfaces.chargepoint.service.CPAPIResponse

Address(port=None)[source]¶

City(port=None)[source]¶

Connector(port=None)[source]¶

Country(port=None)[source]¶

Current(port=None)[source]¶

Description(port=None)[source]¶

Lat(port=None)[source]¶

Level(port=None)[source]¶

Long(port=None)[source]¶

Mode(port=None)[source]¶

Power(port=None)[source]¶

Reservable(port=None)[source]¶

State(port=None)[source]¶

Type(port=None)[source]¶

Voltage(port=None)[source]¶

currencyCode(port=None)[source]¶

endTime(port=None)[source]¶

mainPhone(port=None)[source]¶

maxPrice(port=None)[source]¶

minPrice(port=None)[source]¶

numPorts(port=None)[source]¶

orgID(port=None)[source]¶

organizationName(port=None)[source]¶

portNumber(port=None)[source]¶

postalCode(port=None)[source]¶

static pricing_helper(attribute, station)[source]¶

sessionTime(port=None)[source]¶

sgID(port=None)[source]¶

sgName(port=None)[source]¶

startTime(port=None)[source]¶

stationID(port=None)[source]¶

stationMacAddr(port=None)[source]¶

stationManufacturer(port=None)[source]¶

stationModel(port=None)[source]¶

stationName(port=None)[source]¶

stationSerialNum(port=None)[source]¶

property stations¶

unitPriceForFirst(port=None)[source]¶

unitPricePerHour(port=None)[source]¶

unitPricePerHourThereafter(port=None)[source]¶

unitPricePerKWh(port=None)[source]¶

unitPricePerSession(port=None)[source]¶

class platform_driver.interfaces.chargepoint.service.CPAPIResponse(response)[source]¶

Bases: object

Response object describing a chargepoint API call

Parameters: response – SOAP object containing the API response
Property responseCode: API response Code. ‘100’ is a successful call.
Property responseText: Short description of the designation for the API call
Method is_successful: Returns Boolean value checking whether or not responseCode is set to ‘100.’

static check_output(attribute, parent_dict)[source]¶: Helper method for get_port_value

static get_attr_from_response(name_string, response, portNum=None)[source]¶

static get_port_value(port_number, data, attribute)[source]¶

Returns data for a given port

Parameters

port_number – Number of the port to access.
data – Larger data structure to scan for Port data.
attribute – Which piece of Port data to return.

Return port_data

Accessed data for given port number and attribute. Else None.

static is_not_found(name)[source]¶

is_successful()[source]¶

property responseCode¶

property responseText¶

class platform_driver.interfaces.chargepoint.service.CPGroupManager(cps, group, stations)[source]¶

Bases: object

Manger for a Chargepoint group and its stations.

Parameters

cps – Chargepoint Service object.
group – CPStationGroup object.
stations – List of CPStation objects belonging to the CPStationGroup.

refreshGroupStationData()[source]¶: For all stations belonging to group, refresh load data.

class platform_driver.interfaces.chargepoint.service.CPOrganization(cpn_id, organization_id, name='Unknown')[source]¶

Bases: object

Represents an organization within the ChargePoint network.

Parameters

cpn_id – Chargepoint Network ID.
organization_id – Chargepoint Org ID.
name –

orgID()[source]¶

Returns Chargepoint orgID

Return orgID: ‘cpn_id:organization_id’.

class platform_driver.interfaces.chargepoint.service.CPPort(data=None)[source]¶

Bases: object

property connector¶

property current¶

property level¶

property portNumber¶

property power¶

property voltage¶

class platform_driver.interfaces.chargepoint.service.CPService(username=None, password=None)[source]¶

Bases: object

Python wrapper around the Chargepoint WebServices API.

Current Version: 5.0 Docs: ChargePoint_Web_Services_API_Guide_Ver4.1_Rev5.pdf

clearAlarms(**kwargs)[source]¶

Clears the Alarms of given group or station based on given query parameters.

Parameters

**kwargs –

any top-level kwarg in the following query. Most frequently queried via stationID.

Query:

(clearAlarmsSearchQuery){: orgID = None organizationName = None stationID = None stationName = None sgID = None sgName = None startTime = None endTime = None portNumber = None alarmType = None clearReason = None

}

:returns SOAP reply object. If successful, there will be a responseCode of ‘100’.

clearShedState(**kwargs)[source]¶

Clears the shed state of given group or station.

Parameters

(as kwarg) (stationID) – groupID of stations to clear.
(as kwarg) – (Optional) ID of individual station to clear. If this is used, only that station will have

a cleared shed state, even with the use of sgID.

:returns SOAP reply object. If successful, there will be a responseCode of ‘100’.

dump_methods_and_datatypes()[source]¶: Debugging tool. Prints out the SOAP methods and datatypes.

getAlarms(**kwargs)[source]¶

Returns any active alarms matching the search query.

Parameters

**kwargs –

any top-level kwarg in the following query. Most frequently queried via stationID.

Query:

(getAlarmsSearchQuery){: orgID = None organizationName = None stationID = None stationName = None sgID = None sgName = None startTime = None endTime = None portNumber = None startRecord = None numTransactions = None

}

Reply:

(reply){

responseCode = “100” responseText = “API input request executed successfully.” Alarms[] =

(oalarms){
stationID = “1:00001” stationName = “CHARGEPOINT / MAIN 001” stationModel = “CT2100-HD-CCR” orgID = “1:ORG00001” organizationName = “My Organization Name” stationManufacturer = Chargepoint stationSerialNum = “000000000001” portNumber = None alarmType = “Reachable” alarmTime = 2016-12-12 12:34:56+00:00 recordNumber = 1

moreFlag = 0

}

getCPNInstances()[source]¶

Returns ChargePoint network objects.

Generally not useful expect that it returns the all important CPNID which is needed to construct the orgID, described as CPNID:CompanyID.

For North America, the CPNID is ‘1’.

getChargingSessionData(**kwargs)[source]¶

Returns a list of charging sessions based on search query.

Returns a list of Charging Sessions. If there are more than 100 records returned by the query, there will be a MoreFlag return value of 1.

Parameters

**kwargs –

any top-level kwarg in the following query. Most frequently queried via stationID.

Query:

(sessionSearchdata){

stationID = None sessionID = None stationName = None Address = None City = None State = None Country = None postalCode = None Proximity = None proximityUnit = None fromTimeStamp = None toTimeStamp = None startRecord = None Geo =

(geoData){
Lat = None Long = None

}

}

Reply:

(reply){

responseCode = “100” responseText = “API input request executed successfully.” ChargingSessionData[] =

(sessionSearchResultdata){
stationID = “1:00001” stationName = “CHARGEPOINT / MAIN 001” portNumber = “2” Address = “1 Main St, Oakland, California, 94607, United States” City = “Oakland” State = “California” Country = “United States” postalCode = “94607” sessionID = 12345678 Energy = 12.345678 startTime = 2016-01-01 01:01:01+00:00 endTime = 2016-01-01 12:12:02+00:00 userID = “123456” recordNumber = 1 credentialID = “123456789”

moreFlag = 0

}

getLoad(**kwargs)[source]¶

Returns current load of charging station sessions.

Returns Load on Charging stations/groups as defined by input query. If sgID is not included, many group level parameters will be returned as ‘None.’

Parameters

**kwargs –

sgID or stationID.

Reply:

(reply){

responseCode = “100” responseText = “API input request executed successfully.” numStations = None groupName = None sgLoad = None stationData[] =

(stationloaddata){
stationID = “1:000013” stationName = “CHARGEPOINT / MAIN 001” Address = “1 Main St, Oakland, California, 94607, United States” stationLoad = 1.1 Port[] =

(stationPortData){
portNumber = “1” userID = None credentialID = None shedState = 0 portLoad = 0.0 allowedLoad = 0.0 percentShed = “0”

}, (stationPortData){

portNumber = “2” userID = “123456” credentialID = “123456789” shedState = 0 portLoad = 1.1 allowedLoad = 0.0 percentShed = “0”

},

}

getOrgsAndStationGroups(**kwargs)[source]¶

Returns orgnaizations and their station groups.

Get all organization and station group identifiers.

Parameters

**kwargs –

any top-level kwarg in the following query. Most frequently queried via stationID.

Query:

(getOrgsAndStationGroupsSearchQuery){: orgID = None organizationName = None sgID = None sgName = None

}

Reply:

(reply){

responseCode = “100” responseText = “API input request executed successfully.” orgData[] =

(ohostdata){
orgID = “1:ORG00001” organizationName = “My Organization Name” sgData[] =

(sgData){
sgID = 00001 sgName = “Main St Garage” parentGroupID = “0”

}

getStationGroupDetails(sgID, *stationID)[source]¶

Gives details for a given station group.

Parameters

sgID – groupID of stations to clear.
stationID – (Optional) ID of individual station to clear. If this is used, only that station will be

returned in the stationData list. If this parameter is given, numStations will return 1

:returns SOAP reply object. If successful, there will be a responseCode of ‘100’.

Reply:

(reply){

responseCode = “100” responseText = “API input request executed successfully.” groupName = “My Group Name” numStations = 1 stationData[] =

(stationGroupData){
stationID = “1:00001” stationName = “CHARGEPOINT / MAIN 001” Address = “1 Main St, Oakland, California, 94607, United States”

}

getStationGroups(orgID)[source]¶

Returns a list of groups and their stations belonging to an organization.

Parameters: orgID – Chargepoint Organization ID

Reply:

(reply){

responseCode = “100” responseText = “API input request executed successfully.” groupData[] =

(groupsdata){
sgID = 00001 orgID = “1:ORG00001” sgName = “Main St Garage” organizationName = “My Organization Name” stationData[] =

(stationData){
stationID = “1:00001” Geo =

(geoData){
Lat = “12.345678901234567” Long = “-123.456789012345678”

}

}

getStationRights(**kwargs)[source]¶

Returns station rights profiles as defined by the given query parameters.

It is worth noting that there ay be more than one rights profile for a given station. A profile defined the relationship between a charge station and a group and a charge station may belong to multiple groups.

Parameters

**kwargs –

any top-level kwarg in the following query. Most frequently queried via stationID.

Query:

(stationRightsSearchRequest){

stationID = None stationManufacturer = None stationModel = None stationName = None serialNumber = None Address = None City = None State = None Country = None postalCode = None Proximity = None proximityUnit = None Connector = None Voltage = None Current = None Power = None demoSerialNumber =

(serialNumberData){
serialNumber[] = <empty>

}

Reservable = None Geo =

(geoData){
Lat = None Long = None

}

Level = None Mode = None Pricing =

(pricingOptions){
startTime = None Duration = None energyRequired = None vehiclePower = None

}

orgID = None organizationName = None sgID = None sgName = None provisionDateRange =

(provisionDateRange){
startDate = None endDate = None

}

currentFault = None portStatus = None adminStatus = None networkStatus = None provisionStatus = None startRecord = None

}

Reply:

(reply){

responseCode = “100” responseText = “API input request executed successfully.” rightsData[] =

(rightsData){
sgID = “00001” sgName = “Main St Garage” stationRightsProfile = “network_manager” stationData[] =

(stationDataRights){
stationID = “1:00001” stationName = “CHARGEPOINT / MAIN 001” stationSerialNum = “000000000001” stationMacAddr = “0123:4567:89AB:CDEF”

moreFlag = 0

}

getStationStatus(station)[source]¶

Get port-level charging status for a given station

Parameters: station – stationID to query

Reply:

(reply){

responseCode = “100” responseText = “API input request executed successfully.” stationData[] =

(oStatusdata){ stationID = “1:00001” Port[] =

(portDataStatus){
portNumber = “1” Status = “AVAILABLE” TimeStamp = 2016-12-12 12:34:56+00:00

moreFlag = 0

}

getStations(**kwargs)[source]¶

Returns a list of Chargepoint Stations based on keyword query args

It is worth noting that only stations the client has access to will be returned.

Parameters

**kwargs –

any top-level kwarg in the following query. Most frequently queried via stationID.

Query:

(stationSearchRequestExtended){

stationID = None stationManufacturer = None stationModel = None stationName = None serialNumber = None Address = None City = None State = None Country = None postalCode = None Proximity = None proximityUnit = None Connector = None Voltage = None Current = None Power = None demoSerialNumber =

(serialNumberData){
serialNumber[] = <empty>

}

Reservable = None Geo =

(geoData){
Lat = None Long = None

}

Level = None Mode = None Pricing =

(pricingOptions){
startTime = None Duration = None energyRequired = None vehiclePower = None

}

orgID = None organizationName = None sgID = None sgName = None stationActivationDate = None startRecord = None numStations = None

}

Reply:

(reply){

responseCode = “100” responseText = “API input request executed successfully.” stationData[] =

(stationDataExtended){
stationID = “1:00001” stationManufacturer = “ChargePoint” stationModel = “CT2100-HD-CCR” stationMacAddr = “0123:4567:89AB:CDEF” stationSerialNum = “000000000001” stationActivationDate = 2016-01-01 12:23:45 Address = “1 Main St ” City = “Oakland” State = “California” Country = “United States” postalCode = “94607” Port[] =

(portData){
portNumber = “1” stationName = “CHARGEPOINT / MAIN 001” Geo =

(geoData){
Lat = “12.345678901234567” Long = “-123.456789012345678”

}

Description = “Use garage entrance on Main St., turn right and follow … Reservable = 0 Level = “L1” Connector = “NEMA 5-20R” Voltage = “120” Current = “16” Power = “1.920” estimatedCost = 0.0

Pricing[] =

(pricingSpecification){
Type = “None” startTime = 00:00:00 endTime = 23:59:59 minPrice = 0.0 maxPrice = 0.0 unitPricePerHour = 0.0 unitPricePerSession = 1.0 unitPricePerKWh = 0.2

},

numPorts = 2 mainPhone = “1-888-123-4567” currencyCode = “USD” orgID = “1:ORG00001” organizationName = “My Organization Name” sgID = “00001, 00002, 00003, 00004, 00005, 00006, 00007, 00008, 00009, … sgName = “Main St Garage, Public Garages, California Stations, …

moreFlag = 0

}

getUsers(**kwargs)[source]¶

Returns a list of Users as defined by the given query parameters

Parameters

**kwargs –

any top-level kwarg in the following query. Most frequently queried via userID or credentialID.

Query:

(getUsersSearchRequest){

userID = None firstName = None lastName = None lastModifiedTimeStamp = None Connection =

(connectionDataRequest){

Status =

(connectedUserStatusTypes){
value = None

}

customInfo =

(customInfoData){
Key = None Value = None

}

}

managementRealm =

(managementRealmRequest){

Status =

(managedUserStatusTypes){: value = None

}

customInfo =

(customInfoData){: Key = None Value = None

}

credentialID = None startRecord = None numUsers = None

}

Reply

(reply){

responseCode = “100” responseText = “API input request executed successfully.” users =

(userParams){

user[] =

(userData){
lastModifiedTimestamp = 2016-11-11 01:23:45+00:00 userID = “123456” firstName = “John” lastName = “Doe” Connection =

(connectionData){
Status = “APPROVED” requestTimeStamp = 2016-11-11 01:23:45+00:00 customInfos =

(customInfosData){

customInfo[] =

(customInfoData){
Key = “Custom Key” Value = “Custom Value”

}

}

managementRealm = “” credentialIDs =

(credentialIDsData){

credentialID[] =
“123456789”, …

}

recordNumber = 1

moreFlag = 0

}

}

set_client(client)[source]¶

set_security_token()[source]¶

shedLoad(**kwargs)[source]¶

Reduce load on a Charegepoint station.

Main functionality for reducing load on a chargepoint station. Can pass either allowedLoadPerStation OR percentShedPerStation, but not both (one must be None).

Parameters

**kwargs –

Input parameters for shedding load. One of allowedLoadPerStation and percentshedPerStation

must be included.

Query:

(shedLoadQueryInputData){

shedGroup =

(shedLoadGroupInputData){: sgID = None allowedLoadPerStation = None percentShedPerStation = None

}

shedStation =

(shedLoadStationInputData){

stationID = None allowedLoadPerStation = None percentShedPerStation = None Ports =

(Ports){
Port[] = <empty>

}

}

timeInterval = None

}

:returns SOAP reply object. If successful, there will be a responseCode of ‘100’.

class platform_driver.interfaces.chargepoint.service.CPStation(cps, sld=None, sde=None)[source]¶

Bases: object

Wrapper around the getStations() return by Chargepoint API.

Data surrounding a Chargepoint Station can generally be categorized as static or dynamic. Chargepoint API has two basic calls, getLoad and getStation, that each return station data. getLoad returns the stationLoadData SUDS object, and getStation returns the stationDataExtended SUDS object. These are each kept as separate meta-data parameters.

Parameters

cps – Chargepoint Service object.
sld – stationLoadData SUDS object.
sde – stationDataExtended SUDS object.

(stationDataExtended){

stationID = “1:00001” stationManufacturer = “ChargePoint” stationModel = “CT2100-HD-CDMA-CCR” stationMacAddr = “0123:4567:89AB:CDEF” stationSerialNum = “000000000001” stationActivationDate = 2016-01-01 12:23:45 Address = “1 Main St ” City = “Oakland” State = “California” Country = “United States” postalCode = “94607” Port[] =

(portData){
portNumber = “1” stationName = “CHARGEPOINT / MAIN 001” Geo =

(geoData){
Lat = “12.345678901234567” Long = “-123.456789012345678”

}

Description = “Use garage entrance on Main St., turn right and follow … Reservable = 0 Level = “L1” Connector = “NEMA 5-20R” Voltage = “120” Current = “16” Power = “1.920” estimatedCost = 0.0

}, (portData){

portNumber = “2” stationName = “CHARGEPOINT / MAIN 001” Geo =

(geoData){
Lat = “12.345678901234567” Long = “-123.456789012345678”

}

Description = “Use garage entrance on Main St., turn right and follow … Reservable = 0 Level = “L2” Connector = “J1772” Voltage = “240” Current = “30” Power = “6.600” estimatedCost = 0.0

},

Pricing[] =

(pricingSpecification){: Type = “None” startTime = 00:00:00 endTime = 23:59:59 minPrice = 0.0 maxPrice = 0.0 unitPricePerHour = 0.0 unitPricePerSession = 1.0 unitPricePerKWh = 0.2

},

numPorts = 2 mainPhone = “1-888-123-4567” currencyCode = “USD” orgID = “1:ORG00001” organizationName = “My Organization Name” sgID = “00001, 00002, 00003, 00004, 00005, 00006, 00007, 00008, 00009, … sgName = “Main St Garage, Public Garages, California Stations, …

}

(stationloaddata){

stationID = “1:00001” stationName = “CHARGEPOINT / MAIN 001” Address = “1 Main St, Oakland, California, 94607, United States” stationLoad = 5.43 Port[] =

(stationPortData){
portNumber = “1” userID = None credentialID = None shedState = 0 portLoad = 0.0 allowedLoad = 0.0 percentShed = “0”

}, (stationPortData){

portNumber = “2” credentialID = “ABC000123456” shedState = 0 portLoad = 5.43 allowedLoad = 0.0 percentShed = “0”

},

}

Property id: sde.stationID
Property manufacturer: sde.stationManufacturer
Property model: sde.stationModel
Property mac: sde.stationMacAddr
Property serial: sde.stationSerialNum
Property activationDate: sde.stationActivationDate
Property name: sld.stationName
Property load: sld.stationLoad

property activationDate¶

property id¶

property load¶

property mac¶

property manufacturer¶

property model¶

property name¶

property organization¶

property ports¶

refreshStationData()[source]¶

refreshStationDataExtended()[source]¶

property serial¶

class platform_driver.interfaces.chargepoint.service.CPStationGroup(cps, groupsdata)[source]¶

Bases: object

Wrapper around the getStationGroups() return by Chargepoint API.

Parameters

cps – Chargepoint Service object.
groupsdata – Returned from Chargepoint API. Defined below.

(groupsdata){

sgID = 00001 orgID = “1:ORG00001” sgName = “Main St Garage” organizationName = “My Organization Name” stationData[] =

(stationData){
stationID = “1:00001” Geo =

(geoData){
Lat = “12.345678901234567” Long = “-123.456789012345678”

}

}

Property id: sgID
Property name: sgName
Property organization: CPOrganization __str__ representation
Property station_ids: List of IDs for stations in belonging to the group

property id¶

property name¶

property organization¶

property station_ids¶

platform_driver.interfaces.modbus_tk package¶

Subpackages¶

platform_driver.interfaces.modbus_tk.maps package¶

platform_driver.interfaces.modbus_tk.tests package¶

Subpackages¶

platform_driver.interfaces.modbus_tk.tests.example_config package¶

platform_driver.interfaces.modbus_tk.tests.modbus_listener_agent module¶

platform_driver.interfaces.modbus_tk.tests.modbus_server module¶

platform_driver.interfaces.modbus_tk.tests.test_battery_meter module¶

platform_driver.interfaces.modbus_tk.tests.test_ion6200 module¶

platform_driver.interfaces.modbus_tk.tests.test_mixed_endian module¶

platform_driver.interfaces.modbus_tk.tests.test_modbus_tk_driver module¶

platform_driver.interfaces.modbus_tk.tests.test_scale_reg module¶

platform_driver.interfaces.modbus_tk.tests.test_scale_reg_pow_10 module¶

platform_driver.interfaces.modbus_tk.tests.test_scrape_all module¶

platform_driver.interfaces.modbus_tk.tests.test_watts_on module¶

platform_driver.interfaces.modbus_tk.tests.test_write_single_registers module¶

platform_driver.interfaces.modbus_tk.client module¶

platform_driver.interfaces.modbus_tk.config_cmd module¶

platform_driver.interfaces.modbus_tk.helpers module¶

platform_driver.interfaces.modbus_tk.server module¶

platform_driver.interfaces.ted_meter package¶

The TED Driver allows scraping of TED Pro Meters via an HTTP API

class platform_driver.interfaces.ted_meter.Interface(**kwargs)[source]¶

Bases: platform_driver.interfaces.BasicRevert, platform_driver.interfaces.BaseInterface

Create an interface for the TED device using the standard BaseInterface convention

configure(config_dict, registry_config_str)[source]¶: Configure method called by the platform driver with configuration stanza and registry config file, we ignore the registry config, as we build the registers based on the configuration collected from TED Pro Device

get_data()[source]¶: returns a tuple of ETree objects corresponding to the three aapi endpoints

get_point(point_name)[source]¶

Get the current value for the point name given.

Parameters

point_name (str) – Name of the point to retrieve.
kwargs – Any interface specific parameters.

Returns

Point value

insert_register(register)[source]¶: We override the default insert_register behavior so that we can automatically create additional totalized registers when track_totalizers is True

class platform_driver.interfaces.ted_meter.Register(volttron_point_name, units, description)[source]¶

Generic class for containing information about a the points exposed by the TED Pro API

Parameters

register_type (str) – Type of the register. Either “bit” or “byte”. Usually “byte”.
pointName (str) – Name of the register.
units (str) – Units of the value of the register.
description (str) – Description of the register.

The TED Meter Driver does not expose the read_only parameter, as the TED API does not support writing data.

platform_driver.interfaces.IEEE2030_5 module¶

class platform_driver.interfaces.IEEE2030_5.IEEE2030_5Register(read_only, point_name, IEEE2030_5_resource_name, IEEE2030_5_field_name, units, data_type, default_value=None, description='')[source]¶

Bases: platform_driver.interfaces.BasicRevert, platform_driver.interfaces.BaseInterface

Register for all IEEE 2030.5 interface attributes.

is_stale()[source]¶

set_value(x)[source]¶: Cast the point value to the correct data type, set the register value, update the cache timestamp.

property value¶

class platform_driver.interfaces.IEEE2030_5.Interface(**kwargs)[source]¶

IEEE 2030.5 device driver interface.

This driver gets, and sends, device data by issuing RPC calls to IEEE 2030.5Agent, (see its source code in services/core/IEEE2030_5Agent), which communicates with IEEE 2030.5 devices via a web interface.

For further information about this subsystem, please see the VOLTTRON IEEE 2030.5 DER Support specification, which is located in VOLTTRON readthedocs under specifications/IEEE2030_5_agent.html.

Test drivers for the IEEE 2030.5 interface can be configured as follows:

cd $VOLTTRON_ROOT export DRIVER_ROOT=$VOLTTRON_ROOT/services/core/PlatformDriverAgent/platform_driver volttron-ctl config store platform.driver IEEE2030_5.csv $DRIVER_ROOT/IEEE2030_5.csv –csv volttron-ctl config store platform.driver devices/IEEE2030_5_1 $DRIVER_ROOT/test_IEEE2030_5_1.config volttron-ctl config store platform.driver devices/IEEE2030_5_2 $DRIVER_ROOT/test_IEEE2030_5_2.config echo IEEE2030_5 drivers configured for PlatformDriver: volttron-ctl config list platform.driver

call_agent_config_points()[source]¶: Issue a IEEE2030_5Agent RPC call to initialize the point configuration.

call_agent_rpc(rpc_name, point_name=None, value=None)[source]¶: Issue a IEEE2030_5Agent RPC call (get_point, get_points, or set_point), and return the result.

configure(config_dict, registry_config)[source]¶

Configures the Interface for the specific instance of a device.

Parameters

config_dict (dict) – The “driver_config” section of the driver configuration file.
registry_config_str (str) – The contents of the registry configuration file.

This method must setup register representations of all points on a device by creating instances of BaseRegister (or a subclass) and adding them to the Interface with BaseInterface.insert_register().

get_point(point_name, **kwargs)[source]¶: Get the point value, fetching it from IEEE2030_5Agent if not already cached.

get_point_map()[source]¶: Return a dictionary of all register definitions, indexed by Volttron Point Name.

get_register_value(point_name)[source]¶

platform_driver.interfaces.bacnet module¶

class platform_driver.interfaces.bacnet.Interface(**kwargs)[source]¶

Bases: platform_driver.interfaces.BaseInterface

configure(config_dict, registry_config_str)[source]¶

Configures the Interface for the specific instance of a device.

Parameters

config_dict (dict) – The “driver_config” section of the driver configuration file.
registry_config_str (str) – The contents of the registry configuration file.

This method must setup register representations of all points on a device by creating instances of BaseRegister (or a subclass) and adding them to the Interface with BaseInterface.insert_register().

establish_cov_subscription(point_name, lifetime, renew=False)[source]¶: Asks the BACnet proxy to establish a COV subscription for the point via RPC. If lifetime is specified, the subscription will live for that period, else the subscription will last indefinitely. Default period of 3 minutes. If renew is True, the the core scheduler will call this method again near the expiration of the subscription.

get_point(point_name, get_priority_array=False)[source]¶

Get the current value for the point name given.

Parameters

point_name (str) – Name of the point to retrieve.
kwargs – Any interface specific parameters.

Returns

Point value

parse_config(configDict)[source]¶

ping_target()[source]¶

revert_all(priority=None)[source]¶: Revert entrire device to it’s default state

revert_point(point_name, priority=None)[source]¶: Revert point to it’s default state

schedule_ping()[source]¶

scrape_all()[source]¶

Method the Platform Driver Agent calls to get the current state of a device for publication.

Returns: Point names to values for device.
Return type: dict

set_point(point_name, value, priority=None)[source]¶

Set the current value for the point name given.

Implementations of this method should make a reasonable effort to return the actual value the point was set to. Some protocols/devices make this difficult. (I’m looking at you BACnet) In these cases it is acceptable to return the value that was requested if no error occurs.

Parameters

point_name (str) – Name of the point to retrieve.
value – Value to set the point to.
kwargs – Any interface specific parameters.

Returns

Actual point value set.

class platform_driver.interfaces.bacnet.Register(instance_number, object_type, property_name, read_only, point_name, units, description='', priority=None, list_index=None)[source]¶: Bases: platform_driver.interfaces.BaseRegister

platform_driver.interfaces.dnp3 module¶

class platform_driver.interfaces.dnp3.DNP3Register(read_only, volttron_name, dnp3_name, scaling, units, data_type)[source]¶

Bases: platform_driver.interfaces.BasicRevert, platform_driver.interfaces.BaseInterface

Register for each DNP3 interface field (point).

is_stale()[source]¶: Whether it is time to refresh the register’s cached value.

set_value(x)[source]¶: Cast the point value to the correct data type, set the register value, update the cache timestamp.

property value¶

class platform_driver.interfaces.dnp3.Interface(**kwargs)[source]¶

DNP3 device driver interface.

This driver gets, and sends, DNP3 device data by issuing RPC calls to DNP3Agent, (see its source code in services/core/DNP3Agent), which communicates with the DNP3 master via a web interface.

Test drivers for the DNP3 interface can be configured as follows:

export VOLTTRON_ROOT=<your VOLTTRON install directory> export DRIVER_ROOT=$VOLTTRON_ROOT/services/core/PlatformDriverAgent cd $VOLTTRON_ROOT volttron-ctl config store platform.driver dnp3.csv $DRIVER_ROOT/example_configurations/dnp3.csv –csv volttron-ctl config store platform.driver devices/dnp3 $DRIVER_ROOT/example_configurations/test_dnp3.config

all_registers()[source]¶: Return a list of all registers. The read-only registers are placed before the read-write registers.

call_agent_config_points()[source]¶

Issue a DNP3Agent RPC call to initialize the driver’s point configuration.

The point_map dictionary maps VOLTTRON point name to DNP3 point name for each point that’s configured by the driver:

{
volttron_point_name_1: dnp3_point_name_1, volttron_point_name_2: dnp3_point_name_2, …

}

call_agent_rpc(rpc_name, point_name=None, value=None)[source]¶: Issue a DNP3Agent RPC call (get_point, get_points, or set_point), and return the result.

configure(config_dict, registry_config)[source]¶: Load driver config from the registry, as set up in the VOLTTRON config store.

get_point(point_name, **kwargs)[source]¶

Get a point value by (VOLTTRON) point name.

Fetch it from the DNP3Agent if it’s not already fresh in the cache.

get_register_value(point_name)[source]¶

platform_driver.interfaces.ecobee module¶

class platform_driver.interfaces.ecobee.Hold(thermostat_identifier, read_only, readable, point_name, point_path, units, description='')[source]¶

Bases: platform_driver.interfaces.BasicRevert, platform_driver.interfaces.BaseInterface

Register to wrap around points contained in hold field of Ecobee API’s thermostat data response

get_state(ecobee_data)[source]¶

Parameters: ecobee_data – Ecobee data dictionary obtained from Driver HTTP Cache agent
Returns: Most recently available data for this setting register

set_state(value, access_token)[source]¶: Set Ecobee thermostat hold by configured point name and provided value dictionary :param value: Arbitrarily specified value dictionary. Ecobee API documentation provides best practice information for each hold. :param access_token: Ecobee access token to provide as bearer auth in request :return: request response values from settings request

class platform_driver.interfaces.ecobee.Interface(**kwargs)[source]¶

Interface implementation for wrapping around the Ecobee thermostat API

authorize_application()[source]¶

configure(config_dict, registry_config_str)[source]¶: Interface configuration callback :param config_dict: Driver configuration dictionary :param registry_config_str: Driver registry configuration dictionary

get_auth_config_from_store()[source]¶

Returns: Fetch currently stored auth configuration info from config store, returns empty dict if none is

present

get_data_cache(url, update_frequency)[source]¶: Fetches data from cache dict if it is up to date :param url: URL to use to use as lookup value in cache dict :param update_frequency: duration in seconds for which data in cache is considered up to date :return: Data stored in cache if up to date, otherwise None

get_data_remote(request_type, url, **kwargs)[source]¶: Make request to Ecobee remote API for “register” data, updating authorization tokens as necessary :param request_type: HTTP request type for making request :param url: URL corresponding to “register” data :param kwargs: HTTP request arguments :return: remote API response body

get_ecobee_data(request_type, url, update_frequency, refresh=False, **kwargs)[source]¶: Checks cache for up to date Ecobee data. If none is available for the URL, makes a request to remote Ecobee API. :param refresh: force Ecobee data to be obtained from the remote API rather than cache :param request_type: HTTP request type for request sent to remote :param url: URL of remote Ecobee API endpoint :param update_frequency: period for which cached data is considered up to date :param kwargs: HTTP request arguments :return: Up to date Ecobee data for URL

get_point(point_name, **kwargs)[source]¶: Return a point’s most recent stored value from remote API :param point_name: The name of the point corresponding to a register to get the state of :return: register’s most recent state from remote API response

get_thermostat_data(refresh=False)[source]¶: Collects most up to date thermostat object data for the configured Ecobee thermostat ID :param refresh: whether or not to force obtaining new data from the remote Ecobee API

parse_config(config_dict)[source]¶: Parse driver registry configuration and create device registers :param config_dict: Registry configuration in dictionary representation

refresh_tokens()[source]¶: Refresh Ecobee API authentication tokens via API endpoint - asks Ecobee to reset tokens then updates config with new tokens from Ecobee

request_tokens()[source]¶: Request up to date Auth tokens from Ecobee using API key and authorization code

store_remote_data(url, response)[source]¶: Store response body with a timestamp for a given URL :param url: url to use to use as lookup value in cache dict :param response: request response body to store in cache

update_auth_config()[source]¶: Update the platform driver configuration for this device with new values from auth functions

update_authorization()[source]¶

class platform_driver.interfaces.ecobee.Program(thermostat_identifier)[source]¶

Wrapper register for managing Ecobee thermostat programs, and getting program status

get_state(ecobee_data)[source]¶

Parameters: ecobee_data – Ecobee data dictionary obtained from Driver HTTP Cache agent
Returns: List of Ecobee event objects minus vacation events

set_state(program, access_token, resume_all=False)[source]¶: Set a new program, resume the next program on the programs stack, or “resume all” :param program: Program dictionary as specified by Ecobee API docs if setting a new program, else None :param access_token: Ecobee access token to provide as bearer auth in request :param resume_all: Whether or not to “resume all” if using the resume program function

class platform_driver.interfaces.ecobee.Setting(thermostat_identifier, read_only, readable, point_name, point_path, units, description='')[source]¶

Register to wrap around points contained in setting field of Ecobee API’s thermostat data response

get_state(ecobee_data)[source]¶

Parameters: ecobee_data – Ecobee data dictionary obtained from Driver HTTP Cache agent
Returns: Most recently available data for this setting register

set_state(value, access_token)[source]¶: Set Ecobee thermostat setting value by configured point name and provided value :param value: Arbitrarily specified value to request as set point :param access_token: Ecobee access token to provide as bearer auth in request :return: request response values from settings request

class platform_driver.interfaces.ecobee.Status(thermostat_identifier)[source]¶

Status request wrapper register for Ecobee thermostats. Note: There is a single status point for each thermostat, which is set by the device.

get_state(ecobee_data)[source]¶

Returns: List of currently running equipment connected to Ecobee thermostat

set_state(value, access_token)[source]¶: Set state is not supported for the static Status register.

class platform_driver.interfaces.ecobee.Vacation(thermostat_identifier)[source]¶

Wrapper register for adding and deleting vacations, and getting vacation status Note: Since vacations are transient, only 1 vacation register will be created per driver. The driver can be used to add, delete, or get the status of all vacations for the device

get_state(ecobee_data)[source]¶

Parameters: ecobee_data – Ecobee data dictionary obtained from Driver HTTP Cache agent
Returns: List of vacation dictionaries returned by Ecobee remote API

set_state(vacation, access_token, delete=False)[source]¶: Send delete or create vacation request to Ecobee API for the configured thermostat :param vacation: Vacation name for delete, or vacation object dictionary for create :param access_token: Ecobee access token to provide as bearer auth in request :param delete: Whether to delete the named vacation

platform_driver.interfaces.ecobee.call_grequest(method_name, url, **kwargs)[source]¶: Make grequest calls to remote api :param method_name: method type - put/get/delete :param url: http URL suffix :param kwargs: Additional arguments for http request :return: grequest response

platform_driver.interfaces.ecobee.make_ecobee_request(request_type, url, **kwargs)[source]¶: Wrapper around making arbitrary GET and POST requests to remote Ecobee API :return: Ecobee API response using provided request content

platform_driver.interfaces.ecobee.populate_selection_objects(access_token, selection_type, selection_match, specification)[source]¶: Utility method for generating set point request bodies for Ecobee remote api :param access_token: Ecobee access token from auth steps/configuration (bearer in request header) :param selection_type: Ecobee identity selection type :param selection_match: Ecobee identity selection match id :param specification: dictionary specifying the Ecobee object for updating the point on the remote API :return: request body JSON as dictionary

platform_driver.interfaces.ecobee.populate_thermostat_headers(access_token)[source]¶: Create populated header json as dictionary :param access_token: Ecobee “bearer” access token :return: header json as dictionary

platform_driver.interfaces.fakedriver module¶

class platform_driver.interfaces.fakedriver.EKGregister(read_only, pointName, units, reg_type, default_value=None, description='')[source]¶

Bases: platform_driver.interfaces.BasicRevert, platform_driver.interfaces.BaseInterface

property value¶

class platform_driver.interfaces.fakedriver.FakeRegister(read_only, pointName, units, reg_type, default_value=None, description='')[source]¶: Bases: platform_driver.interfaces.BaseRegister

class platform_driver.interfaces.fakedriver.Interface(**kwargs)[source]¶

configure(config_dict, registry_config_str)[source]¶

Configures the Interface for the specific instance of a device.

Parameters

config_dict (dict) – The “driver_config” section of the driver configuration file.
registry_config_str (str) – The contents of the registry configuration file.

This method must setup register representations of all points on a device by creating instances of BaseRegister (or a subclass) and adding them to the Interface with BaseInterface.insert_register().

get_point(point_name)[source]¶

Get the current value for the point name given.

Parameters

point_name (str) – Name of the point to retrieve.
kwargs – Any interface specific parameters.

Returns

Point value

parse_config(configDict)[source]¶

platform_driver.interfaces.modbus module¶

class platform_driver.interfaces.modbus.Interface(**kwargs)[source]¶

Bases: platform_driver.interfaces.BasicRevert, platform_driver.interfaces.BaseInterface

build_ranges_map()[source]¶

configure(config_dict, registry_config_str)[source]¶

Configures the Interface for the specific instance of a device.

Parameters

config_dict (dict) – The “driver_config” section of the driver configuration file.
registry_config_str (str) – The contents of the registry configuration file.

This method must setup register representations of all points on a device by creating instances of BaseRegister (or a subclass) and adding them to the Interface with BaseInterface.insert_register().

get_point(point_name)[source]¶

Get the current value for the point name given.

Parameters

point_name (str) – Name of the point to retrieve.
kwargs – Any interface specific parameters.

Returns

Point value

insert_register(register)[source]¶

Inserts a register into the Interface.

Parameters: register (BaseRegister) – Register to add to the interface.

merge_register_ranges()[source]¶: Merges any adjacent registers for more efficient scraping. May only be called after all registers have been inserted.

parse_config(configDict)[source]¶

scrape_bit_registers(client, read_only)[source]¶

scrape_byte_registers(client, read_only)[source]¶

class platform_driver.interfaces.modbus.ModbusBitRegister(address, type_string, pointName, units, read_only, mixed_endian=False, description='', slave_id=0)[source]¶

Bases: platform_driver.interfaces.modbus.ModbusRegisterBase

get_register_count()[source]¶

get_state(client)[source]¶

parse_value(starting_address, bit_stream)[source]¶

set_state(client, value)[source]¶

class platform_driver.interfaces.modbus.ModbusByteRegister(address, type_string, pointName, units, read_only, mixed_endian=False, description='', slave_id=0)[source]¶

Bases: platform_driver.interfaces.modbus.ModbusRegisterBase

get_register_count()[source]¶

get_state(client)[source]¶

parse_value(starting_address, byte_stream)[source]¶

set_state(client, value)[source]¶

exception platform_driver.interfaces.modbus.ModbusInterfaceException(string)[source]¶: Bases: pymodbus.exceptions.ModbusException

class platform_driver.interfaces.modbus.ModbusRegisterBase(address, register_type, read_only, pointName, units, description='', slave_id=0)[source]¶: Bases: platform_driver.interfaces.BaseRegister

platform_driver.interfaces.modbus.modbus_client(address, port)[source]¶

platform_driver.interfaces.obix module¶

class platform_driver.interfaces.obix.Interface(**kwargs)[source]¶

Bases: platform_driver.interfaces.BasicRevert, platform_driver.interfaces.BaseInterface

configure(config_dict, registry_config)[source]¶

Configures the Interface for the specific instance of a device.

Parameters

config_dict (dict) – The “driver_config” section of the driver configuration file.
registry_config_str (str) – The contents of the registry configuration file.

This method must setup register representations of all points on a device by creating instances of BaseRegister (or a subclass) and adding them to the Interface with BaseInterface.insert_register().

get_point(point_name)[source]¶

Get the current value for the point name given.

Parameters

point_name (str) – Name of the point to retrieve.
kwargs – Any interface specific parameters.

Returns

Point value

parse_config(configDict, url)[source]¶

class platform_driver.interfaces.obix.Register(url, point_name, obix_point_name, obix_type_str, read_only, units, description='')[source]¶

get_value_async_result(username=None, password=None)[source]¶

obix_types = {'bool': <function Register.<lambda>>, 'int': <class 'int'>, 'real': <class 'float'>}¶

parse_result(xml_tree)[source]¶

set_value_async_result(value, username=None, password=None)[source]¶

platform_driver.interfaces.radiothermostat module¶

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

class platform_driver.interfaces.radiothermostat.Interface(**kwargs)[source]¶

Bases: platform_driver.interfaces.BaseInterface

configure(config_dict, registry_config_str)[source]¶: Configure the Inteface

get_point(point_name)[source]¶: Returns the value of a point on the device

parse_config(configDict)[source]¶

ping_target(address)[source]¶: Ping target function not implemented for this interface

revert_all()[source]¶: Sets all points on the device to their default values

revert_point(point_name)[source]¶: sets the value of a point to its default value

scrape_all()[source]¶: Scrapes the device for current status of all points

set_point(point_name, value)[source]¶: Sets the value of a point o the devcie

class platform_driver.interfaces.radiothermostat.Register(read_only, pointName, device_point_name, units, default_value)[source]¶

Inherits from Volttron Register Class

platform_driver.interfaces.rainforesteagle module¶

class platform_driver.interfaces.rainforesteagle.InstantaneousDemand[source]¶

Bases: platform_driver.interfaces.BasicRevert, platform_driver.interfaces.BaseInterface

value()[source]¶

class platform_driver.interfaces.rainforesteagle.Interface(**kwargs)[source]¶

configure(config_dict, register_config)[source]¶

Configures the Interface for the specific instance of a device.

Parameters

config_dict (dict) – The “driver_config” section of the driver configuration file.
registry_config_str (str) – The contents of the registry configuration file.

This method must setup register representations of all points on a device by creating instances of BaseRegister (or a subclass) and adding them to the Interface with BaseInterface.insert_register().

get_point(point_name)[source]¶

Get the current value for the point name given.

Parameters

point_name (str) – Name of the point to retrieve.
kwargs – Any interface specific parameters.

Returns

Point value

class platform_driver.interfaces.rainforesteagle.NetworkStatus[source]¶

value()[source]¶

class platform_driver.interfaces.rainforesteagle.PeakDelivered[source]¶

value()[source]¶

class platform_driver.interfaces.rainforesteagle.PeakReceived[source]¶

value()[source]¶

class platform_driver.interfaces.rainforesteagle.PriceCluster[source]¶

value()[source]¶

class platform_driver.interfaces.rainforesteagle.SummationDelivered[source]¶

value()[source]¶

class platform_driver.interfaces.rainforesteagle.SummationReceived[source]¶

value()[source]¶

platform_driver.interfaces.rainforesteagle.get_demand_peaks(key)[source]¶

platform_driver.interfaces.rainforesteagle.get_summation(key)[source]¶

platform_driver.interfaces.rainforestemu2 module¶

class platform_driver.interfaces.rainforestemu2.InstantaneousDemand[source]¶

Bases: platform_driver.interfaces.BasicRevert, platform_driver.interfaces.BaseInterface

value()[source]¶

class platform_driver.interfaces.rainforestemu2.Interface(**kwargs)[source]¶

configure(config_dict, register_config)[source]¶

Configures the Interface for the specific instance of a device.

Parameters

config_dict (dict) – The “driver_config” section of the driver configuration file.
registry_config_str (str) – The contents of the registry configuration file.

This method must setup register representations of all points on a device by creating instances of BaseRegister (or a subclass) and adding them to the Interface with BaseInterface.insert_register().

get_point(point_name)[source]¶

Get the current value for the point name given.

Parameters

point_name (str) – Name of the point to retrieve.
kwargs – Any interface specific parameters.

Returns

Point value

class platform_driver.interfaces.rainforestemu2.NetworkInfo[source]¶

value()[source]¶

class platform_driver.interfaces.rainforestemu2.PriceCluster[source]¶

Bases: platform_driver.interfaces.BasicRevert, platform_driver.interfaces.BaseInterface

value()[source]¶

platform_driver.interfaces.restful module¶

class platform_driver.interfaces.restful.Interface(**kwargs)[source]¶

configure(config_dict, registry_config_str)[source]¶

Configures the Interface for the specific instance of a device.

Parameters

config_dict (dict) – The “driver_config” section of the driver configuration file.
registry_config_str (str) – The contents of the registry configuration file.

This method must setup register representations of all points on a device by creating instances of BaseRegister (or a subclass) and adding them to the Interface with BaseInterface.insert_register().

get_point(point_name, **kwargs)[source]¶

Get the current value for the point name given.

Parameters

point_name (str) – Name of the point to retrieve.
kwargs – Any interface specific parameters.

Returns

Point value

parse_config(configDict)[source]¶

class platform_driver.interfaces.restful.Register(read_only, volttron_point_name, units, description, point_name)[source]¶: Bases: platform_driver.interfaces.BaseRegister

platform_driver.interfaces.thermostat_api module¶

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

class platform_driver.interfaces.thermostat_api.ThermostatInterface(url)[source]¶

Bases: object

Base interface to get and set values on the thermostat

energy_led(data)[source]¶: Controls energy led, possible values: 0,1,2,4

fmode(data)[source]¶: Sets fan’s mode

get_cool_pgm(day='')[source]¶

get cool program for a week or a specific day day = {‘mon’,’tue’,’wed’,’thu’,’fri’,’sat’,’sun’}

for a specific day, say thursday: t.get_cool_pgm(‘thu’)

for a week: t.get_cool_pgm()

get_heat_pgm(day='')[source]¶

get heat program for a week or a specific day day = {‘mon’,’tue’,’wed’,’thu’,’fri’,’sat’,’sun’}

for a specific day, say thursday: t.get_heat_pgm(‘thu’)

for a week: t.get_heat_pgm()

hold(data)[source]¶: Sets hold controls

mode(data)[source]¶: Sets operating mode

model()[source]¶: Returns device model

over(data)[source]¶: Sets override controls

set_cool_pgm(schedules, day='')[source]¶

set cool program for a week or a specific day day = {‘mon’,’tue’,’wed’,’thu’,’fri’,’sat’,’sun’}

for a spefic day, say ‘thu’ t.set_cool_pgm(‘{“360, 80, 480, 80, 1080, 80, 1320 , 80”,’thu’)

t.set_cool_pgm(‘{: “1”: [360, 70, 480, 70, 1080, 70, 1320, 70], “0”: [360, 66, 480, 58, 1080, 66, 1320, 58], “3”: [360, 66, 480, 58, 1080, 66, 1320, 58], “2”: [360, 66, 480, 58, 1080, 66, 1320, 58], “5”: [360, 66, 480, 58, 1080, 66, 1320, 58], “4”: [360, 66, 480, 58, 1080, 66, 1320, 58], “6”: [360, 66, 480, 58, 1080, 66, 1320, 58]

}’)

set_heat_pgm(schedules, day='')[source]¶

set heat program for a week or a specific day day = {‘mon’,’tue’,’wed’,’thu’,’fri’,’sat’,’sun’}

for a spefic day, say ‘thu’

t.set_heat_pgm('{"360, 80, 480, 80, 1080, 80, 1320 , 80",'thu')

for a week

t.set_heat_pgm('{
            "1": [360, 70, 480, 70, 1080, 70, 1320, 70],
            "0": [360, 66, 480, 58, 1080, 66, 1320, 58],
            "3": [360, 66, 480, 58, 1080, 66, 1320, 58],
            "2": [360, 66, 480, 58, 1080, 66, 1320, 58],
            "5": [360, 66, 480, 58, 1080, 66, 1320, 58],
            "4": [360, 66, 480, 58, 1080, 66, 1320, 58],
            "6": [360, 66, 480, 58, 1080, 66, 1320, 58]
     }')

t_cool(data)[source]¶: Sets cooling setpoint

t_heat(data)[source]¶: Sets heating setpoint

t_setpoint(data, point, tmode='')[source]¶: Sets cooling setpoint

tstat()[source]¶: Returns current deicve paramenters

platform_driver.interfaces.thermostat_api.Thermostat_API(url)[source]¶: Call the interface

platform_driver.interfaces.universal module¶

08/15/16 - Remove whitespace in config file. 10/11/16 - Pass only device_id to VehicleDriver. 03/01/17 - Call agent.GetPoint in get_point. 04/17/17 - Updated for Volttron 4.0.

class platform_driver.interfaces.universal.Interface(**kwargs)[source]¶

Bases: platform_driver.interfaces.BasicRevert, platform_driver.interfaces.BaseInterface

configure(config_dict, registry_config_dict)[source]¶

Configures the Interface for the specific instance of a device.

Parameters

config_dict (dict) – The “driver_config” section of the driver configuration file.
registry_config_str (str) – The contents of the registry configuration file.

This method must setup register representations of all points on a device by creating instances of BaseRegister (or a subclass) and adding them to the Interface with BaseInterface.insert_register().

get_point(point_name)[source]¶

Get the current value for the point name given.

Parameters

point_name (str) – Name of the point to retrieve.
kwargs – Any interface specific parameters.

Returns

Point value

parse_config(agent, device_type, config_dict, reg_config_str)[source]¶

platform_driver.agent module¶

exception platform_driver.agent.OverrideError[source]¶

Bases: platform_driver.interfaces.DriverInterfaceError

Error raised when the user tries to set/revert point when global override is set.

class platform_driver.agent.PlatformDriverAgent(driver_config_list, scalability_test=False, scalability_test_iterations=3, driver_scrape_interval=0.02, group_offset_interval=0.0, max_open_sockets=None, max_concurrent_publishes=10000, system_socket_limit=None, publish_depth_first_all=True, publish_breadth_first_all=False, publish_depth_first=False, publish_breadth_first=False, **kwargs)[source]¶

Bases: volttron.platform.vip.agent.Agent

clear_overrides()[source]¶

RPC method

Clear all overrides.

configure_main(config_name, action, contents)[source]¶

derive_device_topic(config_name)[source]¶

forward_bacnet_cov_value(source_address, point_name, point_values)[source]¶: Called by the BACnet Proxy to pass the COV value to the driver agent for publishing :param source_address: path of the device used for publish topic :param point_name: name of the point in the COV notification :param point_values: dictionary of updated values sent by the device

get_multiple_points(path, point_names, **kwargs)[source]¶

get_override_devices()[source]¶

RPC method

Get a list of all the devices with override condition.

get_override_patterns()[source]¶

RPC method

Get a list of all the override patterns.

get_point(path, point_name, **kwargs)[source]¶

RPC method

Return value of specified device set point :param path: device path :type path: str :param point_name: set point :type point_name: str :param kwargs: additional arguments for the device :type kwargs: arguments pointer

heart_beat()[source]¶

RPC method

Sends heartbeat to all devices

remove_driver(config_name, action, contents)[source]¶

revert_device(path, **kwargs)[source]¶

RPC method

Revert all the set point values of the device to default state/values. If global override is condition is set, raise OverrideError exception. :param path: device path :type path: str :param kwargs: additional arguments for the device :type kwargs: arguments pointer

revert_point(path, point_name, **kwargs)[source]¶

RPC method

Revert the set point to default state/value. If global override is condition is set, raise OverrideError exception. :param path: device path :type path: str :param point_name: set point to revert :type point_name: str :param kwargs: additional arguments for the device :type kwargs: arguments pointer

scrape_all(path)[source]¶

scrape_ending(topic)[source]¶

scrape_starting(topic)[source]¶

set_multiple_points(path, point_names_values, **kwargs)[source]¶

RPC method

Set values on multiple set points at once. If global override is condition is set,raise OverrideError exception. :param path: device path :type path: str :param point_names_values: list of points and corresponding values :type point_names_values: list of tuples :param kwargs: additional arguments for the device :type kwargs: arguments pointer

set_override_off(pattern)[source]¶

RPC method

Turn off override condition on all the devices matching the pattern. The pattern matching is based on bash style filename matching semantics. :param pattern: Pattern on which override condition has to be removed. :type pattern: str

set_override_on(pattern, duration=0.0, failsafe_revert=True, staggered_revert=False)[source]¶

RPC method

Turn on override condition on all the devices matching the pattern. :param pattern: Override pattern to be applied. For example,

If pattern is campus/building1/* - Override condition is applied for all the devices under campus/building1/. If pattern is campus/building1/ahu1 - Override condition is applied for only campus/building1/ahu1 The pattern matching is based on bash style filename matching semantics.

Parameters: duration – Time duration for the override in seconds. If duration <= 0.0, it implies as indefinite

duration. :type duration: float :param failsafe_revert: Flag to indicate if all the devices falling under the override condition has to be set

to its default state/value immediately.

Parameters: staggered_revert (boolean) – If this flag is set, reverting of devices will be staggered.

set_point(path, point_name, value, **kwargs)[source]¶

RPC method

Set value on specified device set point. If global override is condition is set, raise OverrideError exception. :param path: device path :type path: str :param point_name: set point :type point_name: str :param value: value to set :type value: int/float/bool :param kwargs: additional arguments for the device :type kwargs: arguments pointer

stop_driver(device_topic)[source]¶

update_driver(config_name, action, contents)[source]¶

platform_driver.agent.main(argv=['/home/docs/checkouts/readthedocs.org/user_builds/volttron/envs/releases-8.1.1/lib/python3.6/site-packages/sphinx/__main__.py', '-T', '-b', 'readthedocssinglehtmllocalmedia', '-d', '_build/doctrees', '-D', 'language=en', '.', '_build/localmedia'])[source]¶: Main method called to start the agent.

platform_driver.agent.platform_driver_agent(config_path, **kwargs)[source]¶

platform_driver.driver module¶

class platform_driver.driver.DriverAgent(parent, config, time_slot, driver_scrape_interval, device_path, group, group_offset_interval, default_publish_depth_first_all=True, default_publish_breadth_first_all=True, default_publish_depth_first=True, default_publish_breadth_first=True, **kwargs)[source]¶

Bases: volttron.platform.vip.agent.BasicAgent

find_starting_datetime(now)[source]¶

get_interface(driver_type, config_dict, config_string)[source]¶: Returns an instance of the interface

get_multiple_points(point_names, **kwargs)[source]¶

get_paths_for_point(point)[source]¶

get_point(point_name, **kwargs)[source]¶

heart_beat()[source]¶

periodic_read(now)[source]¶

publish_cov_value(point_name, point_values)[source]¶: Called in the platform driver agent to publish a cov from a point :param point_name: point which sent COV notifications :param point_values: COV point values

revert_all(**kwargs)[source]¶

revert_point(point_name, **kwargs)[source]¶

scrape_all()[source]¶

set_multiple_points(point_names_values, **kwargs)[source]¶

set_point(point_name, value, **kwargs)[source]¶

setup_device()[source]¶

starting(sender, **kwargs)[source]¶

update_publish_types(publish_depth_first_all, publish_breadth_first_all, publish_depth_first, publish_breadth_first)[source]¶: Setup which publish types happen for a scrape. Values passed in are overridden by settings in the specific device configuration.

update_scrape_schedule(time_slot, driver_scrape_interval, group, group_offset_interval)[source]¶

platform_driver.driver_exceptions module¶

exception platform_driver.driver_exceptions.DriverConfigError[source]¶: Bases: platform_driver.driver_exceptions.DriverError

exception platform_driver.driver_exceptions.DriverError[source]¶: Bases: Exception

platform_driver.driver_locks module¶

platform_driver.driver_locks.configure_publish_lock(max_connections=0)[source]¶

platform_driver.driver_locks.configure_socket_lock(max_connections=0)[source]¶

platform_driver.driver_locks.publish_lock()[source]¶

platform_driver.driver_locks.socket_lock()[source]¶

Platform Driver Agent¶

The Platform Driver agent is a special purpose agent a user can install on the platform to manage communication of the platform with devices. The Platform driver features a number of endpoints for collecting data and sending control signals using the message bus and automatically publishes data to the bus on a specified interval.

Dependencies¶

VOLTTRON drivers operated by the platform driver may have additional requirements for installation. Required libraries:

BACnet driver - bacpypes
Modbus driver - pymodbus
Modbus_TK driver - modbus-tk
DNP3 and IEEE 2030.5 drivers - pydnp3

The easiest way to install the requirements for drivers included in the VOLTTRON repository is to use bootstrap.py

python3 bootstrap.py --drivers

Configuration¶

Agent Configuration¶

The Platform Driver Agent configuration consists of general settings for all devices. The default values of the Platform Driver should be sufficient for most users. The user may optionally change the interval between device scrapes with the driver_scrape_interval.

The following example sets the driver_scrape_interval to 0.05 seconds or 20 devices per second:

{
    "driver_scrape_interval": 0.05,
    "publish_breadth_first_all": false,
    "publish_depth_first": false,
    "publish_breadth_first": false,
    "publish_depth_first_all": true,
    "group_offset_interval": 0.0
}

driver_scrape_interval - Sets the interval between devices scrapes. Defaults to 0.02 or 50 devices per second. Useful for when the platform scrapes too many devices at once resulting in failed scrapes.
group_offset_interval - Sets the interval between when groups of devices are scraped. Has no effect if all devices are in the same group. In order to improve the scalability of the platform unneeded device state publishes for all devices can be turned off. All of the following setting are optional and default to True.
publish_depth_first_all - Enable “depth first” publish of all points to a single topic for all devices.
publish_breadth_first_all - Enable “breadth first” publish of all points to a single topic for all devices.
publish_depth_first - Enable “depth first” device state publishes for each register on the device for all devices.
publish_breadth_first - Enable “breadth first” device state publishes for each register on the device for all devices.

Driver Configuration¶

Each device configuration has the following form:

{
    "driver_config": {"device_address": "10.1.1.5",
                      "device_id": 500},
    "driver_type": "bacnet",
    "registry_config":"config://registry_configs/vav.csv",
    "interval": 60,
    "heart_beat_point": "heartbeat",
    "group": 0
}

The following settings are required for all device configurations:

driver_config - Driver specific setting go here. See below for driver specific settings.
driver_type - Type of driver to use for this device: bacnet, modbus, fake, etc.
registry_config - Reference to a configuration file in the configuration store for registers on the device.

These settings are optional:

interval - Period which to scrape the device and publish the results in seconds. Defaults to 60 seconds.
heart_beat_point - A Point which to toggle to indicate a heartbeat to the device. A point with this Volttron Point Name must exist in the registry. If this setting is missing the driver will not send a heart beat signal to the device. Heart beats are triggered by the Actuator Agent which must be running to use this feature.
group - Group this device belongs to. Defaults to 0

SQLAggregateHistorian¶

sqlaggregator package¶

sqlaggregator.aggregator module¶

class sqlaggregator.aggregator.SQLAggregateHistorian(config_path, **kwargs)[source]¶

Bases: volttron.platform.agent.base_aggregate_historian.AggregateHistorian

Agent to aggregate data in historian based on a specific time period. This aggregate historian aggregates data collected by SQLHistorian.

collect_aggregate(topic_ids, agg_type, start_time, end_time)[source]¶

Collect the aggregate data by querying the historian’s data store

Parameters

topic_ids – list of topic ids for which aggregation should be performed.
agg_type – type of aggregation
start_time – start time for query (inclusive)
end_time – end time for query (exclusive)

Returns

a tuple of (aggregated value, count of record over which

this aggregation was computed)

configure(config_name, action, config)[source]¶

Converts aggregation time period into seconds, validates configuration values and calls the collect aggregate method for the first time

Parameters

config_name – name of the config entry in store. We only use one config store entry with the default name config
action – “NEW or “UPDATE” code treats both the same way
config – configuration as json object

get_agg_topic_map()[source]¶

Query the aggregate_topics table and create a map of (topic name, aggregation type, aggregation time period) to topic id. This should be done as part of init

Returns: Returns a list of topic_map containing

{(agg_topic_name.lower(), agg_type, agg_time_period) :id}

get_aggregation_list()[source]¶

Returns a list of supported aggregations

Returns: list of supported aggregations

get_topic_map()[source]¶

Query the topics table and create a map of topic name to topic id. This should be done as part of init

Returns: Returns a list of topic_map containing {topic_name.lower():id}

initialize_aggregate_store(aggregation_topic_name, agg_type, agg_time_period, topics_meta)[source]¶

Create the data structure (table or collection) that is going to store the aggregate data for the give aggregation type and aggregation time period

Parameters

aggregation_topic_name – Unique topic name for this aggregation. If aggregation is done over multiple points it is a unique name given by user, else it is same as topic_name for which aggregation is done
agg_type – The type of aggregation. For example, avg, sum etc.
agg_time_period – The time period of aggregation
topics_meta – String that represents the list of topics across which this aggregation is computed. It could be topic name pattern or list of topics. This information should go into metadata table

Returns

Return a aggregation_topic_id after inserting aggregation_topic_name into topics table

insert_aggregate(topic_id, agg_type, period, end_time, value, topic_ids)[source]¶

Insert aggregate data collected for a specific time period into database. Data is inserted into <agg_type>_<period> table

Parameters

agg_topic_id – If len(topic_ids) is 1. This would be the same as the topic_ids[0]. Else this id corresponds to the unique topic name given by user for this aggregation across multiple points.
agg_type – type of aggregation
agg_time_period – The time period of aggregation
end_time – end time used for query records that got aggregated
topic_ids – topic ids for which aggregation was computed
value – aggregation result

update_aggregate_metadata(agg_id, aggregation_topic_name, topic_meta)[source]¶

Update aggregation_topic_name and topic_meta data for the given agg_id.

Parameters

agg_id – Aggregation topic id for which update should be done
aggregation_topic_name – New aggregation_topic_name
topic_meta – new topic metadata

sqlaggregator.aggregator.main(argv=['/home/docs/checkouts/readthedocs.org/user_builds/volttron/envs/releases-8.1.1/lib/python3.6/site-packages/sphinx/__main__.py', '-T', '-b', 'readthedocssinglehtmllocalmedia', '-d', '_build/doctrees', '-D', 'language=en', '.', '_build/localmedia'])[source]¶: Main method called by the eggsecutable.

SQL Aggregate Historian¶

An aggregate historian computes aggregates of data stored in a given volttron historian's data store. It runs periodically to compute aggregate data and store it in new tables/collections in the historian's data store. Each historian implementation would use a corresponding aggregate historian to compute and store aggregates.

Aggregates can be defined for a specific time interval and can be calculated for one or more topics. For example, 15 minute average of topic1 or 15 minute average of values of topic1 and topic2. Current version of this agent only computes aggregates supported by underlying data store. When aggregation is done over more than one topic a unique aggregation topic name should be configured by user. This topic name can be used in historian's query api to query the collected aggregate data.

Note: This agent doesn't not compute dynamic aggregates. It is only useful when you know what kind of aggregate you would need before hand and have them be collected periodically so that retrieval of that data at a later point would be faster

Data flow between historian and aggregate historian¶

Historian collects data from devices and stores it in its data store
Aggregate historian periodically queries historian's data store for data within configured time period.
Aggregate historian computes aggregates and stores it in historian's data store
Historian's query api queries aggregate data when used with additional parameters - agg_type, agg_period

Configuration¶

{
    # configuration from mysql historian - START
    "connection": {
        "type": "mysql",
        "params": {
            "host": "localhost",
            "port": 3306,
            "database": "test_historian",
            "user": "historian",
            "passwd": "historian"
        }
    },
    # configuration from mysql historian - END
    # If you are using a differnt historian(sqlite3, mongo etc.) replace the
    # above with connection details from the corresponding historian.
    # the rest of the configuration would be the same for all aggregate
    # historians

    "aggregations":[
        # list of aggregation groups each with unique aggregation_period and
        # list of points that needs to be collected. value of "aggregations" is
        # a list. you can configure this agent to collect multiple aggregates.
        # aggregation_time_periiod + aggregation topic(s) together uniquely
        # identify an aggregation

        {
            # can be minutes(m), hours(h), weeks(w), or months(M)

            "aggregation_period": "1m",

            # Should aggregation period align to calendar time periods.
            # Default False
            # Example,
            # if "aggregation_period":"1h" and "use_calendar_time_periods": False
            # example periods: 10.15-11.15, 11.15-12.15, 12.15-13.15 etc.
            # if "aggregation_period":"1h" and "use_calendar_time_periods": True
            # example periods: 10.00-11.00, 11.00-12.00, 12.00-13.00 etc.

            "use_calendar_time_periods": "true",

            # topics to be aggregated

            "points": [
                    {
                    # here since aggregation is done over a single topic name
                    # same topic name is used for the aggregation topic
                    "topic_names": ["device1/out_temp"],
                    "aggregation_type": "sum",
                    #minimum required records in the aggregation time period for aggregate to be recorded
                    "min_count": 2
                    },
                    {
                    "topic_names": ["device1/in_temp"],
                    "aggregation_type": "sum",
                    "min_count": 2
                    }
                ]
        },
        {
            "aggregation_period": "2m",
            "use_calendar_time_periods": "false",
            "points": [
                {
                 # aggregation over more than one topic so aggregation_topic_name should be specified
                 "topic_names": ["Building/device/point1", "Building/device/point2"],
                 "aggregation_topic_name":"building/device/point1_2/month_sum",
                 "aggregation_type": "avg",
                 "min_count": 2
                }
            ]
        }
    ]
}

SQLHistorian¶

sqlhistorian package¶

sqlhistorian.historian module¶

class sqlhistorian.historian.MaskedString[source]¶: Bases: str

class sqlhistorian.historian.SQLHistorian(connection, tables_def=None, **kwargs)[source]¶

Bases: volttron.platform.agent.base_historian.BaseHistorian

This is a historian agent that writes data to a SQLite or Mysql database based on the connection parameters in the configuration. .. seealso:

- :py:mod:`volttron.platform.dbutils.basedb`
- :py:mod:`volttron.platform.dbutils.mysqlfuncts`
- :py:mod:`volttron.platform.dbutils.sqlitefuncts`

get_dbfuncts_object()[source]¶

historian_setup()[source]¶: Optional setup routine, run in the processing thread before main processing loop starts. Gives the Historian a chance to setup connections in the publishing thread.

manage_db_size(history_limit_timestamp, storage_limit_gb)[source]¶: Optional function to manage database size.

publish_to_historian(to_publish_list)[source]¶

Main publishing method for historian Agents.

Parameters: to_publish_list (list) – List of records

to_publish_list takes the following form:

[
    {
        'timestamp': timestamp1.replace(tzinfo=pytz.UTC),
        'source': 'scrape',
        'topic': "pnnl/isb1/hvac1/thermostat",
        'value': 73.0,
        'meta': {"units": "F", "tz": "UTC", "type": "float"}
    },
    {
        'timestamp': timestamp2.replace(tzinfo=pytz.UTC),
        'source': 'scrape',
        'topic': "pnnl/isb1/hvac1/temperature",
        'value': 74.1,
        'meta': {"units": "F", "tz": "UTC", "type": "float"}
    },
    ...
]

The contents of meta is not consistent. The keys in the meta data values can be different and can change along with the values of the meta data. It is safe to assume that the most recent value of the “meta” dictionary are the only values that are relevant. This is the way the cache treats meta data.

Once one or more records are published either BaseHistorianAgent.report_all_handled() or BaseHistorianAgent.report_handled() must be called to report records as being published.

query_aggregate_topics()[source]¶

This function is called by BaseQueryHistorianAgent.get_aggregate_topics() to find out the available aggregates in the data store

Returns: List of tuples containing (topic_name, aggregation_type, aggregation_time_period, metadata)
Return type: list

query_historian(topic, start=None, end=None, agg_type=None, agg_period=None, skip=0, count=None, order='FIRST_TO_LAST')[source]¶

This function is called by BaseQueryHistorianAgent.query() to actually query the data store and must return the results of a query in the following format:

Single topic query:

{
"values": [(timestamp1, value1),
            (timestamp2:,value2),
            ...],
 "metadata": {"key1": value1,
              "key2": value2,
              ...}
}

Multiple topics query:

{
"values": {topic_name:[(timestamp1, value1),
            (timestamp2:,value2),
            ...],
           topic_name:[(timestamp1, value1),
            (timestamp2:,value2),
            ...],
            ...}
 "metadata": {} #empty metadata
}

Timestamps must be strings formatted by volttron.platform.agent.utils.format_timestamp().

“metadata” is not required. The caller will normalize this to {} for you if it is missing.

Parameters

topic (str or list) – Topic or list of topics to query for.
start (datetime) – Start of query timestamp as a datetime.
end (datetime) – End of query timestamp as a datetime.
agg_type – If this is a query for aggregate data, the type of aggregation ( for example, sum, avg)
agg_period – If this is a query for aggregate data, the time period of aggregation
skip (int) – Skip this number of results.
count (int) – Limit results to this value. When the query is for multiple topics, count applies to individual topics. For example, a query on 2 topics with count=5 will return 5 records for each topic
order (str) – How to order the results, either “FIRST_TO_LAST” or “LAST_TO_FIRST”

Returns

Results of the query

Return type

dict

query_topic_list()[source]¶

This function is called by BaseQueryHistorianAgent.get_topic_list() to actually topic list from the data store.

Returns: List of topics in the data store.
Return type: list

query_topics_by_pattern(topic_pattern)[source]¶

Find the list of topics and its id for a given topic_pattern

Returns: returns list of dictionary object {topic_name:id}

query_topics_metadata(topics)[source]¶

This function is called by BaseQueryHistorianAgent.get_topics_metadata() to find out the metadata for the given topics

Parameters: topics (str or list) – single topic or list of topics
Returns: dictionary with the format

{topic_name: {metadata_key:metadata_value, ...},
topic_name: {metadata_key:metadata_value, ...} ...}

Return type: dict

version()[source]¶: Return the current version number of the historian :return: version number

sqlhistorian.historian.historian(config_path, **kwargs)[source]¶

This method is called by the sqlhistorian.historian.main() to parse the passed config file or configuration dictionary object, validate the configuration entries, and create an instance of SQLHistorian :param config_path: could be a path to a configuration file or can be a

dictionary object

Parameters: kwargs – additional keyword arguments if any
Returns: an instance of sqlhistorian.historian.SQLHistorian

sqlhistorian.historian.main(argv=['/home/docs/checkouts/readthedocs.org/user_builds/volttron/envs/releases-8.1.1/lib/python3.6/site-packages/sphinx/__main__.py', '-T', '-b', 'readthedocssinglehtmllocalmedia', '-d', '_build/doctrees', '-D', 'language=en', '.', '_build/localmedia'])[source]¶: Main entry point for the agent.

SQLHistorian¶

This is a historian agent that writes data to a SQLite, Mysql, Postgres, TimeScale, or Redshift database based on the connection parameters in the configuration. The sql historian has been programmed to allow for inconsistent network connectivity (automatic re-connection to tcp based databases). All additions to the historian are batched and wrapped within a transaction with commit and rollback functions properly implemented. This allows the maximum throughput of data with the most protection

Common Configurations¶

All SQLHistorians support two parameters

connection - This is a mandatory parameter with type indicating the type of sql historian (ex. mysql, sqlite, etc.) and params containing the connection parameters specific to the connecting database type.
tables_def - Optional parameter to provide custom table names for topics, data, and metadata. This is useful when you want to use more than one instance of sqlhistorian with the same database

Example:

JSON format :

{
    "connection": {
        # type should be sqlite
        "type": "sqlite",
        "params": {
            "database": "data/historian.sqlite",
        }
    }
    "tables_def":  {
        # prefix for data, topics, and (in version < 4.0.0 metadata tables)
        # default is ""
        "table_prefix": "",
        # table name for time series data. default "data"
        "data_table": "data",
        # table name for list of topics. default "topics"
        "topics_table": "topics",
        # table name mapping topic to metadata. default "meta"
        # In sqlhistorian version >= 4.0.0 metadata is stored in topics table
        "meta_table": "meta"
    }
}

MySQL¶

Installation notes¶

In order to support timestamp with microseconds you need at least MySql 5.6.4. Please see this MySql documentation for more details
The mysql user must have SELECT INSERT, and DELETE privileges to the historian database tables.
SQLHistorianAgent can create the database tables the first time it runs if the database user has CREATE privileges. But we recommend this only for development/test environments. For all other use cases, use the mysql-create*.sql script to create the tables and then start agent. This way database user used by VOLTTRON historian can work with minimum required privileges

Dependencies¶

In order to use mysql one must install the mysql-python connector

From an activated shell execute

pip install mysql-connector-python-rf

On Ubuntu 16.04

pip install does not work. Please download the connector from https://launchpad.net/ubuntu/xenial/+package/python-mysql.connector and follow instructions on README

Configuration¶

The following is a minimal configuration file for using a MySQL based historian. Other options are available and are documented http://dev.mysql.com/doc/connector-python/en/connector-python-connectargs.html. Not all mysql connection parameters have been tested, use at your own risk. The configurations can be provided in JSON format or yml format

JSON format :

{
    "connection": {
        # type should be "mysql"
        "type": "mysql",
        # additional mysql connection parameters could be added but
        # have not been tested
        "params": {
            "host": "localhost",
            "port": 3306,
            "database": "volttron",
            "user": "user",
            "passwd": "pass"
        }
    }
}

YML format :

connection:
    type: mysql
    params:
        host: localhost
        port: 3306
        database: test_historian
        user: historian
        passwd: historian

SQLite3¶

An Sqlite historian provides a convenient solution for under powered systems. The database parameter is a location on the file system. By default it is relative to the agents installation directory, however it will respect a rooted or relative path to the database.

Configuration¶

{
    "connection": {
        # type should be sqlite
        "type": "sqlite",
        "params": {
            "database": "data/historian.sqlite",
        }
    }
}

PostgreSQL and Redshift¶

Installation notes¶

The PostgreSQL database driver supports recent PostgreSQL versions. It was tested on 10.x, but should work with 9.x and 11.x.
The user must have SELECT, INSERT, and UPDATE privileges on historian tables.
The tables in the database are created as part of the execution of the SQLHistorianAgent, but this will fail if the database user does not have CREATE privileges.
Care must be exercised when using multiple historians with the same database. This configuration may be used only if there is no overlap in the topics handled by each instance. Otherwise, duplicate topic IDs may be created, producing strange results.
Redshift databases do not support unique constraints. Therefore, it is possible that tables may contain some duplicate data. The Redshift driver handles this by using distinct queries. It does not remove duplicates from the tables.

Dependencies¶

The PostgreSQL and Redshift database drivers require the psycopg2 Python package.

From an activated shell execute:

pip install psycopg2-binary

Configuration¶

The following are minimal configuration files for using a psycopg2-based historian. Other options are available and are documented http://initd.org/psycopg/docs/module.html Not all parameters have been tested, use at your own risk.

Local PostgreSQL Database¶

The following snippet demonstrates how to configure the SQLHistorianAgent to use a PostgreSQL database on the local system that is configured to use Unix domain sockets. The user executing volttron must have appropriate privileges.

    {
        "connection": {
            "type": "postgresql",
            "params": { "dbname": "volttron" }
        }
    }

#### Remote PostgreSQL Database

The following snippet demonstrates how to configure the
SQLHistorianAgent to use a remote PostgreSQL database.

{
    "connection": {
        "type": "postgresql",
        "params": {
            "dbname": "volttron",
            "host": "historian.example.com",
            "port": 5432,
            "user": "volttron",
            "password": "secret" }
    }
}

TimescaleDB Support¶

Both of the above PostgreSQL connection types can make use of TimescaleDB's high performance Hypertable backend for the primary timeseries table. The agent assumes you have completed the TimescaleDB installation and setup the database by following the instructions here: https://docs.timescale.com/latest/getting-started/setup To use, simply add 'timescale_dialect: true' to the connection params in the Agent Config as below

{
    "connection": {
        "type": "postgresql",
        "params": {
            "dbname": "volttron",
            "host": "historian.example.com",
            "port": 5432,
            "user": "volttron",
            "password": "secret" ,
            "timescale_dialect": true }
    }

}

Redshift Database¶

The following snippet demonstrates how to configure the SQLHistorianAgent to use a Redshift database.

{
    "connection": {
        "type": "redshift",
        "params": {
            "dbname": "volttron",
            "host": "historian.example.com",
            "port": 5432,
            "user": "volttron",
            "password": "secret" }
    }
}

Notes¶

Do not use the "identity" setting in configuration file. Instead use the new method provided by the platform to set an agent's identity. See scripts/core/make-sqlite-historian.sh for an example of how this is done. Setting a historian's VIP IDENTITY from its configuration file will not be supported after VOLTTRON 4.0. Using the identity configuration setting will override the value provided by the platform. This new value will not be reported correctly by 'volttron-ctl status'

SQLiteTaggingService¶

sqlite package¶

sqlite.tagging module¶

class sqlite.tagging.SQLiteTaggingService(connection, table_prefix=None, **kwargs)[source]¶

Bases: volttron.platform.agent.base_tagging.BaseTaggingService

This is a tagging service agent that writes data to a SQLite database.

insert_topic_tags(tags, update_version=False)[source]¶

Add tags to multiple topics.

Parameters

tags (dict) –
dictionary object or file containing the topic and the tag details. dictionary object or the file content should be of the format:
```
<topic_name or prefix or topic_name pattern>: {<valid
tag>:<value>, ... }, ... }
```
update_version (bool) – True/False. Default to False. If set to True and if any of the tags update an existing tag value the older value would be preserved as part of tag version history. Note: this feature is not implemented in the current version of sqlite and mongodb tagging service.

load_tag_refs()[source]¶: Called right after setup to load a dictionary of reference tags and its corresponding parent tag. Implementing methods should load self.tag_refs with tag and parent tag information

load_valid_tags()[source]¶: Called right after setup to load a dictionary of valid tags. It should load self.valid_tags with tag and type information

query_categories(include_description=False, skip=0, count=None, order='FIRST_TO_LAST')[source]¶

Get the available list tag categories. category can have multiple tags and tags could belong to multiple categories

Parameters

include_description (bool) – indicate if result should include available description for categories returned
skip (int) – number of tags to skip. usually used with order
count (int) – limit on the number of tags to return
order (str) – order of result - “FIRST_TO_LAST” or “LAST_TO_FIRST”

Returns

list of category names if include_description is False, list of (category name, description) if include_description is True

Return type

query_tags_by_category(category, include_kind=False, include_description=False, skip=0, count=None, order='FIRST_TO_LAST')[source]¶

Get the list of tags for a given category name. category can have multiple tags and tags could belong to multiple categories

Parameters

category (str) – name of the category for which associated tags should be returned
include_kind (bool) – indicate if result should include the kind/datatype for tags returned
include_description (bool) – indicate if result should include available description for tags returned
skip (int) – number of tags to skip. usually used with order
count (int) – limit on the number of tags to return
order (str) – order of result - “FIRST_TO_LAST” or “LAST_TO_FIRST”

Returns

Will return one of the following

list of tag names
list of (tags, its data type/kind) if include_kind is True
list of (tags, description) if include_description is True
list of (tags, its data type/kind, description) if include_kind is True and include_description is true

Return type

query_tags_by_topic(topic_prefix, include_kind=False, include_description=False, skip=0, count=None, order='FIRST_TO_LAST')[source]¶

Get the list of tags for a given topic prefix or name.

Parameters

topic_prefix (str) – topic_prefix for which associated tags should be returned
include_kind (bool) – indicate if result should include the kind/datatype for tags returned
include_description (bool) – indicate if result should include available description for tags returned
skip (int) – number of tags to skip. usually used with order
count (int) – limit on the number of tags to return
order (str) – order of result - “FIRST_TO_LAST” or “LAST_TO_FIRST”

Returns

Will return one of the following

list of (tag name, value)
list of (tag name, value, data type/kind) if include_kind is True
list of (tag name, value, description) if include_description is True
list of (tags, value, data type/kind, description) if include_kind is True and include_description is true

Return type

query_topics_by_tags(ast, skip=0, count=None, order=None)[source]¶

Get list of topic names and topic name prefixes based on query condition. Query condition is passed as an abstract syntax tree.

Parameters

ast (tuple) –
Abstract syntax tree that represents conditional statement to be used for matching tags. The abstract syntax tree represents query condition that is created using the following specification

Query condition is a boolean expression that contains one or more query conditions combined together with an “AND” or “OR”. Query conditions can be grouped together using parenthesis. Each condition in the expression should conform to one of the following format:
1. <tag name/ parent.tag_name> <binary_operator> <value>
2. <tag name/ parent.tag_name>
3. <tag name/ parent.tag_name> LIKE <regular expression within single quotes
4. the word NOT can be prefixed before any of the above three to negate the condition.
5. expressions can be grouped with parenthesis. For example
  condition="(tag1 = 1 or tag1 = 2) and (tag2 < '' and tag2 > '') and tag3 and (tag4 LIKE '^a.*b$')" condition="NOT (tag5='US' OR tag5='UK') AND NOT tag3 AND NOT (tag4 LIKE 'a.*')" condition="campusRef.geoPostalCode='20500' and equip and boiler"
skip (int) – number of tags to skip. usually used with order
count (int) – limit on the number of tags to return
order (str) – order of result - “FIRST_TO_LAST” or “LAST_TO_FIRST”

Returns

list of topics/topic_prefix that match the given query conditions

Return type