Corvina IOT util

corvina-iot-util is the utility of the Corvina IoT team: it creates a local device simulator from a Corvina model, runs it, and inserts historical data into the platform.

The package installs a single binary under two names:

• ci — current command set task oriented from version 1.3.0, with commands (ci device create|start|stop|list|ports|logs|upload), the API key read once from a configuration file.
• corvina-iot-util — the command set of the versions <= 1.2.0, still working and documented in The corvina-iot-util command set at the end of this page.

Installation

npm install -g @corvina/corvina-iot-util

The ci command is then available in your shell; ci --help and ci device <command> --help describe every command and flag.

Without installing anything, the same command can be run through npx:

npx -p @corvina/corvina-iot-util ci device list

From a clone of this repository, ./ci runs the binary in build/ for your platform, with no installation at all.

The ci commands

ci works on a workspace: every device is a directory of the current directory, created and then started, stopped and watched by name. The API key is read once from a configuration file instead of being pasted into every command.

Configuration

Settings shared by all commands are read from the first of these files:

1. $CI_CONFIG
2. ./.env (the workspace root)
3. ~/.config/corvina-ci/.env
4. ~/.corvina-ci.env

CORVINA_API_KEY=<your user api key>
CORVINA_ORG=exor
CORVINA_BACKEND=app.corvina.cloud

Environment variables with the same names override the file. Files containing ACTIVATION_KEY are skipped, so a device .env is never mistaken for the configuration. The devices are the directories of the current directory, which can be overridden with CI_WORKSPACE.

1. Create a device from a model

ci device create --model model.json --name device-001 \
  --backend app.corvina.cloud --key 62UY5-8X9SU-CXJLA-4K5B1

• --model FILE the Corvina model, defaults to model.json
• --name NAME name of the device, also used as the directory name
• --key KEY activation key
• --backend BACKEND defaults to CORVINA_BACKEND
• --no-simulation create the device with the tag simulation off
• --port N defaults to the first free port

Creates the directory device-001/ (named after the device, no renaming needed) with configuration.json, .env and run.sh. --backend accepts what you read in the browser: app.corvina.cloud, corvina.mk, https://app.dev.corvina.cloud all work, and the pairing endpoint is derived from it.

2. Start and stop a device

ci device start device-001 --no-simulation
ci device stop device-001
ci device logs device-001 --lines 100
ci device logs device-001 --follow      # keep printing as the device writes, Ctrl+C to stop

start launches @corvina/device-example in background, writing its output to device-001/device.log and its pid to device-001/.ci.json. logs --follow (-f) prints the tail and then keeps printing what the device writes, so you can watch a device you just started; it keeps waiting when the device is stopped, and picks the log up again from the start if the file is emptied.

3. List the devices

$ ci device list
Name        |Status  |Activation Key          |Simulation Tags  |Backend           |Port  |PID
device-001  Run      62UY5-8X9SU-CXJLA-4K5B1  False             app.corvina.cloud  3001   34122
device-002  Stop     AAAAA-AAAAA-AAAAA-AAAAA  True              app.corvina.mk     3002   -

Both the device-001/ layout created by ci and the older <project>/device-example/ layout are recognised.

list also warns when two devices are assigned the same port, which happens with the directories created before ci started assigning them. ports shows the port map and what it would change:

$ ci device ports
Name        |Port  |Status  |Conflict
device-001  3001   Run      -
device-002  3001   Stop     shared with device-001
device-003  3007   Stop     used by another process

device-002: 3001 -> 3002 (shared with device-001)
device-003: 3007 -> 3003 (used by another process)

Nothing changed. Run 'ci device ports --fix' to apply.

--fix writes the new ports in the .env and in the state of each device. A running device keeps its port, since it is the one that owns it, and is never rewritten while it runs: stop it first. A port held by a process outside the workspace (a device started by hand from another directory, for instance) counts as a conflict too, because device-example dies with EADDRINUSE before even pairing.

4. Insert test data

Once the device is registered on Corvina, insert a previously downloaded data file, replacing the device id it was downloaded from:

ci device upload device-001 --file data.json --set id=ZKhHM4rT32UyUC-XRVk8rg

