Obix Driver

Obix Driver Configuration

VOLTTRON’s uses Obix’s restful interface to facilitate communication.

This driver does not handle reading data from the history section of the interface. If the user wants data published from the management systems historical data use the Obix History agent.

Driver Configuration

There are three arguments for the driver_config section of the device configuration file:

  • url - URL of the Obix remote API interface

  • username - User’s username for the Obix remote API

  • password - Users’ password corresponding to the username

Here is an example device configuration file:

{
    "driver_config": {"url": "http://example.com/obix/config/Drivers/Obix/exports/",
                      "username": "username",
                      "password": "password"},
    "driver_type": "obix",
    "registry_config":"config://registry_configs/obix.csv",
    "interval":     30,
    "timezone": "UTC"
}

A sample Obix configuration file can be found in the VOLTTRON repository in examples/configurations/drivers/obix.config

Obix Registry Configuration File

The registry configuration file is a CSV file. Each row configures a point on the device.

The following columns are required for each row:

  • Volttron Point Name - The name by which the platform and agents running on the platform will refer to this point. For instance, if the Volttron Point Name is HeatCall1 then an agent would use <device topic>/HeatCall1 to refer to the point when using the RPC interface of the actuator agent.

  • Obix Point Name - Name of the point on the Obix interface. Escaping of spaces and dashes for use with the interface is handled internally.

  • Obix Type - One of bool, int, or real

  • Units - Used for meta data when creating point information on the historian.

  • Writable - Either TRUE or FALSE. Determines if the point can be written to. Only points labeled TRUE can be written to through the ActuatorAgent. This can be used to protect points that should not be accessed by the platform.

The following column is optional:

  • Default Value - The default value for the point. When the point is reverted by an agent it will change back to this value. If this value is missing it will revert to the last known value not set by an agent.

Any additional columns will be ignored. It is common practice to include a Point Name or Reference Point Name to include the device documentation’s name for the point and Notes and Unit Details for additional information about a point.

The following is an example of a Obix registry configuration file:

Obix

Volttron Point Name

Obix Point Name

Obix Type

Units

Writable

Notes

CostEL

CostEL

real

dollar

FALSE

Precision: 2

CostELBB

CostELBB

real

dollar

FALSE

Precision: 2

CDHEnergyHeartbeat

CDHEnergyHeartbeat

real

null

FALSE

ThermalFollowing

ThermalFollowing

bool

FALSE

CDHTestThermFollow

CDHTestThermFollow

bool

FALSE

CollegeModeFromCDH

CollegeModeFromCDH

real

null

FALSE

Precision: 0, Min: 3.0, Max: 3.0

HospitalModeFromCDH

HospitalModeFromCDH

real

null

FALSE

Precision: 0, Min: 3.0, Max: 3.0

HomeModeFromCDH

HomeModeFromCDH

real

null

FALSE

Precision: 0, Min: 3.0, Max: 3.0

CostNG

CostNG

real

null

FALSE

Precision: 2

CollegeBaseloadSPFromCDH

CollegeBaseloadSPFromCDH

real

kilowatt

FALSE

Precision: 0

CollegeImportSPFromCDH

CollegeImportSPFromCDH

real

kilowatt

FALSE

Precision: 0

HospitalImportSPFromCDH

HospitalImportSPFromCDH

real

kilowatt

FALSE

Precision: 0

HospitalBaseloadSPFromCDH

HospitalBaseloadSPFromCDH

real

kilowatt

FALSE

Precision: 0

HomeImportSPFromCDH

HomeImportSPFromCDH

real

kilowatt

FALSE

Precision: 0

ThermalFollowingAlarm

ThermalFollowingAlarm

bool

FALSE

A sample Obix configuration can be found in the VOLTTRON repository in examples/configurations/drivers/obix.csv

Automatic Obix Configuration File Creation

A script that will automatically create both a device and register configuration file for a site is located in the repository at scripts/obix/get_obix_driver_config.py.

The utility is invoked with the command:

python get_obix_driver_config.py <url> <registry_file> <driver_file> -u <username> -p <password>

If either the registry_file or driver_file is omitted the script will output those files to stdout.

If either the username or password arguments are left out the script will ask for them on the command line before proceeding.

The registry file produced by this script assumes that the Volttron Point Name and the Obix Point Name have the same value. Also, it is assumed that all points should be read only. Users are expected to fix this as appropriate.