tessl/npm-arduino--arduino-iot-client

JavaScript client library for the Arduino IoT Cloud REST API enabling programmatic management of devices, things, properties, and time-series data

Overview

Eval results

Files

Arduino IoT Client

Name: tessl/npm-arduino--arduino-iot-client
Author: tessl

Arduino IoT Client is the official JavaScript client library for the Arduino IoT Cloud REST API. It provides comprehensive programmatic access to manage Arduino IoT devices, things, properties, and time-series data. The library is auto-generated from OpenAPI specifications and offers both Node.js and browser compatibility with OAuth2 authentication.

Package Information

Package Name: @arduino/arduino-iot-client
Package Type: npm
Language: JavaScript (ES6+ with Babel)
Installation: npm install @arduino/arduino-iot-client

Core Imports

import ArduinoIotClient from '@arduino/arduino-iot-client';

For CommonJS:

const ArduinoIotClient = require('@arduino/arduino-iot-client');

Basic Usage

import ArduinoIotClient from '@arduino/arduino-iot-client';

// Configure OAuth2 authentication
const defaultClient = ArduinoIotClient.ApiClient.instance;
const oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = 'YOUR_ACCESS_TOKEN';

// Create API instances
const devicesApi = new ArduinoIotClient.DevicesV2Api();
const thingsApi = new ArduinoIotClient.ThingsV2Api();
const propertiesApi = new ArduinoIotClient.PropertiesV2Api();

// List all devices
try {
  const devices = await devicesApi.devicesV2List();
  console.log('Devices:', devices);
} catch (error) {
  console.error('API Error:', error);
}

// Create a new thing
const thingData = {
  name: "My IoT Thing",
  deviceId: "device-uuid-here"
};
const newThing = await thingsApi.thingsV2Create(thingData);

Architecture

Arduino IoT Client is built around several key components:

API Client: Core HTTP client (ApiClient) handling OAuth2 authentication and requests
API Classes: 16 specialized API classes covering different functional areas
Data Models: 123+ model classes representing all data structures and payloads
Authentication: OAuth2 bearer token with organization-level access control
Error Handling: HTTP status-based error responses with structured error models

Capabilities

Device Management

Complete device lifecycle management including creation, configuration, certificate management, and over-the-air updates.

class DevicesV2Api {
  devicesV2Create(createDevicesV2Payload: CreateDevicesV2Payload, opts?: any): Promise<ArduinoDevicev2>;
  devicesV2List(opts?: any): Promise<ArduinoDevicev2[]>;
  devicesV2Show(id: string, opts?: any): Promise<ArduinoDevicev2>;
  devicesV2Update(id: string, devicev2: Devicev2, opts?: any): Promise<ArduinoDevicev2>;
  devicesV2Delete(id: string, opts?: any): Promise<void>;
}

Device Management

Thing Management

IoT thing management with property definitions, sketch handling, and device associations.

class ThingsV2Api {
  thingsV2Create(thingCreate: ThingCreate, opts?: any): Promise<ArduinoThing>;
  thingsV2List(opts?: any): Promise<ArduinoThing[]>;
  thingsV2Show(id: string, opts?: any): Promise<ArduinoThing>;
  thingsV2Update(id: string, thingUpdate: ThingUpdate, opts?: any): Promise<ArduinoThing>;
  thingsV2Delete(id: string, opts?: any): Promise<void>;
}

Thing Management - Includes legacy ThingsV1Api for backward compatibility

Property Management

Real-time property value management, timeseries data access, and property configuration.

class PropertiesV2Api {
  propertiesV2Create(id: string, property: Property, opts?: any): Promise<ArduinoProperty>;
  propertiesV2List(id: string, opts?: any): Promise<ArduinoProperty[]>;
  propertiesV2Publish(id: string, pid: string, propertyValue: PropertyValue, opts?: any): Promise<void>;
  propertiesV2Timeseries(id: string, pid: string, opts?: any): Promise<ArduinoSeriesResponse>;
}

Property Management - Includes legacy PropertiesV1Api for backward compatibility

Dashboard Management

Visual dashboard creation, widget management, and sharing capabilities.

class DashboardsV2Api {
  dashboardsV2Create(dashboardv2: Dashboardv2, opts?: any): Promise<ArduinoDashboardv2>;
  dashboardsV2List(opts?: any): Promise<ArduinoDashboardv2[]>;
  dashboardsV2Link(id: string, widgetId: string, widgetlink: Widgetlink, opts?: any): Promise<ArduinoWidgetv2>;
  dashboardsV2Share(id: string, dashboardshare: Dashboardshare, opts?: any): Promise<void>;
}

Dashboard Management

Time Series Analytics

Advanced time series data querying with batch operations, sampling, and historical data analysis.

