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

property-management.mddocs/

Property Management

Real-time property value management, timeseries data access, and property configuration. Properties are the individual data points or controls within IoT things that represent sensor readings, actuator states, or configuration values.

Capabilities

Core Property Operations

Primary property management functionality for CRUD operations on thing properties.

class PropertiesV2Api {
  /**
   * Create a new property for a thing
   * @param id - Thing ID
   * @param property - Property configuration including type, permissions, and update strategy
   * @param opts - Optional parameters including organization ID
   * @returns Promise<ArduinoProperty> - Created property object
   */
  propertiesV2Create(id: string, property: Property, opts?: any): Promise<ArduinoProperty>;

  /**
   * List all properties for a thing
   * @param id - Thing ID
   * @param opts - Optional parameters including organization ID and show_deleted flag
   * @returns Promise<ArduinoProperty[]> - Array of property objects
   */
  propertiesV2List(id: string, opts?: any): Promise<ArduinoProperty[]>;

  /**
   * Get detailed information about a specific property
   * @param id - Thing ID
   * @param pid - Property ID
   * @param opts - Optional parameters including organization ID and show_deleted flag
   * @returns Promise<ArduinoProperty> - Property object with full details
   */
  propertiesV2Show(id: string, pid: string, opts?: any): Promise<ArduinoProperty>;

  /**
   * Update property configuration and metadata
   * @param id - Thing ID
   * @param pid - Property ID
   * @param property - Updated property configuration
   * @param opts - Optional parameters including organization ID
   * @returns Promise<ArduinoProperty> - Updated property object
   */
  propertiesV2Update(id: string, pid: string, property: Property, opts?: any): Promise<ArduinoProperty>;

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

  /**
   * Publish a new value to a property (real-time data update)
   * @param id - Thing ID
   * @param pid - Property ID
   * @param propertyValue - New property value with optional metadata
   * @param opts - Optional parameters including organization ID
   * @returns Promise<void>
   */
  propertiesV2Publish(id: string, pid: string, propertyValue: PropertyValue, opts?: any): Promise<void>;

  /**
   * Get time series data for a property
   * @param id - Thing ID
   * @param pid - Property ID
   * @param opts - Optional parameters including time range, aggregation, and organization ID
   * @returns Promise<ArduinoSeriesResponse> - Time series data with statistics
   */
  propertiesV2Timeseries(id: string, pid: string, opts?: any): Promise<ArduinoSeriesResponse>;
}

Usage Examples:

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

const propertiesApi = new ArduinoIotClient.PropertiesV2Api();

// Create a temperature sensor property
const temperatureProperty = await propertiesApi.propertiesV2Create('thing-id', {
  name: 'Temperature',
  type: 'TEMPERATURE',
  permission: 'READ_ONLY',
  updateStrategy: 'ON_CHANGE',
  variableName: 'temperature',
  persist: true,
  minValue: -40,
  maxValue: 85
});

// Create a controllable LED property
const ledProperty = await propertiesApi.propertiesV2Create('thing-id', {
  name: 'LED Status',
  type: 'BOOL',
  permission: 'READ_WRITE',
  updateStrategy: 'ON_CHANGE',
  variableName: 'ledEnabled',
  persist: false
});

// Publish a new temperature reading
await propertiesApi.propertiesV2Publish('thing-id', temperatureProperty.id, {
  value: 23.5,
  createdAt: new Date().toISOString()
});

// Control the LED
await propertiesApi.propertiesV2Publish('thing-id', ledProperty.id, {
  value: true
});

// Get property timeseries data for the last hour
const timeseries = await propertiesApi.propertiesV2Timeseries('thing-id', temperatureProperty.id, {
  from: new Date(Date.now() - 3600000).toISOString(), // 1 hour ago
  to: new Date().toISOString()
});

console.log('Temperature data points:', timeseries.data.length);

Property Types

Property type definitions and available property types for different sensor and actuator configurations.

