Skip to content

Quickstart guide for Plaid

This section will describe the quickest way to get Plaid running, inspect the messages and start using OpenADR. We recommend reviewing the Conceptual Overview before getting started.

You will require either the Plaid source code or binaries, and access to the cloud VTN. Please email support@gridfabric.zendesk.com if you don't have access to these.

This guide will walk the user through the most basic end to end implementation of Plaid, connecting to GridFabric's Cloud VTN, to provide the user a basis for which to complete their own implementation.

Accessing software packages

If you have purchased a license for Plaid, you will be granted access to the Plaid source code and cloud VTN.

If you would like to test out Plaid functionality using our pre-built binarines before buying, please email support@gridfabric.zendesk.com with a description of your use case.

Certificates

For most OpenADR implementations you will need to use TLS certificates for every VEN that you run. They are needed to connect to the test VTN, but you can use free test certificates. To download the test certificates and bundle them in Plaid, follow the guide for generating test certificates then move to the next step.

Prepare an endpoint to test callback functions

Any service that allows you track http messages to an endpoint will work for this quickstart. For ease of use, we have had success with webhook.site. We will use this to demonstrate the callback functions the Plugin calls during operation. By default, webhook.site will create a new endpoint for you. Copy that url for the next step.

Other options

Other endpoint sites are fine to use (e.g. beeceptor, requestbin), but webhook.site we found to be easiest out of the box because you don't need an account and by default it responds with a blank response. When Plaid receives a blank response, it will use default behavior. If it receives a response with data in it, but that data doesn't match the expected format, it will error. So use an endpoint site that either allows you to edit the response, or provides a blank response.

Alternatively, you can set up a simple server locally to receive POST messages. We have provided a basic server implementation in nodejs that you may run locally, or use as inspiration: https://github.com/gridfabric/nodejs-sample-middleware.

Update configuration file

If you are using the source code, the sample config file is in /plaid/plaid/config/config.json.sample. Rename it to config.json as you make the updates. For the binaries, it is simply in the config.json file.

The fields to update in this file are as follows. Note that the example is for the source code. Update the file paths accordingly for the binary. They are not nested in the binary file download. 

{
    "oadr": {
        "venName": "my_test_ven", // update to whichever name you prefer
        "vtnUrl": "https://canvas.gridfabric.io:4433/oadrapi/ven/<base_url>",
            //update base_url to whatever your instance of the VTN is set to
        "tls": {
            "enable": true,
            //all paths in the config file are with respect to where the executable 
            //will run, in this case that is in /build/debug/
            "capath": "../../cacerts/ven_cacerts_test.pem", 
                //CA certificate files - in production you will use prod
            "keypath": "../../certs/privkey.pem", 
                //This is the privkey.pem file you put in the certs folder
            "certpath": "../../certs/certchain.pem" 
                //This is the concatenated file you created in the prior step
        },
        "marketContexts": [ ".*" ] 
            // market context will be explained more later on - this will capture any market context
            //For certification testing, this should be ["http://MarketContext1", "http://MarketContext2"]
    },
    "plugin": {
        "pluginPath": "plaidven-notifierhttp-plugin.so", 
            //this is the standard plugin that ships with Plaid. The file extension 
            //needs to be added depending on if you are using windows or linux.
        "instanceId": "my-quickstart-ven", 
        //included in every plugin message, to be used for differentiating
        //instances of Plaid
        "endpoints": {
            "event": {
                "startEventInterval": " https://webhook.site/da9e0968-8e58-47b8-ae8a-bb91508a90e7",
                "endEvent": "   https://webhook.site/da9e0968-8e58-47b8-ae8a-bb91508a90e7",
            }
            //the url copied from webhook.site (or something comparable)
        }
    }
}

Only startEventInterval and endEvent endpoints are needed for the quickstart. For all of the other endpoints, leave them blank by default (e.g. "startEvent": "") and Plaid will not try to use them - this simplifies your implementation until you are ready to tap into that functionality.

If ca certs are not available in your bundle, you can find the test cacerts file here.

Build & Run

If you are using the pre-built binaries, you may simply run ./plaidven schema.json config.json and skip to the end of this section. Make sure that you have the required dependencies installed locally however, and note that (e.g.) the 18.04 Linux binary will only work with Ubuntu 18.04 (if you would like to run it in a docker container, see the docker section).

If using the source code, now is time to build.

Depending on operating system, please follow the appropriate guide to build and run the software. Follow the "debug" build process.

Plaid should now be running locally and will be trying to connect to the VTN. You should see it logging that it is unable to connect and will see the following logged message, among some others. This is because the VTN has not been configured to accept the VEN.

Error executing job (will retry): ven.registration: Registration failed (will retry): 
    Registration exception: error code received: 452

Prepare and use the VTN

Now it's time to go to the VTN to complete the connection. Go to https://canvas.gridfabric.io/ and log in using your provided account information.

Add the VEN

Now to add the VEN. This will be quick because the VEN has already tried to register, so we can take a shortcut by finding the VEN in NOVA DRE.

Go to the VENs section and Failed Registrations Tab. You should see your VEN show up there with all it's information, now you just need to add it to the VTN by clicking "New VEN".

Failed Registration Screenshot

On the next screen, just click the Create VEN - you don't need to update any fields here (a random VEN ID will be assigned).

After you create the VEN, you should see back in your Plaid Log that it has registered, with a message that says: VEN Registered.

Your VEN should now be registered.

Create an Event

Now it is time to finish it off by creating an event and seeing it propagate through the VEN.

Update market context

The first thing to do is update the market context. This will be explained in more detail in the VTN guide. For now just create a default market context and click Save. Fill in whatever you like for Description and Color - these aren't used.

VTN market context screenshot

Create Event

Now create the event. Go to the Events section and click on the "Create Event" button. In the modal that shows up, click "Standard".

create event screenshot

On the next screen, you'll see a number of fields. You only need to update:

  • start time: set to near in the future (e.g. a few minutes out). By default, start time is set to the current time, so you just need to add a few minutes.
  • duration: set to less than 10 minutes - we will do a quick event so you can see it start and end.
  • event signal type & payload: set to LEVEL and 2, respectively.

Now click "Create Event".

add event details screenshot

The Event is still a draft and not yet published. Before publishing, you need to add a target. Click on the "Target" tab. In the box, find the VEN that you added, and include it in "targets".

add event target screenshot

Now, go back to the "Publish" tab and click "Publish Event".

Next time the VEN polls, it will receive information about this event, and pass it through the plugin to the endpoint. After the event has started and completed, you should see the messages populated in the webhook.site stream. You will see messageType OnEventIntervalStart posted to the endpoint when the event starts, and OnEventComplete posted when the event is over.

If you click on the event, you will see the payload delivered that describes the event. This is what will be parsed by your system.

That's all for the quick start. To recap:

  • You configured, built, and ran your first VEN
  • You connected it to a VTN
  • You created an event and propagated it through the VEN

See the rest of the Implementation Guide to find details on all of the functionality that you will need to achieve OpenADR certification and connect to load shifting programs.