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 interfaceusername
- User’s username for the Obix remote APIpassword
- 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:
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.