class PropertyTypesV1Api {
  /**
   * Get list of all available property types with their configurations
   * @param opts - Optional parameters including organization ID
   * @returns Promise<ArduinoPropertytype[]> - Array of available property types
   */
  propertyTypesV1ListTypes(opts?: any): Promise<ArduinoPropertytype[]>;
}

Usage Example:

const propertyTypesApi = new ArduinoIotClient.PropertyTypesV1Api();

// Get all available property types
const propertyTypes = await propertyTypesApi.propertyTypesV1ListTypes();

console.log('Available property types:');
propertyTypes.forEach(type => {
  console.log(`- ${type.name}: ${type.description}`);
});

// Find specific property type
const temperatureType = propertyTypes.find(type => type.name === 'TEMPERATURE');
console.log('Temperature type config:', temperatureType);

Legacy Property Operations (V1 API)

Legacy property management functionality for backward compatibility. Use PropertiesV2Api for new integrations.

class PropertiesV1Api {
  /**
   * Create a new property associated to a thing (legacy)
   * @param id - The thing ID
   * @param property - Property configuration payload
   * @param opts - Optional parameters
   * @returns Promise<ArduinoProperty> - Created property object
   */
  propertiesV1Create(id: string, property: Property, opts?: any): Promise<ArduinoProperty>;

  /**
   * Remove a property associated to a thing (legacy)
   * @param id - The thing ID
   * @param pid - The property ID
   * @param opts - Optional parameters including force delete flag
   * @returns Promise<void>
   */
  propertiesV1Delete(id: string, pid: string, opts?: any): Promise<void>;

  /**
   * List properties associated to a thing (legacy)
   * @param id - The thing ID
   * @param opts - Optional parameters including showDeleted flag
   * @returns Promise<ArduinoProperty[]> - Array of property objects
   */
  propertiesV1List(id: string, opts?: any): Promise<ArduinoProperty[]>;

  /**
   * Publish a property value to MQTT as string (legacy)
   * @param id - The thing ID
   * @param pid - The property ID
   * @param propertyStringValue - Property value payload as string
   * @returns Promise<void>
   */
  propertiesV1Send(id: string, pid: string, propertyStringValue: PropertyStringValue, opts?: any): Promise<void>;

  /**
   * Get property details (legacy)
   * @param id - The thing ID
   * @param pid - The property ID
   * @param opts - Optional parameters including showDeleted flag
   * @returns Promise<ArduinoProperty> - Property object
   */
  propertiesV1Show(id: string, pid: string, opts?: any): Promise<ArduinoProperty>;

  /**
   * Update property configuration (legacy)
   * @param id - The thing ID
   * @param pid - The property ID
   * @param property - Updated property configuration
   * @returns Promise<ArduinoProperty> - Updated property object
   */
  propertiesV1Update(id: string, pid: string, property: Property, opts?: any): Promise<ArduinoProperty>;
}

Migration Note: The V1 API uses different method signatures and behavior compared to V2. For new projects, use PropertiesV2Api which provides better type safety, improved error handling, and enhanced functionality.

Data Models

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

interface Property {
  maxValue?: number;
  minValue?: number;
  name: string;
  permission: PropertyPermission;
  persist?: boolean;
  tag?: number;
  type: PropertyType;
  updateParameter?: number;
  updateStrategy: PropertyUpdateStrategy;
  variableName?: string;
}

interface PropertyValue {
  createdAt?: string;
  value: any;
}

interface ArduinoPropertytype {
  description?: string;
  name?: string;
  type?: string;
}

interface ArduinoSeriesResponse {
  aggregation?: string;
  countValues?: number;
  data?: TimeseriesDataPoint[];
  fromDate?: Date;
  interval?: number;
  query?: string;
  serieLimit?: number;
  status?: string;
  thingId?: string;
  toDate?: Date;
  values?: any[];
}