• --file FILE the data file, JSON or CSV, defaults to data.json
• --set id=<device-id> override the deviceId of every record
• --set model=<Model:version> override the model of every modelPath
• --org ORG defaults to CORVINA_ORG, --backend defaults to the device one
• --batch-size N, --delay 1s, --dry-run

The API key comes from the configuration, never from the command line.

The corvina-iot-util command set

These are the commands of the versions <= 1.2.0. They still work — same binary, same package — and are kept for the scripts that already use them; for a new device or a new data upload, prefer the ci commands above.

USAGE: corvina-iot-util [global options] command [command options]

create-device-example: Create and run a device

• --model string: The JSON file containing the model configuration
• --activation-key string: The activation key of the device
• --device-dir string: The directory where the device will be created
• --host string: The hostname of the corvina iot server
• --start-device: If true, the device will be started after creation

corvina-iot-util create-device-example \
 --model=model.json \
 --activation-key=XXXX-XXXX-XXX-XXX \
 --host=corvina.mk

insert-device-data: Insert bulk data into a device.

• --XApiKey string: specify a valide user API key
• --file string: specify the path of the file with the data to be inserted
• --host string: specify the corvina host. e.g.: corvina.mk
• --org string: specify a organization name. e.g.: exor
• --device-id string: (optional) specify the device id to override the one in the file
• --model-prefix string: (optional) specify the model name to override the one in the file
• --batch-size int: (optional) number of data rows sent per request. Defaults to 500. Large payloads are split into multiple requests to avoid gateway timeouts (504).
• --delay duration: (optional) pause between consecutive requests to avoid the API rate limiter. Defaults to 1s. Accepts values like 1s, 500ms, 2s.

You can insert bulk data into a device using a JSON or CSV file.

When inserting large files, the data is automatically split into batches of --batch-size rows (default 500) and sent in multiple requests. This avoids 504 Gateway Time-out errors caused by sending too much data in a single request. Lower the batch size if you still hit timeouts.

A --delay (default 1s) is applied between consecutive requests to avoid hitting the API rate limiter. Set it to 0 to disable the pause, or increase it if you still get rate-limited.

Example JSON Data Insertion

corvina-iot-util insert-device-data \
  --XApiKey=<api-key> \
  --org=<org> \
  --host=corvina.cloud \
  --file=./<file-name-data-json>

  {
    "deviceId": "i05Ofzkn35iSqrEch5lqCg",
    "modelPath": "Model:1/Property1",
    "header": [
      "timestamp",
      "value"
    ],
    "types": [
      "datetime",
      "integer"
    ],
    "data": [
      ["2024-11-06T12:53:36.000+01:00", 1 ],
      ["2024-11-06T12:53:50.000+01:00", 2 ],
    ]
  },
  {
    "deviceId": "i05Ofzkn35iSqrEch5lqCg",
    "modelPath": "Model:1/Property2",
    "header": [
      "timestamp",
      "value"
    ],
    "types": [
      "datetime",
      "integer"
    ],
    "data": [
      ["2024-11-06T12:53:36.000+01:00", 10 ],
      ["2024-11-06T12:53:50.000+01:00", 20 ],
    ]
  }
]

Example JSON Data Insertion

When using CSV data, it is recommended to set the --device-id and --model-prefix options to override these fields for all rows, ensuring consistency and simplifying the CSV structure.

Example CSV format:

deviceId,modelPath,timestamp,value
i05Ofzkn35iSqrEch5lqCg,Model:1/Property1,2024-11-06T12:53:36.000+01:00,1
i05Ofzkn35iSqrEch5lqCg,Model:1/Property1,2024-11-06T12:53:50.000+01:00,2
i05Ofzkn35iSqrEch5lqCg,Model:1/Property2,2024-11-06T12:53:36.000+01:00,10
i05Ofzkn35iSqrEch5lqCg,Model:1/Property2,2024-11-06T12:53:50.000+01:00,20

Usage:

corvina-iot-util insert-device-data \
  --XApiKey=<api-key> \
  --org=<org> \
  --host=corvina.cloud \
  --file=./<file-name-data.csv> \
  --device-id=<device-id> \
  --model-prefix=<model-prefix> \
  --batch-size=500 \
  --delay=1s