Knowledge
homeappabout
English
English
  • Home
  • About Ardexa
    • Our Security Principles
    • What makes us different?
    • Collecting Data
    • Device Remote Control
    • Tunnel (VPN) Access
    • File Transfers
    • Machine Plugins
  • Getting Started
    • What is Ardexa?
    • Connectivity in 60 Seconds
    • The Ardexa Data Store
  • Configure the Edge Device
    • Edge and Cloud Connect
    • Edge Device Configuration
      • ArdexaLinux Operating System
      • Approved Hardware
        • Dell Industrial Computers
          • Dell PowerEdge Installation
        • Advantech Industrial Computers
          • Configuring Advantech Devices
            • UNO-2271G, UNO-2272G
            • UNO-2362G
          • Advantech ArdexaLinux Installation
          • Advantech Serial Driver
        • Siemens Industrial Computers
          • Siemens IPC 127E Installation
          • Siemens IOT2050 ArdexaLinux Installation
        • Raspberry Pi
          • Install the Raspbian Image
          • USB On-The-Go (OTG) support
          • Raspberry Pi 4 EEPROM update
          • Display hardware version of Raspberry Pi
        • Virtual machines
      • Internet Connection
        • Connecting
        • Complex Network Management
      • Networking
        • Network Configuration Using Ardexa Cloud
        • Config Static IP - Manually
        • Add static route
        • Add secondary IP
        • Access via SSH
        • Update password
        • Test Network Access
        • Reconnecting Offline Device
        • Cisco VPN Access
        • USB Tethering
      • Using a local Network Time server (NTP)
      • Serial Communications
        • Testing the serial ports
      • Antivirus
      • Time Zone
    • Connecting to Plant Equipment
      • TCP (Ethernet)
        • Standard Industrial Protocols
        • OPC Protocols
        • Database Protocols
        • PLC Protocols
        • Miscellaneous
      • Serial (RS-485, RS-422, RS-232)
        • Standard Industrial Protocols
        • Proprietary Protocols
      • Others (Bluetooth, etc.)
    • Ardexa Agent
      • Installation (ARM64 or X86/AMD64)
      • Installation Raspberry Pi
      • Install (opkg)
      • Install on Docker
      • Check it's working
      • Increase system limits
      • Data types and formats
        • Decimal
        • CSV file format
      • Scenarios
        • Run
        • How does the UNIX_SOCKET scenario work?
      • Dynamic Configuration
      • Manual Configuration
      • Replacing a Device with a New One
      • Replacing a Device with an Existing One
      • Uninstall
    • Ardexa Machine Plugins
      • Safety & Risk Notice
      • Modbus
        • Modbus Server
        • Modbus Python Plugin
        • Modbus Plugin
      • Programmable Logic Controllers (PLCs)
        • Access to OPC DA Data
        • Installing the OpenOPC utility
        • Mitsubishi PLC Plugin
        • Siemens S7 PLC Plugin
        • Omron PLC Plugin
        • README
      • OPC Plugins
        • OPCUA Plugin
      • Solar Inverter Plugins
        • Satcon Inverters
        • Sungrow Inverters
          • Sungrow SG Grid Scale Inverters
          • Sungrow SG1000MX Inverters
          • Sungrow SG String Inverters
        • Delta Inverters
        • Connecting to Huawei
        • Huawei Logger
        • Huawei Logger
        • ABB Inverters
          • Configuring ABB Inverters
          • ABB Aurora Inverters
          • ABB PowerOne Modbus Inverters
          • ABB Pro 33 Inverters
          • ABB PVS 800 Inverters
          • ABB Trio Inverters
        • SolarEdge Inverters
        • Sunspec Inverters
        • SMA Inverters
          • Connecting SMA Inverters
          • SMA Central Inverters
          • SMA Cluster Controllers
          • SMA "YASDI" Inverters
          • SMA Sunny Tripower (non Sunspec)
          • SMA Power Plant Controllers
          • SMA Central 1850-2750 Inverters
          • SMA Sunny Webbox
        • Kostal Inverters
          • Connecting via Kostal Proprietary Protocol
          • Kostal Proprietary Plugin
          • Kostal Modbus (non Sunspec) Plugin
        • Kaco Inverters
          • Configuring Kaco Inverters
          • Kaco Inverter Plugin
        • SolarMax Inverters
          • Configuring SolarMax Inverters
          • SolarMax Inverter Plugin
        • Refusol Inverters
        • JEMA IFX Inverters
        • Ginglong Solis Inverters
        • Growatt TL3 Inverters
        • HEC Freesun Inverters
        • Next Tracker Plugin
        • Ingecon 100TL Inverters
        • Tristart MPPT Charger
        • Zenergy PID Boxes
        • Eaton Inverters
        • SolarCheck Strings
        • Soltec Trackers
        • GE Inverters
        • TMEIC Solar Ware Ninja Inverters
        • Power Electronics Inverters
        • Ingeteam Inverters
        • Delta Logger
        • FTC Trackers
        • Trina Trackers
        • Solivia Inverters
        • Dunext Inverters
      • Data Logger Plugins
        • Connecting SolarLog
        • SolarLog Logger
        • MaxWeb Logger
        • Gantner Logger
        • MeteoControl Logger
        • Bluelog Logger
        • Kaco proLOG
        • Sinapsi Logger
        • Skylog Logger
        • SMA Sunny Webbox Logger
      • Electricity Meter Plugins
        • Janitza Meters
        • Cube Meters
        • ECS Meters
        • Gavazzi Meters
          • Gavazzi EM24 Meters
          • Gavazzi WM Meters
        • KBR Meters
        • Plus ES Meters
        • RPI Current Transformers
        • Schweitzer Meters
        • Schweitzer Protection Relays
        • Schneider Electric Meters
          • Schneider ION Meters
          • Schneider Sepam Meters
        • Fanox Relay
        • Elspec Meters
        • Landis Gyr Meter
      • Wind Turbines
        • Wind Park Networks
        • Vestas Wind Turbines
          • Vestas ODBC
          • Vestas OPCUA
        • Clavis XML Server
        • Gamesa Wind Turbines
          • Gamesa ODBC Wind Turbines Plugin
          • Gamesa Windnet OPCUA
          • Gamesa Wind Turbines via Config Files
        • Nordex Wind Turbines
          • Nordex OPCXML Wind Turbines Plugin
          • Nordex Plugin ODBC with Config Files
          • Nordex Plugin OPCXML with Config Files
        • Enercon Wind Turbines
          • Enercon Wind Turbines Plugin
          • Enercon Wind Turbines Plugin with Config Files
        • GE ODBC Wind Turbines
        • Senvion Wind Turbines
          • Senvion Wind Turbines Plugin
          • Senvion Plugin with Config Files
        • Siemens Wind Turbines
          • Siemens Wind Turbines
          • Siemens Wind Turbines with Config Files
      • Weather Stations
        • Kipp and Zonen
        • IMT Si-RS485 Sensors
        • Webdom
        • Lufft Weather Stations
        • Campbell Weather Stations
        • DustIQ Soiling Sensors
        • Geonica Weather Stations
        • Groundwork Zenith Meteorological Stations
        • Hukseflux Pyranometers
      • Solar Powered Computers
      • Energy Storage
        • BYD ESS C648
        • BYD ESS
        • NetMan 204
        • Narada Batteries
      • IEC
        • IEC 61850
        • IEC 60870
      • Management Plugins
        • RESI Real Time Clock Plugin
        • Logrotate Plugin
        • Interface Manager Plugin
          • Automatic Modem Connection
          • Manual Modem Connection
          • Troubleshooting Modem Usage
        • Black Box Plugin
        • Log Rotation and Deleting Old Logs
        • Antivirus
        • Backfill
      • Computer Vision
        • Photo Capture Plugin
      • Testing Plugins
        • Dynamic Test
        • JSON Test
        • Ping Test
        • Schema Test
        • Serial Test
        • Solar Demo Plugin
        • Vestas Demo Plugin
        • Service Load Test
        • Resource Usage
        • Edge Statistics
      • Control
        • Ardexa Control Plugin
    • Variable Naming Guide
    • Communications Hardware
      • USB to WIFI Converter
      • Teltonika RUT950 router
      • Huawei E8372 (3G) Modems
      • Modems
  • Ardexa Cloud
    • Ardexa Account
      • Multi-factor Authentication
      • User profile
      • Browsers
      • Navigation
    • Ardexa Remote
      • Install Ardexa Remote
      • Using the Tunnel
      • Using the VPN
      • Troubleshooting
    • Data Access
      • KPIs
      • Users and Permissions
      • Device Groups
      • Limit user access to a subset of devices
      • Limit Access to Searches
      • API Tokens
      • Device access to the API
      • Images
      • Power BI
    • Analysis
      • View Types
      • Charts
      • Formulae
      • Device Logs
    • Searches
      • Creating Searches
      • Sharing Searches
      • CSV Downloads
      • Scheduled Search
      • Search Admin
      • Search Visualisations
      • Search Statistics
      • Search Analysis
      • Audit Logs
      • Other Resources
    • Devices
      • Edge and Cloud Devices
      • Device Summary
      • Device Bulk Actions
      • General Info
      • Remote Shell
      • File Transfer
      • Machine Plugins
      • Manual Configuration
      • Live Feed
      • Network (Edge Devices)
      • Network (Cloud Devices)
      • Discovery
        • Modbus
      • Commands
      • Tunnel (Ardexa Remote)
        • Install ArdexaRemote command line interface (CLI)
      • NAT Gateway
    • Entities
      • What is an entity
      • Create new entity
      • View entities
      • Managing entities
      • Recommendations
    • Standard UI components
    • Dashboards
      • Creating and Editing
      • Card types
        • 📈Chart Card
        • Button Stack
        • Active Incidents
        • Camera Control
        • Command Template
        • Cylinder
        • Energy Summary
        • Energy Tally
        • Gauge
        • Heat Map
        • Indicator light
        • Indicator light table
        • Inverter performance
        • KPI Chart
        • KPI Value
        • Latest Values
        • Link Stack
        • Live Calculation
        • Map
        • Metadata
        • Photo
        • Radial Histogram
        • Remote Web
        • Satellite Image
        • Scatter Plot
        • Single Value
        • Switch Toggle
        • Dynamic Text
        • Static Text
        • Value Table
        • Pie Chart
      • Lookup Table Integration
      • Timeframe and Timezone
    • Alerts
      • Incident Logs
    • Administration
      • Security Services
      • Metadata
      • Workgroup Settings
      • Labelling
      • Moving a Device Across Workgroups
      • External Sources
      • Lookup Table
      • Access Control
    • Energy Solutions
      • Energy Reports
        • Configuring the Daily Energy process
        • Configuring Meter Data
        • Configuring Performance Ratio
          • Irradiation Extract
    • Control
      • Schedules
    • Photos
  • FAQ
    • Difference between "Datetime", "event_time" and "store_time"
    • How can I manually upgrade the agent?
    • What ports does the agent require?
    • Can the agent subscribe to data streams from other agents?
  • Troubleshooting
    • ardpkg error: TypeError: 'NoneType' object is not subscriptable
    • Offline device (Ardexa agent is offline)
      • Remote checks
      • On-site checks
    • Agent continually restarts
    • Workgroup Invitations
    • Slack Invitation
    • Advantech Computer will not connect to the Internet
    • Edge Computer is not fully serviceable
    • The agent won't connect
    • My agent is online, but there is no data in the cloud
    • Agent upgrade failed: Unknown error
    • Device Config Update every log interval
    • Other Agent related issue
    • Running the agent in Debug Mode
    • Agent Maintenance on SysV
    • Connecting a device securely to a network segment that does not have Internet access
    • EXPECT_ERROR: Decimal conversion failed
    • Docker Interface Conflict
    • Failed to fetch...IP Not Found
  • Ardexa API
    • API
      • API Quick Start Guide
      • Python examples
      • Automated API Token Renewal
      • General
        • Issue API token
        • Examine API Token
        • WebSockets
      • Consumer
      • Security
      • Devices
        • Websocket
      • Search
        • API Search Functions
        • Search scrolling
        • Timeframe
        • Consuming data via the API
      • Energy
