Types and Interfaces
This page documents the main TypeScript types and interfaces used throughout the Energy Manager IoT library.
Device Types
DeviceType
Enum that classifies different IoT device categories:
enum DeviceType {
/** Device that collects environmental or system data */
SENSOR = 'sensor',
/** Device that captures visual data */
CAMERA = 'camera',
/** Device that controls or affects physical systems */
ACTUATOR = 'actuator',
/** Device that connects and bridges other devices */
GATEWAY = 'gateway',
/** General purpose device that doesn't fit other categories */
GENERIC = 'generic'
}
DeviceConfig
Interface that defines configurable parameters for IoT devices:
interface DeviceConfig {
/** Reporting interval in seconds */
reportingInterval?: number;
/** Battery level percentage threshold to enter sleep mode */
sleepThreshold?: number;
/** Whether device should automatically wake after sleep period */
autoWake?: boolean;
/** Security level from 1 (low) to 5 (high) */
securityLevel?: number;
}
Device
Core interface representing an IoT device in the system:
interface Device {
/** Unique identifier for the device */
id: string;
/** Human-readable name of the device */
name: string;
/** Classification of the device */
type: DeviceType;
/** Current operational status of the device (if known) */
status?: DeviceStatus;
/** Groups this device belongs to */
groups: string[];
/** Device configuration settings */
config: DeviceConfig;
/** Timestamp when the device was first registered (epoch milliseconds) */
createdAt: number;
/** Timestamp when the device was last updated (epoch milliseconds) */
updatedAt: number;
}
Status Types
PowerMode
Enum representing different energy consumption states of a device:
enum PowerMode {
/** Normal operation mode with full functionality */
NORMAL = 'normal',
/** Reduced power consumption mode with limited functionality */
LOW_POWER = 'low_power',
/** Minimal power consumption hibernation mode */
SLEEP = 'sleep',
/** Emergency mode due to critically low battery */
CRITICAL = 'critical'
}
ConnectionStatus
Enum representing the current connectivity state of a device:
enum ConnectionStatus {
/** Device is connected and responsive */
ONLINE = 'online',
/** Device is disconnected or unresponsive */
OFFLINE = 'offline',
/** Device has unstable or intermittent connectivity */
INTERMITTENT = 'intermittent'
}
DeviceStatus
Interface representing the current operational state of a device:
interface DeviceStatus {
/** ID of the device this status belongs to */
deviceId: string;
/** Battery level as a percentage (0-100) */
batteryLevel: number;
/** Current power saving mode */
powerMode: PowerMode;
/** Current connection state */
connectionStatus: ConnectionStatus;
/** Timestamp of when the device was last seen (epoch milliseconds) */
lastSeen: number;
/** Optional firmware version string */
firmwareVersion?: string;
/** Optional signal strength in dBm */
signalStrength?: number;
/** Optional array of error messages */
errors?: string[];
/** Optional additional device-specific information */
additionalInfo?: Record<string, any>;
}
GroupStatistics
Interface providing aggregated statistics for a group of devices:
interface GroupStatistics {
/** Average battery level across all devices in the group */
averageBatteryLevel: number;
/** Distribution of devices across different power modes */
powerModeDistribution: Record<PowerMode, number>;
/** Number of devices currently online */
onlineCount: number;
/** Number of devices currently offline */
offlineCount: number;
/** Total number of devices in the group */
totalDevices: number;
}
Command Types
CommandType
Enum defining standard operations that can be performed on devices:
enum CommandType {
/** Put device into power saving mode */
SLEEP = 'sleep',
/** Exit power saving mode */
WAKE = 'wake',
/** Restart the device */
RESTART = 'restart',
/** Request firmware update */
UPDATE = 'update',
/** Configure status reporting interval */
SET_REPORTING = 'set_reporting_interval',
/** Request immediate status update */
GET_STATUS = 'get_status'
}
DeviceCommand
Interface for commands sent to IoT devices:
interface DeviceCommand {
/** Type of command to execute */
type: CommandType;
/** Optional data payload for the command */
payload?: any;
/** Timestamp when command was issued (epoch milliseconds) */
timestamp: number;
/** Optional unique identifier to correlate responses */
requestId?: string;
}
CommandResponse
Interface for responses from devices after processing commands:
interface CommandResponse {
/** Whether the command was successfully executed */
success: boolean;
/** Optional ID matching the original request */
requestId?: string;
/** Optional message providing additional context */
message?: string;
/** Timestamp when response was generated (epoch milliseconds) */
timestamp: number;
}
Error Types
ErrorType
Enum for categorizing different kinds of errors:
enum ErrorType {
CONNECTION = 'connection_error',
VALIDATION = 'validation_error',
AUTHENTICATION = 'authentication_error',
DEVICE_NOT_FOUND = 'device_not_found',
GROUP_NOT_FOUND = 'group_not_found',
COMMAND_FAILED = 'command_failed',
CONFIGURATION_ERROR = 'configuration_error',
TIMEOUT_ERROR = 'timeout_error',
MESSAGE_FORMAT_ERROR = 'message_format_error',
PROTOCOL_ERROR = 'protocol_error',
PERMISSION_DENIED = 'permission_denied',
RATE_LIMIT_EXCEEDED = 'rate_limit_exceeded',
INTERNAL_ERROR = 'internal_error'
}
ErrorSeverity
Enum for indicating the operational impact of an error:
enum ErrorSeverity {
/** Critical errors requiring immediate attention */
CRITICAL = 'critical',
/** High-impact errors affecting system functionality */
HIGH = 'high',
/** Medium-impact errors affecting specific features */
MEDIUM = 'medium',
/** Low-impact errors with minimal functional impact */
LOW = 'low'
}
EnergyManagerError
Custom error class with additional properties for error categorization and contextual data:
class EnergyManagerError extends Error {
/** Classification of the error */
readonly type: ErrorType;
/** Operational impact of the error */
readonly severity: ErrorSeverity;
/** Optional data related to the error context */
readonly data?: any;
/** Unique error code for lookup in documentation */
readonly code: string;
/** Timestamp when the error occurred */
readonly timestamp: Date;
/** Optional correlation ID for tracing related operations */
readonly correlationId?: string;
constructor(
message: string,
type: ErrorType,
data?: any,
severity: ErrorSeverity = ErrorSeverity.MEDIUM,
correlationId?: string
);
/**
* Returns a structured object representation of the error
* for logging or serialization
*/
toJSON(): object;
}
Usage Examples
Creating and Configuring a Device
import { DeviceType } from 'energy-manager-iot';
const device = {
id: 'temp-sensor-01',
name: 'Living Room Temperature',
type: DeviceType.SENSOR,
groups: ['living-room', 'temperature-sensors'],
config: {
reportingInterval: 60,
sleepThreshold: 15,
autoWake: true,
securityLevel: 2
},
createdAt: Date.now(),
updatedAt: Date.now()
};
Creating a Device Status Object
import { PowerMode, ConnectionStatus } from 'energy-manager-iot';
const status = {
deviceId: 'temp-sensor-01',
batteryLevel: 87,
powerMode: PowerMode.NORMAL,
connectionStatus: ConnectionStatus.ONLINE,
lastSeen: Date.now(),
firmwareVersion: '1.2.3',
signalStrength: -70
};
Creating a Device Command
import { CommandType } from 'energy-manager-iot';
const command = {
type: CommandType.SLEEP,
payload: {
duration: 3600 // Sleep for 1 hour
},
timestamp: Date.now(),
requestId: `req-${Date.now()}`
};