CtrlK
BlogDocsLog inGet started
Tessl Logo

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

thing-management.mddocs/

Thing Management

IoT thing management with property definitions, sketch handling, and device associations. Things represent logical entities in your IoT system that can contain multiple properties and be associated with physical devices.

Capabilities

Core Thing Operations

Primary thing management functionality for CRUD operations on IoT things.

class ThingsV2Api {
  /**
   * Create a new IoT thing
   * @param thingCreate - Thing creation parameters
   * @param opts - Optional parameters including organization ID
   * @returns Promise<ArduinoThing> - Created thing object
   */
  thingsV2Create(thingCreate: ThingCreate, opts?: any): Promise<ArduinoThing>;

  /**
   * List all things accessible to the authenticated user
   * @param opts - Optional parameters including organization ID, pagination, and filtering
   * @returns Promise<ArduinoThing[]> - Array of thing objects
   */
  thingsV2List(opts?: any): Promise<ArduinoThing[]>;

  /**
   * Get detailed information about a specific thing
   * @param id - Thing ID
   * @param opts - Optional parameters including organization ID and show_properties flag
   * @returns Promise<ArduinoThing> - Thing object with full details
   */
  thingsV2Show(id: string, opts?: any): Promise<ArduinoThing>;

  /**
   * Update thing configuration and metadata
   * @param id - Thing ID
   * @param thingUpdate - Updated thing configuration
   * @param opts - Optional parameters including organization ID
   * @returns Promise<ArduinoThing> - Updated thing object
   */
  thingsV2Update(id: string, thingUpdate: ThingUpdate, opts?: any): Promise<ArduinoThing>;

  /**
   * Delete a thing permanently
   * @param id - Thing ID
   * @param opts - Optional parameters including organization ID and force flag
   * @returns Promise<void>
   */
  thingsV2Delete(id: string, opts?: any): Promise<void>;

  /**
   * Clone an existing thing with all its properties
   * @param id - Thing ID to clone
   * @param thingClone - Clone configuration including new name
   * @param opts - Optional parameters including organization ID
   * @returns Promise<ArduinoThing> - Cloned thing object
   */
  thingsV2Clone(id: string, thingClone: ThingClone, opts?: any): Promise<ArduinoThing>;

  /**
   * Get thing as a template for replication
   * @param id - Thing ID
   * @param opts - Optional parameters including organization ID
   * @returns Promise<ArduinoThingtemplate> - Thing template
   */
  thingsV2Template(id: string, opts?: any): Promise<ArduinoThingtemplate>;
}

Usage Examples:

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

const thingsApi = new ArduinoIotClient.ThingsV2Api();

// Create a new thing
const newThing = await thingsApi.thingsV2Create({
  name: "Smart Home Sensor",
  deviceId: "device-uuid-here",
  timezone: "America/New_York"
});

// List all things with pagination
const things = await thingsApi.thingsV2List({
  page: 1,
  size: 20,
  showProperties: true
});

// Get thing details with properties
const thingDetails = await thingsApi.thingsV2Show(newThing.id, {
  showProperties: true
});
console.log('Thing properties:', thingDetails.properties);

// Clone a thing for testing
const clonedThing = await thingsApi.thingsV2Clone(newThing.id, {
  name: "Smart Home Sensor - Test",
  includeProperties: true
});

Arduino Sketch Management

Manage Arduino sketches associated with things for code deployment and updates.

class ThingsV2Api {
  /**
   * Create a new Arduino sketch for a thing
   * @param id - Thing ID
   * @param thingSketch - Sketch creation parameters including code content
   * @param opts - Optional parameters including organization ID
   * @returns Promise<ArduinoThing> - Updated thing with sketch information
   */
  thingsV2CreateSketch(id: string, thingSketch: ThingSketch, opts?: any): Promise<ArduinoThing>;

  /**
   * Update an existing Arduino sketch
   * @param id - Thing ID
   * @param sketchId - Sketch ID
   * @param updateSketch - Updated sketch content and metadata
   * @param opts - Optional parameters including organization ID
   * @returns Promise<ArduinoThing> - Updated thing with sketch information
   */
  thingsV2UpdateSketch(id: string, sketchId: string, updateSketch: UpdateSketch, opts?: any): Promise<ArduinoThing>;

  /**
   * Delete the Arduino sketch from a thing
   * @param id - Thing ID
   * @param opts - Optional parameters including organization ID
   * @returns Promise<void>
   */
  thingsV2DeleteSketch(id: string, opts?: any): Promise<void>;
}

Thing Tagging

Thing organization and categorization through tags.

class ThingsV2TagsApi {
  /**
   * Create or update a thing tag
   * @param id - Thing ID
   * @param tag - Tag to create or update
   * @param opts - Optional parameters including organization ID
   * @returns Promise<void>
   */
  thingsV2TagsUpsert(id: string, tag: Tag, opts?: any): Promise<void>;