Powered by GitBook
On this page
  • Viewing devices
  • Accessing device metadata
  • Accessing fields
  • Viewing Device & Source General Information

Was this helpful?

  1. Ardexa API
  2. API

Devices

Inspecting Devices and metadata in the Ardexa Cloud

PreviousSecurityNextWebsocket

Last updated 4 years ago

Was this helpful?

Note: Ardexa hosts clouds in multiple regions as subdomains of ardexa.com. Where you see a reference to mycloud in this document, replace it with the appropriate subdomain for your cloud, eg: mycloud.ardexa.com -> app.ardexa.com or eur1.ardexa.com

Viewing devices

To get a list of devices in a workgroup, make a GET request against the Devices endpoint:

GET mycloud.ardexa.com/api/v1/devices/<workgroupId>

This will return a list of all devices in the workgroup, fully populated with their current device metadata.

Alternatively, you can issue a GET against an individual device's UUID:

GET mycloud.ardexa.com/api/v1/devices/<workgroupId>/<deviceId>

Accessing device metadata

Device metadata is stored against the meta top-level property of the device. meta has a number of top-level properties containing lists of scenarios as described in and displayed in in the Ardexa Cloud.

The scenario types provided as of Agent version 2.4.1 are:

  • run: execute a task at a defined frequency / schedule. Optionally capture the output as an event to send to the Ardexa Cloud

  • tail: watch a text file for new lines. These are captured as events and sent to the Ardexa Cloud. This corresponds to the 'Capture' tab on the Device -> Manual Config page in the app

  • watch: watch a file for changes. When one is detected, send an event to the cloud, optionally attaching the file content

  • unix_socket: listens for events on a specified unix socket. These are captured and sent to the cloud

  • dynamic: tail scenarios detected dynamically by the Ardexa agent, see Dynamic Mapping below

