or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

connection-management.mdindex.mdproperty-operations.mdsenml-processing.md
tile.json

tessl/npm-arduino-iot-js

JavaScript/TypeScript library for connecting to the Arduino IoT Cloud MQTT broker with support for both browser and Node.js applications.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/arduino-iot-js@0.14.x

To install, run

npx @tessl/cli install tessl/npm-arduino-iot-js@0.14.0

index.mddocs/

Arduino IoT JS

Arduino IoT JS is a JavaScript/TypeScript library for connecting to the Arduino IoT Cloud MQTT broker, enabling both browser and Node.js applications to interact with Arduino IoT Cloud devices and properties. It supports two connection modes: user credentials for accessing all user properties, and device credentials for single device behavior.

Package Information

  • Package Name: arduino-iot-js
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install arduino-iot-js

Core Imports

import { ArduinoIoTCloud } from "arduino-iot-js";

For CommonJS:

const { ArduinoIoTCloud } = require("arduino-iot-js");

Additional imports:

import {
  ArduinoIoTCloud,
  CloudOptions,
  SenML,
  type APIOptions,
  type BrowserOptions,
  type CredentialsOptions,
  type IArduinoIoTCloudFactory,
  type ICloudClient,
  type IMultiPropertiesCloudClient,
  type ITokenCloudClient,
  type ISinglePropertyCloudClient,
  type CloudMessageValue
} from "arduino-iot-js";

Basic Usage

User Credentials with API Keys

import { ArduinoIoTCloud } from "arduino-iot-js";

const client = await ArduinoIoTCloud.connect({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
  onDisconnect: (message) => console.error(message),
});

// Send a value to a thing property
await client.sendProperty("YOUR_THING_ID", "temperature", 25.5);

// Listen to a thing property's changes
client.onPropertyValue("YOUR_THING_ID", "humidity", (value) => {
  console.log("Humidity updated:", value);
});

Device Credentials

import { ArduinoIoTCloud } from "arduino-iot-js";

const client = await ArduinoIoTCloud.connect({
  deviceId: "YOUR_DEVICE_ID",
  secretKey: "YOUR_SECRET_KEY",
  onDisconnect: (message) => console.error(message),
});

// Send property values as a device
await client.sendProperty("temperature", 25.5);

// Listen to property updates
client.onPropertyValue("led_status", (value) => {
  console.log("LED status:", value);
});

Architecture

Arduino IoT JS is built around several key components:

  • Connection Factory: ArduinoIoTCloud factory creates appropriate client instances based on connection options
  • Client Types: Different client interfaces for multi-property (user) and single-property (device) scenarios
  • Builder Pattern: Internal builders handle different authentication methods (API, token, device credentials)
  • Connection Layer: MQTT connection management with WebSocket transport and reconnection logic
  • SenML Processing: CBOR-encoded SenML message handling for IoT data exchange
  • Type Safety: Full TypeScript support with comprehensive interfaces and type definitions

Capabilities

Connection Management

Core connection functionality for establishing and managing MQTT connections to Arduino IoT Cloud.

interface IArduinoIoTCloudFactory {
  connect(options: APIOptions & Partial<CloudOptions>): Promise<IMultiPropertiesCloudClient>;
  connect(options: BrowserOptions & Partial<CloudOptions>): Promise<IMultiPropertiesCloudClient>;
  connect(options: CredentialsOptions & Partial<CloudOptions>): Promise<ISinglePropertyCloudClient>;
}

Connection Management

Property Operations

Property sending and listening capabilities for IoT device communication.

interface IMultiPropertiesCloudClient extends ICloudClient {
  sendProperty<T extends CloudMessageValue>(
    thingId: string,
    name: string,
    value: T,
    tmp?: number
  ): Promise<void>;
  onPropertyValue<T extends CloudMessageValue>(
    thingId: string,
    name: string,
    cb: OnMessageCallback<T>
  ): void;
}

interface ISinglePropertyCloudClient extends ICloudClient {
  sendProperty<T extends CloudMessageValue>(
    name: string,
    value: T,
    tmp?: number
  ): Promise<void>;
  onPropertyValue<T extends CloudMessageValue>(
    name: string,
    cb: OnMessageCallback<T>
  ): void;
}

Property Operations

SenML Data Processing

SenML (Sensor Markup Language) utilities for IoT data encoding and processing.

namespace SenML {
  export const CBOR: {
    encode(value: SenML[], numericKeys?: boolean): ArrayBuffer;
    decode(buffer: ArrayBuffer): SenML[];
  };
  export function parse(
    name: string,
    value: CloudMessageValue,
    timestamp: number,
    useCloudProtocolV2: boolean,
    deviceId: string
  ): SenML | SenML[];
}

SenML Processing

Error Handling

Arduino IoT Cloud specific error handling and utilities.

class ArduinoCloudError extends Error {
  constructor(public code: number, message: string);
  name: string;
}

Core Types

type CloudMessageValue = string | number | boolean | object;

type OnMessageCallback<T extends CloudMessageValue> = (message: T) => void;


interface CloudOptions {
  host?: string;
  port?: string | number;
  useCloudProtocolV2?: boolean;
  ssl?: boolean;
  onOffline?: () => void;
  onConnected?: () => void;
  onDisconnect?: (message?: any) => void;
}

namespace CloudOptions {
  /** Default connection options */
  const DEFAULT: CloudOptions;
}

interface APIOptions {
  apiUrl?: string;
  clientId: string;
  audience?: string;
  clientSecret: string;
}

interface BrowserOptions {
  token: string;
}

interface CredentialsOptions {
  deviceId: string;
  secretKey: string;
}

interface ICloudClient {
  reconnect(): Promise<void>;
  disconnect(): Promise<void>;
  sendMessage(topic: string, message: string | ArrayBuffer): Promise<void>;
}

interface ITokenCloudClient {
  getToken(): string;
  updateToken(newToken: string): Promise<void>;
}