class SeriesV2Api {
  seriesV2BatchQuery(batchQueryRequestsMediaV1: BatchQueryRequestsMediaV1, opts?: any): Promise<ArduinoSeriesResponse>;
  seriesV2BatchQueryRaw(batchQueryRawRequestsMediaV1: BatchQueryRawRequestsMediaV1, opts?: any): Promise<ArduinoSeriesRawResponse>;
  seriesV2HistoricData(historicDataRequest: HistoricDataRequest, opts?: any): Promise<ArduinoSeriesResponse>;
}

Time Series Analytics - Includes legacy SeriesV1Api for backward compatibility

Automation & Triggers

Event-driven automation with triggers, actions, and conditional logic for IoT workflows.

class TriggersV1Api {
  triggersV1Create(trigger: Trigger, opts?: any): Promise<ArduinoTrigger>;
  actionsV1Create(createAction: CreateAction, opts?: any): Promise<ArduinoAction>;
  triggersV1List(opts?: any): Promise<ArduinoTrigger[]>;
  actionsV1List(opts?: any): Promise<ArduinoAction[]>;
}

Automation & Triggers

LoRa Device Management

LoRaWAN device creation and frequency plan management for Low Power Wide Area Network deployments.

class LoraDevicesV1Api {
  loraDevicesV1Create(createLoraDevicesV1Payload: CreateLoraDevicesV1Payload, opts?: any): Promise<ArduinoLoradevicev1>;
}

class LoraFreqPlanV1Api {
  loraFreqPlanV1List(opts?: any): Promise<ArduinoLorafreqplansv1>;
}

LoRa Device Management

Network Credentials & Templates

Network credentials management and template-based device/thing creation for standardized deployments.

class NetworkCredentialsV1Api {
  networkCredentialsV1Show(type: string, opts?: any): Promise<ArduinoCredentialsv1>;
  networkCredentialsV1ShowByDevice(type: string, opts?: any): Promise<ArduinoCredentialsv1[]>;
}

class TemplatesApi {
  templatesApply(template: Template, opts?: any): Promise<ArduinoTemplate>;
}

Network Credentials & Templates

Authentication

OAuth2 authentication is required for all API operations:

interface OAuth2Config {
  accessToken: string;
}

class ApiClient {
  static instance: ApiClient;
  authentications: {
    oauth2: OAuth2Config;
  };
}

Obtaining Access Token:

const requestPromise = require('request-promise');

const tokenOptions = {
  method: 'POST',
  url: 'https://api2.arduino.cc/iot/v1/clients/token',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  json: true,
  form: {
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    audience: 'https://api2.arduino.cc/iot'
  }
};

const response = await requestPromise(tokenOptions);
const accessToken = response.access_token;

Core Data Models

interface ArduinoDevicev2 {
  connectionType?: string;
  deviceId?: string;
  fqbn?: string;
  id?: string;
  name?: string;
  serial?: string;
  type?: string;
  userId?: string;
  webhookActive?: boolean;
  webhookUri?: string;
}

interface ArduinoThing {
  createdAt?: Date;
  deletedAt?: Date;
  deviceId?: string;
  href?: string;
  id?: string;
  name?: string;
  properties?: ArduinoProperty[];
  sketchId?: string;
  timezone?: string;
  updatedAt?: Date;
  userId?: string;
  webhookActive?: boolean;
  webhookUri?: string;
}

interface ArduinoProperty {
  createdAt?: Date;
  href?: string;
  id?: string;
  lastValue?: any;
  linkedToTrigger?: boolean;
  maxValue?: number;
  minValue?: number;
  name?: string;
  permission?: PropertyPermission;
  persist?: boolean;
  tag?: number;
  thingId?: string;
  type?: PropertyType;
  updateParameter?: number;
  updateStrategy?: PropertyUpdateStrategy;
  updatedAt?: Date;
  variableName?: string;
}

Error Handling

All API methods return promises that may reject with structured error objects:

interface Error {
  code?: string;
  detail?: string;
  status?: number;
}

Error Handling Example:

try {
  const devices = await devicesApi.devicesV2List();
} catch (error) {
  if (error.status === 401) {
    console.error('Authentication failed - check access token');
  } else if (error.status === 403) {
    console.error('Forbidden - check organization permissions');
  } else {
    console.error('API Error:', error.detail || error.message);
  }
}

Organization Support

Multi-tenant support through organization headers:

// Pass organization ID in options for all API calls
const opts = {
  xOrganization: 'your-organization-id'
};

const devices = await devicesApi.devicesV2List(opts);
const things = await thingsApi.thingsV2List(opts);

Install with Tessl CLI

npx tessl i tessl/npm-arduino--arduino-iot-client

Workspace: tessl
Visibility: Public
Created: 5 months ago
Last updated: about 1 month ago
Describes: pkg:npm/@arduino/arduino-iot-client@3.0.x