External metadata scenarios are optionally stored separate to the device's configuration, within the settings.externalMeta property. These link data ingested to the cloud from a non-agent source, such as an external API, to the device.

Metadata terminology

Static configuration: run, tail, watch, unix_socket and external define statically configured scenarios derived from the ardexa.yaml configuration file on the device. This was the first metadata configuration scheme implemented in the Ardexa Cloud.

Accessing fields

Where a scenario has an expect type of csv, the agent expects to receive a CSV-formatted record containing one or more fields. This record is transformed into an event which is sent to the Ardexa Cloud. The set of fields is determined by the fields property of the scenario.

An individual field has the following schema:

{
  name: 'field-name-string',
  expect: 'decimal|integer|bool|keyword|text|date'
  meta: {
    units: 'unit-string'
  }
}

There are three variants of field definition used in the Ardexa Cloud:

Hydrated metadata

If the fields property of a scenario is an array, the contents of the array define the exact set of fields collected by that scenario. When all scenarios in a device's configuration contain fields arrays we refer to it as "Hydrated" metadata. For larger device configurations with many scenarios collecting identical fields this results in many redundant field definitions.

Example:

{ ...
  meta: {
    ...
    tail: [{
        table: 'telemetry'
        source: 'widget-01',
        expect: 'csv',
        fields: [
          { name: 'temperature', expect: 'decimal', meta: { units: 'C' },
          { name: 'production', expect: 'integer' }
        ]
      }, {
        table: 'telemetry'
        source: 'widget-02',
        expect: 'csv',
        fields: [
          { name: 'temperature', expect: 'decimal', meta: { units: 'C' },
          { name: 'production', expect: 'integer' }
        ]
      
      }
    ]
  }
... 
}

Compact metadata

If the fields property contains a string without a period (.), the scenario is using a compact fields reference. The value of fields will resolve to a top-level property of the device's meta. This top-level property will contain an array of fields collected by the scenario.

Example:

{ ...
  meta: {
    ...
    tail: [{
      table: 'telemetry',
      source: 'widget-01',
      expect: 'csv',
      fields: 'widget_fields'
    }, {
      table: 'telemetry',
      source: 'widget-02',
      expect: 'csv',
      fields: 'widget_fields'
    }],
    ...
    widget_fields: [
      { name: 'temperature', expect: 'decimal', meta: { units: 'C' },
      { name: 'production', expect: 'integer' }
    ],
    ...
  }
}
    

Dynamic compact metadata

If the fields property contains a string with a single period (.), the scenario is using a dynamic compact fields reference. The format of the fields property will be <table>.<source> . The table and source refer to a scenario within the current scenario type (eg. dynamic) that contains the actual fields array used by both scenarios.

Note that the actual scenario that contains the field definition is set dynamically by the Ardexa Agent, so may change when a device's metadata is updated.

Example:

{ ...
  meta: {
    ...
    dynamic: [{
      table: 'telemetry',
      source: 'widget-01',
      expect: 'csv',
      fields: [
        { name: 'temperature', expect: 'decimal', meta: { units: 'C' },
        { name: 'production', expect: 'integer' }
      ]
    }, {
      table: 'telemetry',
      source: 'widget-02',
      expect: 'csv',
      fields: 'telemetry.widget-01'
    }],
    ...
  }
}

Viewing Device & Source General Information

Device & Source General Information (as displayed in Devices -> General Info in the app, or maintained in the Admin -> Workgroup -> Metadata section) is stored as a device setting on each device in a workgroup. Look-ups for this information must be retrieved from the Workgroup's deviceInfoKeys and sourceInfoKeys settings. Each id in these settings corresponds to the ID of a device setting, as returned in the settings property of the GET device endpoint.

Source-level metadata is stored as a map, keyed by source name.

GET /api/v1/orgs/myWorkgroupId/settings/deviceInfoKeys
-->
{
  "key": "deviceInfoKeys",
  "value": [
    {
      "id": "ae95703c-0ba4-49bf-8d7c-6d57054751d5",
      "name": "Latitude"
    },
    {
      "id": "526118f9-b552-4124-8a02-bab30e3606e6",
      "name": "Longitude"
    }
  ]
}

GET /api/v1/orgs/myWorkgroupId/settings
-->
{
    "key": "sourceInfoKeys",
    "value": [
        {
            "id": "111111111-0ba4-49bf-8d7c-6d57054751d5",
            "name": "Manufacturer"
        },
        {
            "id": "111111111-b552-4124-8a02-bab30e3606e6",
            "name": "Serial Number"
        }
}

GET /api/v1/devices/myWorkgroupId/device-id-1
--> 
{
  name: 'My device',
  ...,
  meta: {...},
  settings: {
    "ae95703c-0ba4-49bf-8d7c-6d57054751d5": -35.282, // Latitude device-level item
    "526118f9-b552-4124-8a02-bab30e3606e6": 149.129, // Longitude device-level item
    "111111111-0ba4-49bf-8d7c-6d57054751d5": { 
      // (Manufacturer source-level item)
      source-1: "ACME Widget Co",
      source-2: "Widgets r Us"
    },
    "111111111-b552-4124-8a02-bab30e3606e6": {
      // (Serial number source-level item)
      source-1: "111000999111-c",
      source-2: "445039956551-b"
    }
  }
}

Scenario: an individual unit of work performed by the agent. This usually involves executing a command at a specified interval or watching a file for changes. See for more information. An important rule is that within a device's configuration, the combination of each scenario's table and source must be unique.

Dynamic mapping: dynamic scenarios, introduced in agent version 2.3.0 are populated by the Ardexa agent. The agent watches specific file system locations on the device for dynamic run and dynamic tail scenarios, typically executable files in /opt/ardexa/run and latest.csv files in/opt/ardexa/logs respectively. This scheme scales well with large device configurations and is heavily used by the Machine Plugins system. For more information, see .

Agent -> Manual Configuration
Devices -> Manual Configuration
Scenarios
Dynamic Mapping