Energy Manager IoT

A Node.js library for efficient energy management in IoT devices through MQTT protocol.

📚 Full Documentation

Features

• Robust MQTT connectivity with automatic reconnection support
• Device management with unique IDs and flexible grouping
• Send commands to individual devices or groups (e.g., "sleep", "wake")
• Receive and store device status (e.g., battery level, power mode)
• Group analytics, such as average battery level and power mode distribution
• Full TypeScript support with strong typing
• Professional logging system with contextual tracking and correlation IDs
• Comprehensive error handling with categorized errors and severity levels

Installation

npm install energy-manager-iot

Usage Guide

Initial Setup

1. Import the library:

   import { EnergyManager, DeviceType, CommandType } from 'energy-manager-iot';

2. Create a manager instance:

   const manager = new EnergyManager({
     topicPrefix: 'home/devices/', // Prefix for MQTT topics
     mqttOptions: { clientId: 'my-application' },
     statusInterval: 60000 // Status check every 60 seconds
   });

3. Connect to the MQTT broker:

   await manager.connect('mqtt://localhost:1883', { username: 'user', password: 'password' });

Device Registration and Management

• Register devices:

  manager.registerDevice('sensor1', 'Temperature Sensor', DeviceType.SENSOR, {
    reportingInterval: 60, // In seconds
    sleepThreshold: 20     // Enter sleep mode when battery below 20%
  });

• Create groups and add devices:

  manager.createGroup('living-room');
  manager.addDeviceToGroup('sensor1', 'living-room');

• Send commands to a device or group:

  await manager.sendCommand('sensor1', CommandType.SET_REPORTING, { interval: 300 });
  await manager.sleepGroup('living-room', 3600); // Hibernate the group for 1 hour

Monitoring and Events

The library emits useful events for monitoring:

// Listen to events:
manager.on('connected', () => console.log('Connected to MQTT broker'));
manager.on('statusUpdate', (deviceId, status) => console.log(`Status for ${deviceId}:`, status));
manager.on('deviceOffline', (deviceId) => console.log(`Device ${deviceId} went offline`));
manager.on('commandSent', (deviceId, command) => console.log(`Command sent to ${deviceId}:`, command));

• To finalize, disconnect:

  await manager.disconnect();

Examples

Check the /examples folder for detailed usage examples:

• basic-usage.ts: Basic usage example.
• group-management.ts: Advanced group management.
• device-simulator.ts: IoT device simulator.
• advanced-usage.ts: Advanced example with monitoring and group commands.

Additional Examples

• Run npm run example:simulator to simulate devices and see EnergyManager in action.

API

Main Class

EnergyManager

The main entry point of the library.

// Create instance
const manager = new EnergyManager(options);

// Available options:
interface EnergyManagerOptions {
  topicPrefix?: string;        // MQTT topic prefix (default: 'device/')
  mqttOptions?: MqttHandlerOptions; // MQTT client options
  autoReconnect?: boolean;     // Auto reconnection (default: true)
  statusInterval?: number;     // Status check interval (ms) (default: 60000)
}

Main Methods

Method	Description
connect(brokerUrl, options?)	Connect to the MQTT broker
disconnect()	Disconnect from the MQTT broker
registerDevice(id, name, type, config?, groups?)	Register a new device
sendCommand(deviceId, command, payload?)	Send command to a device
sendCommandToGroup(groupName, command, payload?)	Send command to a group
getDevice(id)	Get information about a device
createGroup(name)	Create a device group
addDeviceToGroup(deviceId, groupName)	Add a device to a group
getGroupStatistics(groupName)	Get group statistics

Convenience Methods

Method	Description
sleepDevice(deviceId, duration?)	Put device in energy saving mode
wakeDevice(deviceId)	Wake device from energy saving mode
sleepGroup(groupName, duration?)	Put group in energy saving mode
wakeGroup(groupName)	Wake group from energy saving mode

Events

The EnergyManager class extends EventEmitter, allowing you to receive notifications:

// Listen to events
manager.on('connected', () => console.log('Connected'));
manager.on('disconnected', () => console.log('Disconnected'));
manager.on('statusUpdate', (deviceId, status) => console.log(`Status: ${deviceId}`, status));
manager.on('deviceOffline', (deviceId) => console.log(`Device offline: ${deviceId}`));
manager.on('commandSent', (deviceId, command) => console.log(`Command sent: ${deviceId}`, command));

Protocols and Standards

Status Format

Devices should publish their status in JSON format:

{
  "batteryLevel": 75,
  "powerMode": "normal",
  "connectionStatus": "online",
  "firmwareVersion": "1.2.3",
  "signalStrength": -67
}

Command Format

Commands are sent in the format:

{
  "type": "sleep",
  "payload": { "duration": 3600 },
  "timestamp": 1634567890123,
  "requestId": "req_1634567890123_abc123"
}

Advanced Logging

The library includes a professional logging system that helps with debugging, monitoring, and diagnostics.

import { Logger } from 'energy-manager-iot';

// Module-specific logger
const deviceLogger = Logger.child('devices');

// Log with correlation ID for tracking related operations
const operationLogger = deviceLogger.withCorrelationId('op-123456');
operationLogger.info('Starting device registration');

// Different log levels
deviceLogger.debug('Detailed information for troubleshooting');
deviceLogger.info('Normal operational messages');
deviceLogger.warn('Warning condition');
deviceLogger.error('Error condition', errorObject);

Advanced Logging Documentation

Error Handling

The library provides a comprehensive error handling system:

import { EnergyManagerError, ErrorType, ErrorSeverity } from 'energy-manager-iot';

try {
  // Some operation
} catch (error) {
  throw new EnergyManagerError(
    'Failed to connect to device',
    ErrorType.CONNECTION,
    { deviceId: 'temp-01' },
    ErrorSeverity.HIGH
  );
}

Security Considerations

• Use TLS/SSL (mqtts://) in production environments.
• Configure authentication and access control in the MQTT broker.
• Validate command payloads to prevent malicious information.
• Enable logging in production for security audit trails.

Developer

Jonh Alex Paz de Lima