Skip to main content

Nodes

The Node resource represents gateways and edge computing devices that serve as connectivity bridges between field devices and the IoT platform. Nodes are essential infrastructure components that enable communication, local processing, and data aggregation for devices that lack direct internet connectivity.

Overview​

A node acts as an intermediary communication hub that connects field devices (such as sensors without built-in connectivity) to the broader IoT platform. Nodes can range from simple gateways that relay data to sophisticated edge computing devices with full operating systems capable of running custom software and performing local data processing.

Key Properties​

Basic Information​

  • name (required): A distinguishable name for the node (e.g., "Gateway-Floor-4", "Edge-Computer-LineA")
  • description: Human-readable description of the node and its role (e.g., "This is the gateway for the 4th floor of the building")
  • projectId (required): The project this node belongs to
  • plantId: The plant where this node is physically installed

Connectivity and Status​

  • connectivityStatus: Current connection state to the platform
    • connected: Node is actively connected to the MQTT broker
    • disconnected: Node has lost connection to the platform

Location and Organization​

  • location: Geographical coordinates of the node's physical installation
  • tags: Array of alphanumeric tags for categorization and filtering

Metadata and Custom Properties​

  • metadata: Flexible key-value storage for custom attributes specific to the node

Lifecycle Management​

Lifecycle Status​

Nodes inherit full lifecycle management capabilities, tracking their operational state through various phases:

Available States​

  • created: Node has been registered in the system but not yet configured
  • provisioned: Node has been configured with necessary credentials and settings
  • active: Node is operational and actively facilitating device communications
  • maintenance: Node is temporarily offline for updates, repairs, or configuration changes
  • suspended: Node operations have been temporarily halted
  • decommissioned: Node has been permanently removed from service

State Transitions​

Nodes typically follow this lifecycle progression:

created → provisioned → active → [maintenance/suspended] → decommissioned

Nodes can transition between maintenance, suspended, and active states as operational requirements change.

Lifecycle Events​

The system maintains a complete audit trail of lifecycle changes through the lifecycleEvents array. Each event contains:

  • timestamp: When the lifecycle change occurred
  • authorId: Who initiated the change
  • type: The lifecycle state that was entered

This provides full traceability for compliance and operational monitoring.

Node Types and Capabilities​

Simple Gateways​

Basic nodes that primarily handle data relay and protocol translation:

  • Protocol Bridging: Convert between local protocols (Modbus, LoRaWAN, Zigbee) and platform protocols
  • Data Aggregation: Collect data from multiple devices before transmission
  • Basic Filtering: Apply simple data validation and filtering rules
  • Store and Forward: Buffer data during connectivity outages

Edge Computing Nodes​

Advanced nodes with full operating systems and computational capabilities:

  • Local Processing: Run custom software and analytics at the edge
  • Real-time Decision Making: Implement control logic without cloud dependencies
  • Data Preprocessing: Filter, aggregate, and transform data locally
  • Application Hosting: Run containerized applications and services
  • Local Storage: Maintain historical data and configuration locally

Connectivity Management​

Connection Monitoring​

The connectivityStatus field provides real-time visibility into node connectivity:

Connected State​

  • Node is actively communicating with the MQTT broker
  • Data flow is operational
  • Commands and configurations can be sent to the node
  • Device data is being relayed successfully

Disconnected State​

  • Node has lost connection to the platform
  • May indicate network issues, power problems, or node failure
  • Triggers alerts and monitoring workflows
  • Requires investigation and potential intervention

Network Requirements​

  • MQTT Connectivity: Primary communication protocol for platform integration
  • Secure Communications: TLS/SSL encryption for all data transmission
  • Credential Management: Secure storage and rotation of authentication credentials
  • Firewall Configuration: Appropriate network security policies

Device Integration​

Device Connectivity Patterns​

Nodes support various device connectivity methods:

Direct Connection​

  • Devices connect directly to the node via local protocols
  • Node handles protocol translation and data forwarding
  • Suitable for devices without internet capability

Mesh Networks​

  • Node serves as coordinator for mesh network topologies
  • Manages device registration and network routing
  • Provides redundancy and self-healing capabilities

Serial and Legacy Protocols​

  • Interface with older equipment using RS-485, Modbus, or proprietary protocols
  • Enable IoT connectivity for legacy industrial equipment
  • Bridge operational technology (OT) with information technology (IT)

Plant Consistency Requirements​

When devices specify a nodeId, both the node and device must belong to the same plant. This ensures:

  • Operational Coherence: Related resources are managed together
  • Network Topology: Proper representation of physical connectivity
  • Access Control: Consistent security boundaries
  • Maintenance Coordination: Unified planning and execution

Resource Management​

Base Resource Properties​

All nodes inherit standard resource properties:

  • uuid: Unique identifier (auto-generated if not provided)
  • createdAt: Resource creation timestamp
  • updatedAt: Last modification timestamp
  • metadata: Flexible key-value storage for custom attributes

Project and Plant Association​

Nodes must be associated with both a project and typically a plant:

  • Project Association: Enables access control, billing, and multi-tenant isolation
  • Plant Association: Provides location-based organization and management
  • Operational Boundaries: Defines management and maintenance responsibilities