Milesight Load Controller API

Description

The Milesight Load Controller API is a microservice built using the NestJS framework. It serves as a command hub for managing Milesight WS558 load controllers through lorawan downlink commands. This service is responsible for:

• Managing load controller pin states
• Configuring device reporting intervals
• Handling device discovery and listing
• Coordinating with AWS IoT and Wireless IoT services
• Managing downlink message delivery through RabbitMQ

Core Features

Device Management

• Device Discovery: List and manage Milesight load controller devices
• Pin Control: Granular control over individual device pins
• Reporting Configuration: Customizable device reporting intervals
• Multi-vendor Support: Native support for Milesight WS558 load controllers

Command Processing

• Downlink Management: Robust downlink command processing
• State Control: Comprehensive pin state management
• Message Queue Integration: RabbitMQ-based command distribution

Architecture

Core Components

1. API Layer:

   • RESTful endpoints for device control
   • Validation pipeline
   • Error handling

2. Service Layer:

   • Load Controller Service: Handles device-specific command logic
   • Downlink Service: Manages message queue operations
   • AWS Integration Service: Handles AWS IoT operations

3. Integration Points:

   • AWS IoT Core
   • AWS IoT Wireless
   • RabbitMQ message queue

Requirements

• Node 20.15.0
• RabbitMQ 3.9.11
• AWS Account with IoT Core access

Additional Requirements for Docker

• Docker 20.10^
• Docker Compose 1.27^

Configuration

Environment Variables

| Variable Name | Description | Default Value | Required | |--------------|-------------|---------------|-----------| | NODE_ENV | Application environment | development | Yes | | STAGE | Deployment stage | development | Yes | | MILESIGHT_LOAD_CONTROLLER_API_PORT | API port | 9061 | Yes | | MILESIGHT_LOAD_CONTROLLER_DOWNLINK_FPORT | Downlink port | 85 | Yes | | AMQP_HOST | RabbitMQ host | localhost | Yes | | AMQP_USERNAME | RabbitMQ username | guest | Yes | | AMQP_PASSWORD | RabbitMQ password | guest | Yes | | AMQP_PORT | RabbitMQ port | 5672 | Yes | | AMQP_VHOST | RabbitMQ virtual host | / | Yes | | AMQP_PREFETCH | RabbitMQ prefetch count | 200 | Yes | | AMQP_DOWNLINK_EXCHANGE | RabbitMQ exchange | hardware.downlinkexchange | Yes | | AWS_REGION | AWS region | us-east-1 | Yes | | AWS_ACCESS_KEY_ID | AWS access key | - | Yes | | AWS_SECRET_ACCESS_KEY | AWS secret key | - | Yes | | ELASTIC_APM_ENABLED | Enable/disable Elastic APM | false | No | | ELASTIC_APM_SERVER_URL | Elastic APM server URL | http://localhost:8200 | No | | TRANSACTION_SAMPLE_RATE | APM transaction sample rate | 1.0 | No | | ELASTIC_APM_SECRET_TOKEN | Elastic APM secret token | - | No |

Installation

$ npm install

Running the app

# development
$ npm run start

# watch mode
$ npm run start:dev

# production mode
$ npm run start:prod

Test

# unit tests
$ npm run test

# e2e tests
$ npm run test:e2e

# test coverage
$ npm run test:cov

Service Dependencies

The Load Controller API provides the following core functionalities:

Device Management

• List available load controllers
• Control device pin states
• Configure reporting intervals
• Endpoints:

  • GET /load-controller

    // Query Parameters
    {
      maxResult?: number; // 1-250, default 25
      nextToken?: string;
    }
    
    // Response
    {
      "message": "Retrieved device list details",
      "result": {
        "things": [...],
        "nextToken": "..."
      }
    }

  • POST /load-controller/pin-status

    // Request Body
    {
      "deviceEui": "string",
      "serialNumber": "string", // optional
      "pinStatus": {
        "key": boolean // e.g., {"0": true, "1": false}
      }
    }
    
    // Response
    {
      "message": "Successfully sent set pin status command",
      "result": true
    }

  • POST /load-controller/reporting-interval

    // Request Body
    {
      "deviceEui": "string",
      "serialNumber": "string", // optional
      "seconds": number // 60-1800 seconds
    }
    
    // Response
    {
      "message": "Successfully sent set reporting interval command",
      "result": true
    }

External Service Dependencies

The service integrates with the following external services:

| Service | Purpose | |---------|----------| | AWS IoT Core | Device management and discovery | | AWS IoT Wireless | LoRaWAN communication | | RabbitMQ | Message queue for downlink commands |

Monitoring and Logging

• Standardized logging through NestJS Logger
• Error tracking and debugging support
• APM integration for performance monitoring
• RabbitMQ message tracking

License

This project is proprietary software. All rights reserved. This source code is protected under international copyright law. No part of this source code may be reproduced, distributed, or transmitted in any form or by any means, including photocopying, recording, or other electronic or mechanical methods, without the prior written permission of GlacierGrid.

Version: 2024.11.14
Author: Jeff Robert Dagala
Copyright: © 2024 GlacierGrid. All rights reserved.