interface TimeseriesDataPoint {
  timestamp?: Date;
  value?: any;
}

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',
  ACCELERATION = 'ACCELERATION',
  GYROSCOPE = 'GYROSCOPE',
  MAGNETOMETER = 'MAGNETOMETER',
  GPS = 'GPS',
  ENERGY = 'ENERGY',
  POWER = 'POWER',
  VOLTAGE = 'VOLTAGE',
  CURRENT = 'CURRENT',
  FREQUENCY = 'FREQUENCY',
  ANGLE = 'ANGLE',
  LENGTH = 'LENGTH',
  MASS = 'MASS',
  VELOCITY = 'VELOCITY',
  VOLUME = 'VOLUME',
  FLOW_RATE = 'FLOW_RATE',
  AREA = 'AREA',
  LUMINANCE = 'LUMINANCE',
  ILLUMINANCE = 'ILLUMINANCE',
  SOUND_PRESSURE_LEVEL = 'SOUND_PRESSURE_LEVEL',
  ELECTRIC_CHARGE = 'ELECTRIC_CHARGE',
  ELECTRIC_POTENTIAL = 'ELECTRIC_POTENTIAL',
  CAPACITANCE = 'CAPACITANCE',
  RESISTANCE = 'RESISTANCE',
  CONDUCTANCE = 'CONDUCTANCE',
  MAGNETIC_FIELD_STRENGTH = 'MAGNETIC_FIELD_STRENGTH',
  MAGNETIC_FLUX_DENSITY = 'MAGNETIC_FLUX_DENSITY',
  INDUCTANCE = 'INDUCTANCE'
}

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

Comprehensive Property Management Example:

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

const propertiesApi = new ArduinoIotClient.PropertiesV2Api();
const propertyTypesApi = new ArduinoIotClient.PropertyTypesV1Api();

async function createSensorThingWithProperties(thingId) {
  try {
    // Get available property types
    const propertyTypes = await propertyTypesApi.propertyTypesV1ListTypes();
    console.log('Available property types:', propertyTypes.length);

    // Create multiple sensor properties
    const properties = [];

    // Temperature sensor (read-only, on-change)
    const tempProperty = await propertiesApi.propertiesV2Create(thingId, {
      name: 'Temperature',
      type: 'TEMPERATURE',
      permission: 'READ_ONLY',
      updateStrategy: 'ON_CHANGE',
      variableName: 'temperature',
      persist: true,
      minValue: -40,
      maxValue: 85
    });
    properties.push(tempProperty);

    // Humidity sensor (read-only, timed updates every 30 seconds)
    const humidityProperty = await propertiesApi.propertiesV2Create(thingId, {
      name: 'Humidity',
      type: 'HUMIDITY',
      permission: 'READ_ONLY',
      updateStrategy: 'TIMED',
      updateParameter: 30,
      variableName: 'humidity',
      persist: true,
      minValue: 0,
      maxValue: 100
    });
    properties.push(humidityProperty);

    // Pressure sensor (read-only, on-change)
    const pressureProperty = await propertiesApi.propertiesV2Create(thingId, {
      name: 'Pressure',
      type: 'PRESSURE',
      permission: 'READ_ONLY',
      updateStrategy: 'ON_CHANGE',
      variableName: 'pressure',
      persist: true,
      minValue: 300,
      maxValue: 1100
    });
    properties.push(pressureProperty);

    // LED control (read-write, on-change)
    const ledProperty = await propertiesApi.propertiesV2Create(thingId, {
      name: 'Status LED',
      type: 'BOOL',
      permission: 'READ_WRITE',
      updateStrategy: 'ON_CHANGE',
      variableName: 'statusLed',
      persist: false
    });
    properties.push(ledProperty);

    // Fan speed control (read-write, on-change)
    const fanProperty = await propertiesApi.propertiesV2Create(thingId, {
      name: 'Fan Speed',
      type: 'PERCENT',
      permission: 'READ_WRITE',
      updateStrategy: 'ON_CHANGE',
      variableName: 'fanSpeed',
      persist: false,
      minValue: 0,
      maxValue: 100
    });
    properties.push(fanProperty);

    console.log(`Created ${properties.length} properties for thing ${thingId}`);
    return properties;

  } catch (error) {
    console.error('Failed to create properties:', error);
    throw error;
  }
}

