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.

Overview

Eval results

Files

Connection Management

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

Core connection functionality for establishing and managing MQTT connections to Arduino IoT Cloud with support for multiple authentication methods.

Capabilities

ArduinoIoTCloud Factory

The main factory object for creating cloud connections based on provided options.

/**
 * Factory object for creating Arduino IoT Cloud connections
 */
const ArduinoIoTCloud: IArduinoIoTCloudFactory;

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

Usage Examples:

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

// API credentials (returns IMultiPropertiesCloudClient)
const apiClient = await ArduinoIoTCloud.connect({
  clientId: "your-client-id",
  clientSecret: "your-client-secret",
  host: "iot.arduino.cc", // optional
  onConnected: () => console.log("Connected!")
});

// Browser token (returns IMultiPropertiesCloudClient)
const tokenClient = await ArduinoIoTCloud.connect({
  token: "your-jwt-token",
  useCloudProtocolV2: true // optional
});

// Device credentials (returns ISinglePropertyCloudClient)
const deviceClient = await ArduinoIoTCloud.connect({
  deviceId: "your-device-id",
  secretKey: "your-secret-key",
  port: 8884 // optional
});

Base Client Interface

Common interface shared by all cloud client types.

interface ICloudClient {
  /** Reconnect to the MQTT broker */
  reconnect(): Promise<void>;
  /** Disconnect from the MQTT broker */
  disconnect(): Promise<void>;
  /** Send a raw message to a specific MQTT topic */
  sendMessage(topic: string, message: string | ArrayBuffer): Promise<void>;
}

Multi-Properties Client

Client interface for user credentials that can access multiple things and properties.

interface IMultiPropertiesCloudClient extends ICloudClient {
  /** Send a property value to a specific thing */
  sendProperty<T extends CloudMessageValue>(
    thingId: string,
    name: string,
    value: T,
    tmp?: number
  ): Promise<void>;

  /** Listen to property value changes from a specific thing */
  onPropertyValue<T extends CloudMessageValue>(
    thingId: string,
    name: string,
    cb: OnMessageCallback<T>
  ): void;
}

Single Property Client

Client interface for device credentials that behaves as a single device.

interface ISinglePropertyCloudClient extends ICloudClient {
  /** Send a property value from this device */
  sendProperty<T extends CloudMessageValue>(
    name: string,
    value: T,
    tmp?: number
  ): Promise<void>;

  /** Listen to property value changes for this device */
  onPropertyValue<T extends CloudMessageValue>(
    name: string,
    cb: OnMessageCallback<T>
  ): void;

  /** Get the thing ID associated with this device */
  getThing(): Promise<string>;
}

Token Client Interface

Additional interface for clients that use JWT token authentication.

interface ITokenCloudClient {
  /** Get the current JWT token */
  getToken(): string;
  /** Update the JWT token and reconnect */
  updateToken(newToken: string): Promise<void>;
}

Connection Options

Configuration options for cloud connections.

interface CloudOptions {
  /** MQTT broker host (default: 'iot.arduino.cc') */
  host?: string;
  /** MQTT broker port */
  port?: string | number;
  /** Use cloud protocol v2 (default: true) */
  useCloudProtocolV2?: boolean;
  /** Use SSL connection */
  ssl?: boolean;
  /** Callback when connection goes offline */
  onOffline?: () => void;
  /** Callback when connection is established */
  onConnected?: () => void;
  /** Callback when connection is lost */
  onDisconnect?: (message?: any) => void;
}

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

Authentication Options

Different authentication option types for various connection modes.

/** API credentials for user access */
interface APIOptions {
  /** API endpoint URL (optional) */
  apiUrl?: string;
  /** OAuth client ID */
  clientId: string;
  /** JWT audience (optional) */
  audience?: string;
  /** OAuth client secret */
  clientSecret: string;
}

/** Browser JWT token authentication */
interface BrowserOptions {
  /** JWT token for authentication */
  token: string;
}

/** Device credentials for single device behavior */
interface CredentialsOptions {
  /** Device identifier */
  deviceId: string;
  /** Device secret key */
  secretKey: string;
}

Connection Examples

Error Handling

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

try {
  const client = await ArduinoIoTCloud.connect({
    clientId: "invalid-id",
    clientSecret: "invalid-secret",
    onDisconnect: (error) => {
      console.error("Connection lost:", error);
      // Implement reconnection logic
    }
  });
} catch (error) {
  console.error("Connection failed:", error.message);
}

Reconnection

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

const client = await ArduinoIoTCloud.connect({
  deviceId: "your-device-id",
  secretKey: "your-secret-key",
  onDisconnect: async (message) => {
    console.log("Disconnected, attempting to reconnect...");
    try {
      await client.reconnect();
      console.log("Reconnected successfully");
    } catch (error) {
      console.error("Reconnection failed:", error);
    }
  }
});

Graceful Disconnection

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

const client = await ArduinoIoTCloud.connect({
  token: "your-jwt-token"
});

// Use the client...

// Clean disconnection
process.on('SIGINT', async () => {
  console.log('Shutting down...');
  await client.disconnect();
  process.exit(0);
});

Install with Tessl CLI