Concepts

Some of the terminology used in CHORDS is described here.

URL Uniform Resource Locator: simply the same old Internet address and qualifiers that you are used to typing into the address bar of a browser. All CHORDS transactions are made via URLs.
Site A geographic location, which may host one or more instruments. It is the only place where geographic coordinates are specified, so if you need to identify a unique location for an instrument, it must be assigned to a distinct site.
Instrument A source of related measurements. Typically it is one device, but you can designate multiple devices as a single instrument, or you can divide the measurements from a single device among multiple instruments, if this results in a more appropriate data organization.
Variable A particular measurement made by an instrument, such as such as temperature, or pH. Variables have Short Names
Measurement A single observation of a Variable. Measurements are assigned to instruments, and each one has an associated time of observation. Typically, multiple measurements for the same instrument are submitted together, with a common time tag.
Short Name A compact identifier for a variable, which is used to represent it in a URL. This is done to keep URLs from becomming unreasonably long. For example, the short name for temperature might be assigned as t, pressure as p, etc. The short name should be as short as possible, but still be useful for identification.
Data URL The syntax used to submit and fetch data from the Portal. "Data URL" links, found on several pages of the Portal, take you to a page which provides examples for a particular instrument.
Format URL extensions usually indicate the type of data that will be returned to a data request:
.csv A comma separated data file.
.jsf A JSON file.
.xml An XML file.
.json A JSON string.
Simulation The CHORDS Portal provides a capability to simulate your instrument data delivery. This is invaluable for configuring and testing your Portal, even before you have instruments deployed. Data that are submitted under simulation are tagged as test values, and can easily be removed from the database.

The dashboard provides an overview of your system performance. It's the default view, accesible from the top level domain name, the CHORDS logo, and the Dashboard link.

  • The instrument links have status indicators which are green/red indicating if a measurement has been received within the nominal reporting interval for the instrument.
  • The most recent measurement URL is shown in the green box.
  • Three bar graphs show the number of measurements received for each instrument, over different time spans.
Dashboard

Clicking on an instrument link (from the dashboard or instrument page takes you to a page where you can monitor data from that instrument. You can also modify the instrument configuration.

  • Select the variables to be plotted by selecting them below the graph.
  • The time span and range can be adjusted with a drop down and slider.
  • The graph has live updates. When a new measurement is recieved, it is plotted.
  • The most recent URL received from the instrument is displayed in the green alert box.
  • Configuration parameters appear in green boxes. You can edit them directly, to change the setup for this instrument.
Dashboard

Configuration is used for managing many (but not all) of the portal characteristics. Sites, instruments, and variables are configured on their own specific pages.

  • You must be logged in with administrator access in order to modify the configuration.
  • Be sure to press the save button at the bottom of the configuration sections.
  • A backup copy of the configuration may be created and reloaded using the Export/Import Configuration buttons.
  • A backup copy of the time-series database may be created and reloaded using Export/Import Database buttons.
Dashboard

The top bar Data link takes you to a page where instrument data can be directly downloaded with a few button clicks. Old measurements can be trimmed from the database. Simple URLs can also be used by programs to fetch data.

  • You can download instrument data for selected days in various file formats.
  • Links are also provided to "Data URLs" pages, which describe how to construct a data request for each instrument.
  • Remember that data can also be fetched directly by programs. You don't have to download files.
Data

The top bar Geo link takes you to a geographical display of site locations.

  • A Google API credential is required in order to show google maps on a web site. Anyone with a Google account can create an API credential. The value is entered into the CHORDS configuration.
Data

Simulation allows you to test the configuration and operation of your portal. This test data can be easily deleted when testing is completed.

  • Simulation will not be available unless you are logged in with administrator access.
  • Select Simulator from the top bar to open the simulation page. It's best to right-click the link, and select "Open Link In New Tab".
  • You can individually toggle each intrument on/off.
  • URLs with simulated measurements will be sent to the Portal, at the nominal instrument data rate.
  • The "test" flag will be added to the measurements."
  • If the simulation window is closed or you navigate away from it, the simulation will end.
Simulate

Grafana is an open-source visualization system that allows you to create powerful data dashboards, right from the browser. The dashboards are very responsive because they fetch data directly from the CHORDS database. The extensive Grafana documentation explains how to unleash the full capability of the system.

However, the following tutorial explains quickly how to configure Grafana to interact with CHORDS, and how to create a simple dashboard.

Note: You should have the portal configured with at least one site/instrument/variable before trying to create a dashboard. If there is no data in the portal, you can create some test data using the simulation function.

Extra credit: once you have been able to make a simple Grafana graph, see this tutorial for indepth instructions on database access and calculations.

  1. Open Grafana

    The visualization link will open a new browser window which provides access to the Grafana time-series visualization system.

    Vis
  2. Login
    • Sign in to Grafana: Dashboard

  3. Creating a datasource
    • Add a data source: Dashboard
    • Configure the data source: Dashboard
    • When configured correctly, success will be indicated: Dashboard
    • If something is not configured correctly, you may see a message: "Unknown error": Dashboard
      • Make changes, and mash Save & Test again.

  4. Add a dashboard
    • Select New dashboard: Dashboard
    • A new dashboard is created, with an empty panel. Add a graph by pressing Graph: Dashboard
    • Click in the bar at the top of the graph, to pop up a menu: Dashboard
    • And select Edit: Dashboard

    • Configure the panel:
      Use the General tab to change set a title: Dashboard
      Use the Display tab to change the appearance: Dashboard
      The variable identifiers are obtained from the CHORDS Instruments page: Dashboard

      Use the Metrics tab to configure the database access. Close when you see plotted data:

      Dashboard

  5. Change the admin password
    • Finally, be sure to change (and remember) the admin password for grafana. This is accessed through Admin->Profile: Dashboard