  /**
   * List all tags for a thing
   * @param id - Thing ID
   * @param opts - Optional parameters including organization ID
   * @returns Promise<ArduinoTags> - Thing tags
   */
  thingsV2TagsList(id: string, opts?: any): Promise<ArduinoTags>;

  /**
   * Delete a specific thing tag
   * @param id - Thing ID
   * @param key - Tag key to delete
   * @param opts - Optional parameters including organization ID
   * @returns Promise<void>
   */
  thingsV2TagsDelete(id: string, key: string, opts?: any): Promise<void>;
}

Legacy Thing Operations (V1 API)

Legacy thing management functionality for backward compatibility. Use ThingsV2Api for new integrations.

class ThingsV1Api {
  /**
   * Create a new thing associated to the user (legacy)
   * @param createThingsV1Payload - Thing creation payload
   * @param opts - Optional parameters including force flag to detach device from other things
   * @returns Promise<ArduinoThing> - Created thing object
   */
  thingsV1Create(createThingsV1Payload: CreateThingsV1Payload, opts?: any): Promise<ArduinoThing>;

  /**
   * List all things associated to the user (legacy)
   * @param opts - Optional parameters including acrossUserIds, deviceId, and showDeleted flags
   * @returns Promise<ArduinoThing[]> - Array of thing objects
   */
  thingsV1List(opts?: any): Promise<ArduinoThing[]>;

  /**
   * Get thing details (legacy)
   * @param id - Thing ID
   * @param opts - Optional parameters including showDeleted flag
   * @returns Promise<ArduinoThing> - Thing object with full details
   */
  thingsV1Show(id: string, opts?: any): Promise<ArduinoThing>;

  /**
   * Update thing configuration (legacy)
   * @param id - Thing ID
   * @param thing - Updated thing payload
   * @param opts - Optional parameters including force flag
   * @returns Promise<ArduinoThing> - Updated thing object
   */
  thingsV1Update(id: string, thing: Thing, opts?: any): Promise<ArduinoThing>;

  /**
   * Delete a thing (legacy)
   * @param id - Thing ID
   * @param opts - Optional parameters including force flag for hard delete
   * @returns Promise<void>
   */
  thingsV1Delete(id: string, opts?: any): Promise<void>;

  /**
   * Create sketch for thing (legacy)
   * @param id - Thing ID
   * @param thingSketch - Sketch configuration payload
   * @returns Promise<ArduinoThing> - Thing object with sketch information
   */
  thingsV1CreateSketch(id: string, thingSketch: ThingSketch, opts?: any): Promise<ArduinoThing>;

  /**
   * Update existing thing sketch (legacy)
   * @param id - Thing ID
   * @param sketchId - Sketch ID
   * @returns Promise<ArduinoThing> - Updated thing object
   */
  thingsV1UpdateSketch(id: string, sketchId: string, opts?: any): Promise<ArduinoThing>;

  /**
   * Delete thing sketch (legacy)
   * @param id - Thing ID
   * @returns Promise<ArduinoThing> - Thing object without sketch
   */
  thingsV1DeleteSketch(id: string, opts?: any): Promise<ArduinoThing>;

  /**
   * Get thing layout without last values data (legacy)
   * @param id - Thing ID
   * @param opts - Optional parameters including showDeleted flag
   * @returns Promise<ArduinoThinglayout> - Thing layout information
   */
  thingsV1Layout(id: string, opts?: any): Promise<ArduinoThinglayout>;
}

Migration Note: V1 API has different payload structures and behavior compared to V2. V2 provides improved validation, better error handling, enhanced filtering options, and more consistent API patterns.

Data Models

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

interface ThingCreate {
  assistantId?: string;
  deviceId?: string;
  id?: string;
  name: string;
  properties?: ArduinoProperty[];
  timezone?: string;
  webhookActive?: boolean;
  webhookUri?: string;
}

interface ThingUpdate {
  assistantId?: string;
  deviceId?: string;
  name?: string;
  properties?: ArduinoProperty[];
  timezone?: string;
  webhookActive?: boolean;
  webhookUri?: string;
}

interface ThingClone {
  includeProperties?: boolean;
  name: string;
}

interface ThingSketch {
  sketchVersion?: string;
}

interface UpdateSketch {
  name?: string;
  sketchVersion?: string;
}

interface ArduinoThingtemplate {
  name?: string;
  properties?: ArduinoTemplateproperty[];
  timezone?: string;
  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;
}

enum PropertyPermission {
  READ_ONLY = 'READ_ONLY',
  READ_WRITE = 'READ_WRITE'
}

enum PropertyType {
  BOOL = 'BOOL',
  INT = 'INT',
  FLOAT = 'FLOAT',
  STRING = 'STRING',
  PERCENT = 'PERCENT',
  TEMPERATURE = 'TEMPERATURE',
  HUMIDITY = 'HUMIDITY',
  PRESSURE = 'PRESSURE'
}

