Skip to content

Configuring Plaid

The config file contains important configurations that will need to be updated for every implementation of Plaid. At a minimum, fields such as vtnID, venID and tls fields within the oadr section will need to be updated for each new VEN.

A sample configuration can be found in <rootdir>/plaid/plaid/config/config.json.sample.

Using the default configuration file, Plaid won't be configured to connect to a VTN. At a minimum, the venName and vtnUrl will need to be modified.

Config in the command line

Settings in the config file can be overridden from the command line by passing additional parameters after the configuration file parameter. The config override options have the following format:

--object.path.in.config=value

Here's an example of setting the vtnUrl and venName from the command line:

plaid <path/to/schema.json> <path/to/config.json> --oadr.vtnUrl=http://localhost:3000 --oadr.venName=newVenName

Config file description

The remainder of this document provides a description for each field in the configuration file.

  • startPollThread (boolean) : if true, start the poll thread on startup
  • heartbeat : Plaid will emit a periodic heartbeat through the default plugin, which the following parameters relate to:
    • enable (boolean): enable / disable heartbeat
    • callbackIntervalSeconds (uint): seconds between heartbeat
  • oadr : The following parameters are related to the oadr communication
    • venName (string) : VEN name supplied by VTN maintainer.
    • venId (string) : VEN ID supplied by the VTN maintainer. If included, this VEN ID will always be present when registering with the VTN.
    • registrationId (string) : Registration ID supplied by the VTN maintainer. If included, this registration ID will be present when registering with the VTN.
    • vtnId (string) : Not used; ignore this parameter.
    • vtnUrl (string) : HTTP path to the VTN. This string must begin with http or https.
    • tls : The following fields refer to subfields of the tls object
      • enable (boolean) : Set to true to enable TLS security. If enabled, all of the following fields should have values and the VTN URL should begin with https.
      • capath (string) : File system path to the CA file in PEM format. These will be provided in your source code in the cacerts folder, or can be downloaded from here (test certchain) and here (production certchain).
      • keypath (string) : File system path to the key file in PEM format. This will be added after downloading from Eonti or Kyrio (explained here), the suggestion is to put it in a certs folder.
      • certpath (string) : File system path the certificate file in PEM format (This is a concatenation of 3 PEM files). This will be added after downloading from Eonti or Kyrio (explained here), the suggestion is to put it in a certs folder.
      • verifyHostname (boolean) : If true, the TLS library will validate the expiration date of the server certificate, and that the common name in the certificate matches the host part of the VTN URL parameter.
      • cipherList (string) : List of supported cipher suites. Under most circumstances this field should be left to the default value of: AES128-SHA256:ECDHE-ECDSA-AES128-SHA256. If curl is built with an SSL library other than OpenSSL, this list may need to be updated accordingly.
      • tlsVersion (string) : Selects the TLS version. Under most circumstances, this field should be left at the default value of TLSv1_2. Other supported values are: TLSv1, SSLv2, SSLv3, TLSv1_0, TLSv1_1, and TLSv1_2
    • httpAuth : If enabled, will create an Authorization header with the encoded username and password to authenticate with the VTN. Username/password based auth is not part of the OpenADR 2.0b spec, but may be found in some older VTN implementations. By default this should not be enabled and TLS is used instead.
    • marketContexts (array of RegEx strings) : Lists the MarketContexts the VEN matches against. Market contexts which don't match the list will be rejected. You may use ".*" to capture all market contexts.
    • signals (array of RegEx strings) : Lists the signalName.signalType the VEN matches against. Signals not matched by the list will be rejected by the VEN. When searching for a match, the signal name and type from the event are concatenated with a period separator. A signal with name SIMPLE and type x-Custom becomes: SIMPLE.x-Custom. Regular expressions should match that format. The signals supported by OpenADR are included by default. You may use ".*" to accept all signal types"
    • persistIds (boolean) : Reuse VEN ID and Registration ID received from the VTN on subsequent registrations, and persist to the config file
  • plugin : Plaid is extended through plugins which implement an interface that accepts callbacks from Plaid
    • pluginPath (string) : Path to the plugin shared library (.so on Linux, .dll on Windows)
    • deadLetterPollInSeconds (uint) : time until plugin callbacks are sent to dead letter
    • instanceId (string) : the ID this instance of Plaid will use in every plugin message. instanceID should be used to differentiate your different instances of Plaid, as it is completely internal and controlled by you. venName, venID and vtnID may be set by the VTN and therefore are not reliable.
    • tls : the same configuration as tls fields above. If enable=false, or fields are not filled out, defaults will be used. These fields can be used to customize the TLS certificates used for communication with your system.
    • httpAuth : If enabled, will create an Authorization header with the encoded username and password, e.g. username/password of aladdin/opensesame creates a base64 encoded string of YWxhZGRpbjpvcGVuc2VzYW1l and the header will be Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l.
    • httpHeaders : An array of header pairs in string form that will be added http POSTs from the plugin. E.g. "httpHeaders": [ “HeaderName1: HeaderValue1”, “HeaderName2: HeaderValue2"]
    • parameters : An array of key value pairs that will be accessible as parameters in the plugin. They will be accessible in the plugin, for example by calling config.plugin.parameters[0].key. This provides an easy way to add parameters for plugin development (e.g. endpoints, queue names, etc.)
    • endpoints : A set of endpoints for the plugin callbacks, described in the plugin guide
  • listener : The listener listens for API requests (to the plaid api). Messages exchanged over the listener are formatted as json. WARNING: there is no security placed on the listener: care should be taken in securing access to this port.
    • enabled (boolean) : If true, the listener will be started on the port and ip address listed below.
    • port (integer) : If running as a regular user, the port must be a value greater than 1024.
    • ip (string) : Set to 127.0.0.1 to listen on localhost only, or to 0.0.0.0 to listen on all interfaces.
  • log : Log file settings
    • stdout (boolean) : If true, messages will be logged to stdout.
    • filename (string) : File system path to the log file.
    • flushIntervalInSeconds (integer) : Time in seconds before log buffer is flushed to file.
    • filter : Log filter
    • rotate : Settings to limit log size and rotate log files
      • enable (boolean) : Enable or disable log rotate settings
      • maxSizeInBytes (uint) : Number of bytes to limit log to
      • fileCount (uint) : Number of log files to use in rotate
  • timeouts : Timeouts in seconds that the plugin will wait for a response
    • connect (integer) : Sets the curl CURLOPT_CONNECTTIMEOUT option
    • request (integer) : Sets the curl CURLOPT_TIMEOUT option
  • retries
    • retryIntervalInSeconds (integer) : Time interval in seconds to wait before retrying a failed job. Callbacks which throw an exception will be retried at this interval.