// Simulate sensor data publishing
async function publishSensorData(thingId, properties) {
  try {
    const [tempProp, humidityProp, pressureProp, ledProp, fanProp] = properties;

    // Publish sensor readings
    await propertiesApi.propertiesV2Publish(thingId, tempProp.id, {
      value: 22.5 + Math.random() * 5, // Simulated temperature
      createdAt: new Date().toISOString()
    });

    await propertiesApi.propertiesV2Publish(thingId, humidityProp.id, {
      value: 45 + Math.random() * 20, // Simulated humidity
      createdAt: new Date().toISOString()
    });

    await propertiesApi.propertiesV2Publish(thingId, pressureProp.id, {
      value: 1013 + Math.random() * 20, // Simulated pressure
      createdAt: new Date().toISOString()
    });

    console.log('Published sensor data');

    // Control actuators based on sensor data
    const tempTimeseries = await propertiesApi.propertiesV2Timeseries(thingId, tempProp.id, {
      from: new Date(Date.now() - 300000).toISOString(), // Last 5 minutes
      to: new Date().toISOString()
    });

    if (tempTimeseries.data && tempTimeseries.data.length > 0) {
      const lastTemp = tempTimeseries.data[tempTimeseries.data.length - 1].value;

      // Turn on LED if temperature is above 25°C
      await propertiesApi.propertiesV2Publish(thingId, ledProp.id, {
        value: lastTemp > 25
      });

      // Set fan speed based on temperature
      let fanSpeed = 0;
      if (lastTemp > 25) {
        fanSpeed = Math.min(100, (lastTemp - 25) * 20); // 20% per degree above 25°C
      }

      await propertiesApi.propertiesV2Publish(thingId, fanProp.id, {
        value: fanSpeed
      });

      console.log(`Temperature: ${lastTemp}°C, LED: ${lastTemp > 25}, Fan: ${fanSpeed}%`);
    }

  } catch (error) {
    console.error('Failed to publish sensor data:', error);
  }
}

// Property analysis and monitoring
async function analyzePropertyData(thingId, propertyId, hours = 24) {
  try {
    const fromDate = new Date(Date.now() - hours * 3600000);
    const toDate = new Date();

    const timeseries = await propertiesApi.propertiesV2Timeseries(thingId, propertyId, {
      from: fromDate.toISOString(),
      to: toDate.toISOString(),
      interval: 300 // 5-minute intervals
    });

    if (timeseries.data && timeseries.data.length > 0) {
      const values = timeseries.data.map(point => parseFloat(point.value));

      const stats = {
        count: values.length,
        min: Math.min(...values),
        max: Math.max(...values),
        average: values.reduce((sum, val) => sum + val, 0) / values.length,
        latest: values[values.length - 1],
        timeRange: {
          from: timeseries.fromDate,
          to: timeseries.toDate
        }
      };

      console.log('Property statistics:', stats);
      return stats;
    } else {
      console.log('No data found for the specified time range');
      return null;
    }

  } catch (error) {
    console.error('Failed to analyze property data:', error);
    throw error;
  }
}

// Usage example with error handling
async function propertyManagementDemo(thingId) {
  try {
    // Create properties
    const properties = await createSensorThingWithProperties(thingId);

    // Start data publishing simulation
    console.log('Starting sensor data simulation...');

    for (let i = 0; i < 10; i++) {
      await publishSensorData(thingId, properties);
      await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
    }

    // Analyze temperature data
    console.log('Analyzing temperature data...');
    await analyzePropertyData(thingId, properties[0].id, 1); // Last hour

    // List all properties to verify
    const allProperties = await propertiesApi.propertiesV2List(thingId);
    console.log(`Thing has ${allProperties.length} properties total`);

    allProperties.forEach(prop => {
      console.log(`- ${prop.name} (${prop.type}): Last value = ${prop.lastValue}`);
    });

  } catch (error) {
    if (error.status === 400) {
      console.error('Bad request - check property configuration');
    } else if (error.status === 404) {
      console.error('Thing or property not found');
    } else {
      console.error('Property management error:', error.detail || error.message);
    }
  }
}

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