enum PropertyUpdateStrategy {
  ON_CHANGE = 'ON_CHANGE',
  TIMED = 'TIMED'
}

Complete Thing Management Example:

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

// Initialize APIs
const thingsApi = new ArduinoIotClient.ThingsV2Api();
const thingsV2TagsApi = new ArduinoIotClient.ThingsV2TagsApi();

async function createCompleteThingSetup() {
  try {
    // Create a thing with initial properties
    const thing = await thingsApi.thingsV2Create({
      name: "Environmental Monitor",
      deviceId: "your-device-id",
      timezone: "America/New_York",
      webhookActive: true,
      webhookUri: "https://example.com/webhooks/environmental-data",
      properties: [
        {
          name: "Temperature",
          type: "TEMPERATURE",
          permission: "READ_ONLY",
          updateStrategy: "ON_CHANGE",
          variableName: "temperature",
          persist: true
        },
        {
          name: "Humidity",
          type: "HUMIDITY",
          permission: "READ_ONLY",
          updateStrategy: "TIMED",
          updateParameter: 30, // seconds
          variableName: "humidity",
          persist: true
        },
        {
          name: "Fan Control",
          type: "BOOL",
          permission: "READ_WRITE",
          updateStrategy: "ON_CHANGE",
          variableName: "fanEnabled",
          persist: false
        }
      ]
    });

    console.log('Created thing:', thing.id);

    // Add organizational tags
    await thingsV2TagsApi.thingsV2TagsUpsert(thing.id, {
      key: "location",
      value: "office-building-a"
    });

    await thingsV2TagsApi.thingsV2TagsUpsert(thing.id, {
      key: "type",
      value: "environmental-sensor"
    });

    await thingsV2TagsApi.thingsV2TagsUpsert(thing.id, {
      key: "criticality",
      value: "high"
    });

    // Create Arduino sketch for the thing
    await thingsApi.thingsV2CreateSketch(thing.id, {
      sketchVersion: "1.0.0"
    });

    // Verify the complete setup
    const completeThing = await thingsApi.thingsV2Show(thing.id, {
      showProperties: true
    });

    console.log('Thing setup complete:');
    console.log('- Name:', completeThing.name);
    console.log('- Properties:', completeThing.properties.length);
    console.log('- Sketch ID:', completeThing.sketchId);

    // Get template for replication
    const template = await thingsApi.thingsV2Template(thing.id);
    console.log('Template created for future replication');

    return thing;

  } catch (error) {
    console.error('Thing setup failed:', error);
    throw error;
  }
}

// Usage with error handling
async function manageThings() {
  try {
    // Create the setup
    const thing = await createCompleteThingSetup();

    // Later, clone for testing
    const testThing = await thingsApi.thingsV2Clone(thing.id, {
      name: "Environmental Monitor - Test",
      includeProperties: true
    });

    console.log('Test thing created:', testThing.id);

    // List all things to verify
    const allThings = await thingsApi.thingsV2List({
      showProperties: false,
      size: 100
    });

    console.log('Total things:', allThings.length);

  } catch (error) {
    if (error.status === 400) {
      console.error('Bad request - check thing parameters');
    } else if (error.status === 404) {
      console.error('Thing not found');
    } else {
      console.error('API Error:', error.detail || error.message);
    }
  }
}

Advanced Thing Patterns:

// Bulk thing operations
async function bulkThingOperations() {
  // Get all things and filter by tags
  const allThings = await thingsApi.thingsV2List({ size: 1000 });

  for (const thing of allThings) {
    try {
      // Get tags for each thing
      const tags = await thingsV2TagsApi.thingsV2TagsList(thing.id);

      if (tags.environment === 'production') {
        // Update production things with monitoring webhook
        await thingsApi.thingsV2Update(thing.id, {
          webhookActive: true,
          webhookUri: 'https://monitoring.example.com/webhook'
        });
        console.log('Updated production thing:', thing.name);
      }
    } catch (error) {
      console.error(`Failed to update thing ${thing.id}:`, error);
    }
  }
}

// Thing lifecycle management
async function thingLifecycle(thingId) {
  // Check thing status
  const thing = await thingsApi.thingsV2Show(thingId);

  if (!thing.deviceId) {
    console.log('Thing not associated with device - associating...');
    // Associate with available device
    const availableDeviceId = await findAvailableDevice();
    await thingsApi.thingsV2Update(thingId, {
      deviceId: availableDeviceId
    });
  }

  if (!thing.sketchId) {
    console.log('Thing has no sketch - creating...');
    await thingsApi.thingsV2CreateSketch(thingId, {
      sketchVersion: '1.0.0'
    });
  }

  console.log('Thing lifecycle check complete');
}

Install with Tessl CLI

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

docs

automation-triggers.md

dashboard-management.md

device-management.md

index.md

lora-device-management.md

network-credentials.md

property-management.md

thing-management.md

timeseries-analytics.md

tile.json