Introduction

NODA Intelligent Systems (NODA) is a spin-off company from research within artificial intelligence at Blekinge Institute of Technology, Sweden. NODA was founded in 2005 and currently has offices in Karlshamn and Malmö in Sweden.

NODA has customers and partners throughout Europe, North America and Asia. The focus of NODA is to develop and market AI-based solutions for thermal systems like district heating and cooling, heat pumps and gas.

In addition, NODA has a strong relationship with universities and research institutes in research and innovation. NODA works with several partners and customers to implement its technology and market approach. These partners range from large global companies to local and regional energy companies or building owners.

Traditionally, the focus of NODA has primarily been on district heating. Still, the last few years have seen an increased focus on hybrid systems based on thermal processes such as combined heat and power, heat pumps and excess heat extraction. This gives NODA a broad range of working knowledge of different types of systems and how they can be combined.

NODA works in the production and delivery chain regarding product development from core research to operational products and routinely participates in international and national research and innovation projects.

Products and services

NODA works with a wide variety of partners and we implement hardware or software integrations wherever needed. In addition, by avoiding tying oneself to a particular equipment manufacturer and relying on in-house software development, NODA is flexible enough to change when new requirements call for change.

EnergyView

This tool has evolved over the years. Its inception was back in 2009 under the working name Linckii. EnergyView is the primary tool for interacting with data stored from communication with field equipment and the output from our machine learning algorithms.

We deploy each customer domain on a separate database. Thus, creating partitions between customers to prevent accidental, unauthorized access.

EnergyView allows access to the time-series data through configurable time-series graphs. Users with more than basic access privileges can change most aspects of an installation.

The system also exposes essential objects as a REST API over HTTP. This interface allows for third-party interaction with the system.

My Pages

My Pages is a much simpler tool compared to EnergyView. Its demographic is customers who want a direct answer, not a philosophical discussion surrounding the question.

Here customers can see all control actions the NODA equipment has performed. They can also get an energy analysis of their heating system and energy consumption along with time-series graphs of their indoor sensors.

Self-host

The purpose of the NODA Self-host is to provide customers with an option to run the core components of the NODA system in their environment as their responsibility. This includes;

• API Server (Aapije)
• Program Server (Juvuln and Malgomaj)
• DBMS (PostgreSQL 12.0+)

These components are all Open Source and freely available for anyone to use without paying for the software. However, a negotiated support agreement is required for aid in deployment.

In a project, we expect customer-specific integrations and the addition of NODAs proprietary software.

Components such as;

• Machine Learning Algorithms (Kimaera)
• MQTT protocol translation bridges
• User interfaces

Document Notes

All information in this manual, including product data, diagrams, charts, etcetera. represents information on products at the time of publication, and is subject to change without prior notice due to product improvements or other reasons.

The documentation and product are provided on an "as is" basis only and may contain deficiencies or inadequacies. NODA Intelligent Systems AB takes no responsibility for damages, liabilities or other losses by using this product.

Copyright and trademark

© 2024, NODA Intelligent Systems AB.

All rights reserved. No part of the contents of this manual may be transmitted or reproduced in any form by any means without the written permission of NODA Intelligent Systems AB.

Contact information

NODA Intelligent Systems AB Headquarter

Biblioteksgatan 4
374 35 Karlshamn
SWEDEN

• 📞 Phone: +46 454 10 271
• 📧 E-Mail: info@noda.se

NODA Intelligent Systems AB Technical Support

• 📞 Phone: +46 454 10 271
• 📧 E-Mail: support@noda.se
• 🌎 Online: https://www.noda.se

NODA Glossary

This is a glossary of terms used in the NODA documentation.

District heating terminology

IT-infrastructure

Modbus terminology

Introduction

EnergyView is a cloud platform with a user interface (front-end) used to administer NODA's services. The platform consists of several components:

• Database system (single tenant) based on PostgreSQL.

• Login system (IdP - identity provider).

• User interface with a separate view for end users of the product NODA Building, referred to as My pages (Mina sidor).

• API that enables external systems to interact with NODA.

• Tools for configuring and administering services and creating reports that visualise data.

• Integrations for communication with customer installations.

• Back-end with a software architecture based on microservices that runs in Kubernetes. This document only further describes these services in cases where explaining the relationship to various NODA services is necessary.

The EnergyView platform is of the single tenant type, meaning customers have their own separate databases on separate customer domains. An advantage of this design is that each customer's data is completely separated from other customers' data.

Users

A user can access one or more customer domains. There are two types of users:

• EnergyView users who have access to EnergyView. These have four different levels of permissions: Basic (see data), Operator (manage settings), Administrator (full access), and API users.

• My pages users only have access to the My pages/Mina sidor module.

Introduction

EnergyView is a cloud platform with a user interface (front-end) used to administer NODA's services. The platform consists of several components:

• Database system (single tenant) based on PostgreSQL.

• Login system (IdP - identity provider).

• User interface with a separate view for end users of the product NODA Building, referred to as My pages (Mina sidor).

• API that enables external systems to interact with NODA.

• Tools for configuring and administering services and creating reports that visualise data.

• Integrations for communication with customer installations.

• Back-end with a software architecture based on microservices that runs in Kubernetes. This document only further describes these services in cases where explaining the relationship to various NODA services is necessary.

The EnergyView platform is of the single tenant type, meaning customers have their own separate databases on separate customer domains. An advantage of this design is that each customer's data is completely separated from other customers' data.

Users

A user can access one or more customer domains. There are two types of users:

• EnergyView users who have access to EnergyView. These have four different levels of permissions: Basic (see data), Operator (manage settings), Administrator (full access), and API users.

• My pages users only have access to the My pages/Mina sidor module.

Information Model

Each NODA customer has one or more domains on which collected data is stored.

Permission is granted per customer domain, meaning a user can access multiple customer domains. Upon logging in, users with access to numerous customer domains will arrive at a predefined home domain. In the dropdown menu at the top right, users see the domains they have permission for and can switch between domains in the menu (opens in a new window).

This structure means that EnergyView supports customers with one or more customer domains, where each domain has one or more users and one or more customer installations with various services activated.

A customer domain has several collectors, representing objects of a specific type with tags for data. A collector could, for example, mean an indoor sensor, a building, or something else. Collectors can be grouped into groups, which are used in various ways in NODA's services.

erDiagram
    CUSTOMER ||..|{ DOMAIN : "owns/has"
    CUSTOMER ||..o{ USER-ACCOUNT : "owns/has"
    USER-ACCOUNT ||--o{ DOMAIN : "has access to"
    DOMAIN ||--o{ COLLECTOR : contains
    COLLECTOR {
        text name
        text description
        lable type
        representation object
        number local-id
        UUID global-id
        text data-interface-id
    }
    COLLECTOR ||--o{ TAG : has
    TAG {
        text namne
        text description
        text unit
    }
    GROUP }|--|{ COLLECTOR : contains

Data Structure

Data points are systematised in EnergyView using the concepts of tag, protocol, device, and collector described in the sections below.

Tag

Data points are linked to tags, where a tag corresponds to a measured value or a computed value of a specific sort. Examples of a tag are indoor temperature, power, flow, etc. Measured values are saved in the database on a customer domain via tags.

Protocol

The top level of the structure for data storage on a customer domain in EnergyView is called a protocol. A protocol is a list of tags. Protocols define which tags exist and can be seen as a gross list. If a new tag is to be created, this is done by adding it to an existing or new protocol. Protocols are thus a high-level sorting of tags. They could, for example, be IoT sensors, properties, district heating systems, or similar.

Several objects and properties are used for further systematisation, described under Device and Collector below. In our environment at NODA, for example, we have used a master protocol for tags related to buildings, a protocol for indoor sensors, and a protocol for tags from the weather forecast service we use. Currently, tags are referred to as sensors, but it means the same thing.

Device

Under each protocol, devices that use the protocol are defined. A device has a limited subset of the tags on the protocol to which it belongs. Nothing prevents a device under a protocol from having all the tags on the protocol. Still, devices make it possible to systematise the structure of data. Protocols are the gross list of tags, and devices are net lists of tags. Examples of what devices can correspond to are meters, sensors, control systems, etc.

Collector

A collector is a node representing something which communicates data points with NODA, for example, a district heating substation in a multi-dwelling building, a sensor in an office, or something else. Several properties declare a collector:

• Name: Free text.
• Description: Free text.
• Device (see Device above): a collector is a device.
• Object representation: A label that describes what the collector represents, e.g., Residential building, Indoor climate sensor, Heating circuit, Network station, etc.
• Tags: The collector has access to the Device's tags, and it is possible to choose which tags should be activated on the collector.
• Identifiers created by the system:
  • Local identifier: A node ID, which is a serial number for the collector on the customer domain.
  • Global unique identifier: A UUID, which can be used to identify the collector via communication between different systems.
• Data interface identifier: This is an ID the user can set themselves and is used for matching when an ID comes from an external system. It is thus an ID that an external system has set, for example, a serial number on a sensor or a MAC address.

Sub-collectors

It is possible to define affiliations between collectors according to a parent-child principle. That is, a collector can be the child of another collector. For example, room sensors can be sub-collectors to a collector representing a building.

Groups

A group consists of collectors. A collector can belong to several groups. Groups are used to describe affiliation for collectors.

API

The EnergyView API comprises two distinct interfaces, namely APIv1 and APIv2. Both interfaces are currently maintained and undergo changes while ensuring backward compatibility.

APIv1

This interface, though older, remains in active use and was initially developed to fulfill our internal requirements. It primarily serves as a representation of the underlying structure of the EnergyView database.

The documentation for APIv1 is publicly accessible and can be located here.

APIv2

Introduced as a newer interface, APIv2 does not diminish the utility of the older APIv1. Its inception was a result of the development of our standalone data store solution, NODA Self-host, in 2021.

To facilitate seamless interoperability between EnergyView and the Self-host system, a compatibility interface was required. Consequently, most, though not all, of the Self-host API functionality was implemented in EnergyView.

The documentation for APIv2 is publicly available and can be found here.

Examples

Understanding the API documentation can be challenging without proper context. To mitigate this, we have created a website featuring examples to assist you. This resource, known as NODA by Example, aims to provide clarity and practical demonstrations.

Collector/Node

A collector is a node representing something which communicates data points with NODA, for example, a district heating substation in a multi-dwelling building, a sensor in an office, or something else. Several properties declare a collector:

• Name: Free text.

• Description: Free text.

• Device (see Device above): a collector is a device.

• Object representation: A label that describes what the collector represents, e.g., Residential building, Indoor climate sensor, Heating circuit, Network station, etc.

• Tags: The collector has access to the Device's tags, and it is possible to choose which tags should be activated on the collector.

• Identifiers created by the system:

  • Local identifier: A node ID, which is a serial number for the collector on the customer domain.

  • Global unique identifier: A UUID, which can be used to identify the collector via communication between different systems.

• Data interface identifier: This is an ID the user can set themselves and is used for matching when an ID comes from an external system. It is thus an ID that an external system has set, for example, a serial number on a sensor or a MAC address.

Error codes and explanations

Collector (Node) States Example

A Collector (Node) can have one of several different states. The system declare these states on a Device level. States are used to indicate the status of the Collector and are most often automatically managed by a Program. Still, some state transitions may require manual intervention.

%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'fontFamily': 'Atkinson Hyperlegible',
      'primaryColor': '#d53169',
      'primaryTextColor': '#fff',
      'primaryBorderColor': '#763454',
      'lineColor': '#111',
      'secondaryColor': '#fca034',
      'tertiaryColor': '#4582ec'
    }
  }
}%%

stateDiagram-v2
    [*] --> PreInstallation
    PreInstallation --> Deployed
    Deployed --> InUse
    InUse --> Inactive
    InUse --> Faulty
	InUse --> Decommissioned
    Inactive --> InUse
    Inactive --> Faulty
    Inactive --> Maintenance
    Faulty --> Maintenance
    Faulty --> Decommissioned
    Maintenance --> InUse
    Decommissioned --> [*]

Table description of the states:

State Flow

The above is an example of a typical state flow for a deployed Collector (Node). These states are just an example of a typical deployment, as the conditions are not fixed and can be modified per Device for each Domain.

A purpose-built Program declared in the Program Manager manages the different state transitions. It is thus easy to add new states and transition between states based on the requirements.

If a Collector (Node) is in a Faulty state, additional inquires can be made to determine the cause of the fault. The error timeseries on a Collector (Node) can be used to determine the cause of the fault. The value maps into the Errors table.

How To

Create and Deploy the Building Service via APIv1

This example shows creating and deploying a service via the EnergyView API version 1.

For details about the API, see the online API documentation.

Outline

1. Create a Control Node
2. Create several Climate Sensor Nodes
3. Deply the service on the Control Node
4. Update the service
5. Summary

Step 0: Prerequisites

You are going to need to have an API key to be able to interact with the API. You can create an API key in the EnergyView web interface if you have enough privileges. You need to contact your system administrator if you do not have enough privileges.

Each request is performed against https://customer.noda.se/{domain}/api/v1/... where {domain} is the domain name of your EnergyView instance. A customer may have several domains, and a separate database manages each domain. This item is sometimes also referred to as "site".

Step 1: Create a Control Node

The first step is to create a Control Node. This is the Node that will act as a representation of a single heating or cooling system. It will contain all the settings and data required for the algorithms to work.

The Control Node is created by sending a POST request to the /{domain}/api/v1/nodes endpoint.

The format of the request body is JSON, and the following is an example of a valid request body:

{
  "uuid": "12345678-1234-1234-1234-123456789012",
  "name": "My Control Node",
  "designation": "building",
  "description": "My Control Node for my building",
  "dataif": "optional string used as an identifier",
  "tags": [
    "operational_state",
    "outdoortemp",
    "outdoortemp_fake",
    "outdoortemp_offset",
    "returntemp_sec",
    "supplytemp_sec",
    "supplytemp_sec_controller_setvalue",
    "supplytemp_sec_offset",
    "meter_effect",
    "meter_heatenergy",
    "meter_primreturntemp",
    "meter_primsupplytemp",
    "meter_volume",
    "meter_volumeflow",
  ],
  "device": "ControlNode",
  "state": "pre-installation"
}

Table of the fields in the request body:

The response will be a 201 Created, and the response body will contain the created Node's serial ID and UUID.

{
  "id": 123,
  "uuid": "12345678-1234-1234-1234-123456789012"
}

Keep the serial ID or UUID of the created Node, as they will be used in the next step.

Step 2: Create Climate Sensor Nodes

The next step is to create Climate Sensor Nodes. These are the nodes that will act as a representation of a single indoor climate sensor. Each Climate Sensor Node will be associated with a Control Node.

The Climate Sensor Nodes are created individually by sending a POST request to the /{domain}/api/v1/nodes endpoint.

The format of the request body is JSON, and the following is an example of a valid request body:

{
  "uuid": "cafe1234-cafe-cafe-cafe-cafe12345678",
  "name": "My Climate Sensor Node #1",
  "designation": "sensor/indoor",
  "description": "One of several climate sensors",
  "dataif": "optional string used as an identifier",
  "tags": [
    "indoortemp"
  ],
  "parent": "12345678-1234-1234-1234-123456789012",
  "device": "Generic Indoor Sensor",
  "state": "pre-installation"
}

The description of the fields in the request body is the same as for the Control Node. With one exception, the parent is a required field that specifies the serial ID or UUID of the Control Node that the Climate Sensor Node should be associated with.

The response will be a 201 Created, and the response body will contain the created Node's serial ID and UUID.

{
  "id": 124,
  "uuid": "cafe1234-cafe-cafe-cafe-cafe12345678"
}

Repeat the process for each Climate Sensor Node you want to create.

Step 3: Deploy the Service

The last step is to deploy the service on the Control Node. This will enable the algorithms to start running.

The service is deployed by sending a POST request to the /{domain}/api/v1/nodes/{id}/provision endpoint, where {id} is the serial ID of the Control Node.

The format of the request body is JSON, and the following is an example of a valid request body:

{
  "active": true,
  "balance_temperature": 17,
  "idt_wanted": 21,
  "idt_min": 17
}

Table of the fields in the request body:

The response will be a 204 No Content, and the response body will be empty.

Step 4: Update the Service

A running service can be updated by repeating the same process as in step 3. The service will be updated with the new settings.

Set the active field to false to stop the service.

Summary

You have created a Control Node and Climate Sensor Nodes and deployed the service on the Control Node. The service will start running, and you can send data to the Climate Sensor Nodes via the time series API.

For details about the time series API, look at the API documentation.

Get the current status of a service via APIv1

TODO

Introduction

My Pages is a specific user portal for the NODA Building product, which helps property owners save energy and costs, achieve a more consistent indoor temperature, and enable the monitoring of the property's heat usage and indoor comfort over time.

The service is a cloud-based software that relies on data collection from the property and its substation to NODA's server. NODA uses the data to control heating more efficiently and to visualise the property's heat usage. Energy savings from the service are achieved by adjusting the heating of the radiator circuit inside the building to the actual needs of the property instead of just the outdoor temperature (the latter is the typical way to control heating in properties).

The system learns how the property uses energy by using room sensors for indoor temperature. By setting an indoor target temperature for the property, the service can control the heating towards this, thus avoiding unnecessary heating and maintaining a steady indoor temperature. The system also relies on weather forecasts to adjust the energy use to what is needed.

The user portal provides information based on the data collected from connected properties. It allows for monitoring indoor temperatures, viewing how much the service controls to optimise heating, observing energy use, and energy savings.

Introduction

My Pages is a specific user portal for the NODA Building product, which helps property owners save energy and costs, achieve a more consistent indoor temperature, and enable the monitoring of the property's heat usage and indoor comfort over time.

The service is a cloud-based software that relies on data collection from the property and its substation to NODA's server. NODA uses the data to control heating more efficiently and to visualise the property's heat usage. Energy savings from the service are achieved by adjusting the heating of the radiator circuit inside the building to the actual needs of the property instead of just the outdoor temperature (the latter is the typical way to control heating in properties).

The system learns how the property uses energy by using room sensors for indoor temperature. By setting an indoor target temperature for the property, the service can control the heating towards this, thus avoiding unnecessary heating and maintaining a steady indoor temperature. The system also relies on weather forecasts to adjust the energy use to what is needed.

The user portal provides information based on the data collected from connected properties. It allows for monitoring indoor temperatures, viewing how much the service controls to optimise heating, observing energy use, and energy savings.

Introduction

Introduction

API

Infrastructure introduction

The infrastructure required to run the NODA system is reasonably complex. It is no surprise that a complex system carries an inherently higher risk of exposure to attacks.

At the forefront of every design decision, NODA strives to mitigate the risk of such attacks.

Reliable, secure and encrypted communication channels are vital to achieving a secure environment.

But it's not the only item of importance.

Who has access, when they have access and why they have access are just as essential to prevent intrusion.

Devices in the field must never expose any ports to the internet. Instead, NODA solves the two-way communication by establishing a secure communication channel over MQTT to a managed service where each device has its own access rules.

Suppose the private certificate on a device, for whatever reason, is highjacked. Then, the device can easily be black-listed, and the certificate revoked to prevent further access.

Infrastructure introduction

The infrastructure required to run the NODA system is reasonably complex. It is no surprise that a complex system carries an inherently higher risk of exposure to attacks.

At the forefront of every design decision, NODA strives to mitigate the risk of such attacks.

Reliable, secure and encrypted communication channels are vital to achieving a secure environment.

But it's not the only item of importance.

Who has access, when they have access and why they have access are just as essential to prevent intrusion.

Devices in the field must never expose any ports to the internet. Instead, NODA solves the two-way communication by establishing a secure communication channel over MQTT to a managed service where each device has its own access rules.

Suppose the private certificate on a device, for whatever reason, is highjacked. Then, the device can easily be black-listed, and the certificate revoked to prevent further access.

Design in broad brush strokes

NODA aims to control energy equipment situated in the field. These devices are often located in the basement of buildings or inside smaller sheds in the vicinity.

By gathering vital data from these devices and crunching the numbers with machine learning algorithms, NODA achieves energy savings on a building level and also solves far more complex city-wide problems.

NODA provides equipment at the customer's site to communicate with many existing energy controllers. Often without the need to replace any existing hardware.

graph LR
    subgraph CustomerSite["Customer Site"]
    	Energy_Controller["Energy Controller"]
        NODA_Equipment["NODA Equipment"]
    end

    subgraph AnotherCustomerSite["Customer Site"]
        SCADASystem["SCADA System"]
        APIIntegration["NODA API Integration"]
    end

    subgraph NODA["NODA"]
        subgraph Kubernetes["Kubernetes"]
    		APIServer["APIServer"]
        	Computations["Machine Learning"]
        	MQTTBackend["MQTT Backend"]
        	UI["User Interface"]
    	end

		MQTTBridge["MQTT Bridge"]
    	Database[("Database")]
    end

    Person["User 🧑"]

	APIIntegration --> SCADASystem
	APIIntegration -->|"Internet 🔒"| APIServer

    NODA_Equipment --> Energy_Controller
    NODA_Equipment -->|"Internet 🔒"| MQTTBridge
    APIServer --> Database
    MQTTBridge <-->|"🔒"| MQTTBackend
    MQTTBackend --> Database
    Computations --> Database
    UI --> Database
    Person --> UI

On the server-side, NODA manages all of the ingress data, performs computations and solves optimization problems using both multi agent systems and machine learning.

Finally, the resulting control action signal is sent back to the controller over the internet.

Most of the data from these computations are then organized and presented so that it's practical and helps the customer in their daily work.

Development Process at NODA

At NODA, our roots in Software Engineering and Computer Science shape our approach to software development. As a company committed to excellence, we ensure that our development processes reflect our dedication to quality, collaboration, and innovation.

Collaboration and Transparency

We believe that transparency and collaboration are key to successful project delivery. Our development process is designed to be open and inclusive, ensuring that all stakeholders are kept informed and involved. By employing an iterative, community-like process, we maintain flexibility and adaptability, ensuring that our solutions meet the evolving landscape.

Embracing Free and Open Source Software

As a small company, we deeply appreciate the contributions of the Free Software and Open Source communities. While it is not always possible for us to contribute back directly, we encourage our employees to participate in and contribute to open source projects whenever possible. This not only helps the community but also enhances our team's skills and knowledge.

Development Process

Planning

Planning is the first step required for any development process. Given that most projects are based on a delivery date, we start with that and work backwards to ensure a comprehensive plan. This involves establishing:

• Maintenance Period: Determining the duration for which the software will be maintained post-deployment.

• Project Deadline: Setting the final delivery date for the project.

• Testing Period: Allocating time for comprehensive testing to ensure the solution meets all requirements and quality standards.

• Development Period: Scheduling the necessary time for the actual development work, including coding and initial testing.

• Requirement Analysis Period: Defining the time needed for gathering, analyzing, and finalizing project requirements.

• Resource Allocation: Identifying and assigning the necessary resources for both the development and maintenance phases.

For projects or solutions with ongoing development and evolving requirements, each addition of new features should be treated as a separate small or large project depending on the scope.

While this process may resemble the traditional Waterfall methodology, and in many respects it functions similarly, it is designed to ensure thoroughness before progressing to the next stage. This approach minimizes the risk of investing time and resources in work that may later prove unnecessary. However, unlike the rigid structure of Waterfall, our process is flexible and encourages back-stepping when necessary. This adaptability allows us to revisit and revise previous stages to ensure we are always working on the right tasks and meeting the project’s evolving needs.

Call it what you will; we simply don't put a label on it.

Requirement Analysis

At the outset, we focus on thoroughly understanding the needs and defining the project requirements. This involves:

• Conducting requirement elicitation meetings with key personnel and stakeholders.

• Performing research to determine the feasibility of the requirements.

• Developing a project-specific Requirement Specification.

• Engaging in negotiations to determine which requirements can be addressed and which cannot, often due to time constraints and resource availability.

The initial phase of requirement analysis concludes once all relevant parties have agreed on the specifications and the interpretation of each requirement.

Prototyping

Certain requirements may involve concepts or dependencies that fall outside the immediate expertise of the development team. To accurately assess the feasibility of these requirements, prototyping becomes essential. Prototyping allows us to explore, experiment, and gain the necessary knowledge to make informed decisions.

For example:

• Integrating New Technologies: When a requirement involves using a new or unfamiliar technology, we create a prototype to test its compatibility and performance within our solution.

• Complex User Interfaces: For most user interface designs, we develop prototypes to validate usability, functionality, and user experience.

• System Interoperability: When the project requires integration with external systems or APIs, we prototype these connections to ensure smooth and reliable interactions.

• Performance Testing: Prototypes can be used to test the system's performance under various conditions, identifying potential bottlenecks and optimization opportunities.

Prototyping helps us mitigate risks, validate assumptions, and refine our approach before full-scale development begins, ensuring a more efficient and effective development process.

Design

Based on the requirements outlined in the Requirement Specification, we design the system architecture, user interfaces, and other key components with security as a primary focus.

During the design phase, new requirements or adjustments to existing requirements may arise. As a result, we must remain flexible and revisit previous steps in the process to accommodate these necessary changes, often requiring a new iteration of Requirement Analysis.

Throughout the design phase, we will often produce:

• System Architecture Diagrams: Detailed representations of the system's structure, including modules, data flow, and integration points.

• User Interface Mockups: Visual prototypes of the user interfaces to ensure alignment with user experience goals and client expectations.

• Database Schemas: Structured plans for data storage, ensuring efficient data management and retrieval.

• Security Models: Plans addressing security measures to protect data integrity and privacy.

• Technical Specifications: Documentation outlining the functionalities and interactions of each component, providing a clear blueprint for the development team.

Certainly! Here is the adjusted and extended version of the Testing chapter:

Testing

The concept of testing should precede the implementation phase. Even though there is nothing to test before code is written, sufficient information should be available for developers to prioritize testing from the outset. This approach shifts the traditional mindset of implementing first and testing later to a more proactive strategy of considering how to test functionality before implementing it, ensuring that the implementation is inherently testable.

Testing is conducted throughout the entire development phase and extends beyond it until we are satisfied with the quality assurance.

Artifacts from testing often include:

• Unit Tests: Comprehensive tests for individual components, with a coverage target where less than 90% is unacceptable. These tests ensure each part of the codebase functions as intended.

• Integration Tests: Tests to ensure that different modules and components work together seamlessly.

• System Tests: End-to-end testing of the complete system to verify that it meets all specified requirements.

• Performance Tests: Assessments to ensure the system performs well under various conditions and loads.

Development

During the development phase, code is written with testability and security as primary core pillars. Features are developed in separate branches, and once a feature is completed and passes all its tests, a merge request is created. A reviewer then examines the merge request, and if adjustments are necessary, the developer must make the modifications before the updated merge request is reviewed again. Once accepted, the code is merged into the main codebase. Each change is tracked using a versioning system (Git), allowing any state of the source code to be investigated.

If developers encounter issues that require changes to the Design or necessitate negotiations about the Requirements, these issues should be promptly raised with the responsible parties for each phase to find a solution.

Freeze

Once all features, or a limited set of features due to time constraints, have been merged into the main branch, a code freeze is implemented. During a freeze, no new features may be merged, and the current state of the main branch is assigned a tag. Development can continue in other branches, but the main branch is off-limits to ensure stability and focus on finalizing the current release. This period is used for final testing, bug fixes, and preparation for the release.

Only critical bugs may result in a slight thaw, where patches are merged to address these issues. Otherwise, the freeze remains in effect, ensuring the integrity and stability of the main branch until the release is complete.

During this time, the deployment team is notified about the upcoming release so they can schedule and prepare for the necessary work to deploy the solution into production.

Staging

Before deploying the solution, it undergoes testing in a staging environment. During this phase, a period of soak testing is conducted, where the system is used as if it were in a production environment. The duration of the soak testing period varies depending on the specific circumstances, and it is up to the testing team to determine the appropriate length of time required on a case by case basis.

Deployment

Once the testing team approves the contribution, the tagged release is assigned an appropriate version number and a build is pushed to the registry in the production environment. During the scheduled maintenance window, the deployment team pushes the update to the production system and monitors it for any unusual behavior for the next few hours. If any issues arise, a rollback to the previous version is performed.

Maintenance

Once the deployment team completes their work, the maintenance period begins. During this phase, automated logging mechanisms are in place to detect and report any unexpected behavior. These systems continuously monitor the application, ensuring that any issues are promptly identified and addressed.

Additionally, regular updates and patches are applied to maintain the system’s security and performance.

Software Lifecycle

We follow a structured process to ensure smooth software deployment. This process guides us through code commits, testing, deployment, and potential rollback, ensuring reliability and consistency throughout.

graph TD;
	ReportIssue[Report Issue]

    Start([Start]) --> A[Planning]
    A --> B[Requirement Analysis]
    B --> C[Prototyping]
    C --> D[Design]
    D --> E[Development]
    E --> F{Run Tests}
    F -->|Pass| G[Code Freeze]
    G --> Staging[Staging]
    Staging --> I[Tag Release]
    Staging -->|Major Issue|ReportIssue
    I --> J[Manual Building\nof Container]
    J --> K{Deploy to\nProduction}
    K -->|Success| L([Success])
    K -->|Fail| M[Revert to Previous\nVersion]
    M --> ReportIssue --> E
    F -->|Fail|E
    F -->|Major Issue|D
    D -->|Major Issue|B

Security of the infrastructure

%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '60px' }}}%%
graph TD
    Vest["🔒 🦺 🔑"]

Accounts

• Never give personnel more access than strictly necessary to do their work.

• Whenever possible, use automatic termination of accounts after a specific date or period.

Installation site

• One should install hardware such as Modbus Gateway behind at least a locked door.

• One must report missing hardware and its certificates revoked ASAP.

• Equipment must be password protected with a unique random password.

• Equipment must connect over an encrypted channel.

• Equipment must never expose itself on the public internet.

• Equipment must continuously be updated with security patches.

Office

• Employees at NODA are required to use Bitwarden for password management.

• TOTP is enforced whenever possible. For the most important objects, U2F security keys (from Yubico) are used.

• Employees' workstations/laptops are full-disk encrypted.

• Employees' workstations/laptops must be updated with new security patches at a regular interval.

• WiFi passwords to the office network are never shared with visitors or friends.

Servers

• Software that exposes an interface to another system must always require authentication, even if the system exposes an interface in a "secure" environment.

• Access to the server system is only allowed through an SSH bastion using certificate authentication. Only the DevOps team has access to this gateway.

• One must never expose the Kubernetes API to the internet outside a maintenance window. During these windows, only a handful of selected IP addresses are allowed to communicate with the API endpoint.

• Machines, Container and Software packages must be tracked for updated of security patches.

Code

• Code in repositories is continuously scanned for new security vulnerabilities.

• Whenever an issue is found, the code is patched, verified and deployed within the next available maintenance window.

• Employees are only given access to a project they are working on.

• Code is written with security in mind.

  • As few dependencies on external systems as possible.

  • Known libraries shall ONLY ever manage cryptography. Never implement a crypto-solution by yourself.

  • Having test cases for most of the code is key to having a stable code base.

Transparency

Infrastructure

• The NODA "Cloud" is hosted on AWS (Amazon Web Services) in the eu-north-1 region.

• NODA uses DigitalOcean and Vultr for development and testing.

• NODA uses Google Workspace.

• NODA relies on FOSS (Free and Open Source) projects as part of the platform.

• The platform is written in house, and is of our own design.

Work environment

• NODA allows its employees to work from home.

• Employees use Linux, FreeBSD, Windows and macOS in their workstations/laptops.

Software

• NODA relies on several Open Source projects (to mention a few);

  • GNU/Linux
  • Kubernetes
  • Docker
  • PostgreSQL
  • Python
  • Go(lang)
  • PHP
  • Tengo
  • Scikit-Learn

• The software for the Modbus Gateway Addon is written using Arduino.

Open Source software licenses

NODA uses FOSS software with the following licenses;

• Apache License, Version 2.0
• BSD License 2, BSD License 3
• Eclipse Public License version 2.0
• GPLv2
• GPLv3
• LGPLv3
• MIT License
• Mozilla Public License 2.0 (MPL 2.0)
• Python License, Version 2
• PHP License, version 3.01
• Zope Public License 2.1

3rd-party solutions

• The operating system in the Teltonika router is based on a Teltonika modified version of OpenWRT.

Examples

Modbus Gateway Installation

A NODA Modbus Gateway can connect to any Modbus TCP or RTU capable energy controller. The NODA Modbus Gateway then reads and writes values to the energy controller using the Modbus protocol.

Installation complexity varies depending on the installation scenario;

• Freely programmable controller: Configurable Modbus layout and programmable logic.
• Application-specific controller: Static Modbus layout with only parameterise logic.

A freely programmable controller has to be configured to expose the required values. An application-specific controller seldom has the option to change the Modbus layout. Nor is it often possible to handle a failsafe mode directly in the controller using software logic.

An application-specific controller may contain this feature if the specific feature was part of the requirements when the controller was designed.

To solve this problem, NODA has developed the NODA Modbus Gateway Addon. A device that sits between the energy controller and the NODA Modbus Gateway and provides the missing logic required to handle situations when a connection to the internet fails for several hours or days.

graph TD
    subgraph clusterAWSIoT["AWS IoT"]
        IoT_Server["IoT Server"]
    end

    subgraph clusterSiteA["Customer Site"]
        Modbus_Gateway["Modbus Gateway"]
        Modbus_Gateway_Addon["Modbus Gateway Addon\n(optional)"]
        Energy_Controller["Energy Controller"]
    end

    Modbus_Gateway -->| | Modbus_Gateway_Addon
    Modbus_Gateway_Addon -->| | Energy_Controller
    Modbus_Gateway -->|"🔒"| IoT_Server

The NODA Modbus Gateway connect to the secure endpoint on AWS IoT. Data is then forwarded to the NODA system and handled by various processes. The system crunches the numbers and sends control signals back the controller via AWS IoT and the NODA Modbus Gateway.

Finally, a customer connects to the EnergyView (or My Pages) system to browse the data at their heart's content.

graph LR
    subgraph clusterNodaPrivate["Noda Private"]
        DBMS[("DBMS")]
        Mosquitto["Mosquitto"]
    end

    subgraph clusterNodaPublic["Noda Public"]
        EnergyView["EnergyView"]
        Mosquitto["Mosquitto"]
    end

    subgraph clusterAWSIoT["AWS IoT"]
        IoT_Server["IoT Server"]
    end

    subgraph clusterSiteA["Customer Site"]
        Modbus_Gateway["Modbus Gateway"]
    end

    Mosquitto -->| | DBMS
    EnergyView -->| | DBMS
    IoT_Server -->|"🔒"| Mosquitto
    Modbus_Gateway -->|"🔒"| IoT_Server

    Customer["💻 Customer"]
    Customer -->|"🔒"| EnergyView

Indoor Sensors Installation

There are several ways to get indoor sensor data into the NODA system.

The most common way is for equipment in the field to send data to NODA. This can be either via Wireless M-Bus gateways or via MQTT or HTTP from a gateway connected to a LoRa network.

These devices are often provisioned once and usually work for several years without intervention.

graph LR
    subgraph clusterNodaPrivate["Noda Private"]
        DBMS[("DBMS")]
    end

    subgraph clusterNodaPublic["Noda Public"]
        EnergyView["EnergyView"] -->| | DBMS
        W_MBus["W-MBus"] -->| | DBMS
    end

    subgraph clusterSite["Customer Site"]
        Indoor_Sensors["🌡️ Indoor Sensors"]
        Indoor_Sensors -->|"🔒"| W_MBus
    end

    Customer["💻 Customer"]
    Customer -->|"🔒"| EnergyView

Typical logging intervals are between 5 and 15 minutes, depending on expected lifespan, technology and so forth. Once the data has landed in the NODA system it can be viewed by customers using either EnergyView or My Pages.

3rd Party Integration Installation

While not very common, NODA allows for customer specific intergrations. This is often solved by using the NODA EnergyView API or the NODA Self-host API.

graph LR
    subgraph clusterNodaPrivate["Noda Private"]
        DBMS[("DBMS")]
    end

    subgraph clusterNodaPublic["Noda Public"]
        EnergyView["EnergyView"] -->| | DBMS
    end

    subgraph clusterSiteC["Customer Site"]
        Third_Party_Solution["3rd party solution"] -->|"🔒"| EnergyView
    end

    Customer["💻 Customer"]
    Customer -->|"🔒"| EnergyView

IEC Installation

NOTICE: This solution reaches end of life (EOL) on the 31st of December 2022.

The NODA IEC is a solution built in-house by NODA. It sits between an outdoor sensor (RTD) and the energy controller. The IEC measures the resistance of the outdoor sensors, converts it to a temperature, applies an offset (or not) and converts the new temperature back to a resistance value for the controller.

This solution has both benefits and drawbacks. Using this method, one can not control specific circuits in a building unless there is one controller for each circuit. In addition, everything affected by the outdoor temperature will be affected by an offset.

However, it's a simple concept and works well if used in the right circumstances.

graph LR
    subgraph clusterNodaPrivate["Noda Private"]
        DBMS[("DBMS")]
    end

    subgraph clusterNodaPublic["Noda Public"]
        EnergyView["EnergyView"]
        IEC_Sync["IEC Sync"]
    end

    subgraph clusterSiteA["Customer Site"]
        IEC["IEC"]
    end

    EnergyView -->| | DBMS
    IEC_Sync -->| | DBMS
    IEC -->|"🔒"| IEC_Sync

    Customer["💻 Customer"]
    Customer -->|"🔒"| EnergyView

Since the IEC cannot query an energy controller for measured values, these are collected by installing surface-mounted 1-wire temperature sensors on the essential circuits.

Important usage and safety information

The following safety precautions must be observed during all phases of the operation, usage, service or repair of any NODA product.

Users of the product are advised to convey the following safety information to users and operating personnel and to incorporate these guidelines into all manuals supplied with the product. Failure to comply with these precautions violates safety standards of design, manufacture and intended use of the product.

NODA Intelligent Systems AB assumes no liability for customer’s failure to comply with these precautions.

The products are developed for indoor use only, unless clearly stated otherwize.

The installation of the product should be performed by a qualified electrician or another professional with the required knowledge. It is important to follow all safety information of this manual when installing the product.

Make sure to read this manual carefully and follow it step by step to ensure a secure usage and to get the most out of your product.

Mobile router introduction

Communication with equipment in the field can be solved using various solutions. Choosing one of these solutions always boils down to weighing functionality vs cost.

Using a customer's existing infrastructure to communicate with the internet is always a problem. Especially so, if the customer is unfamiliar with their own infrastructure.

As a result, NODA decided to go with a mobile router solution. A device which, on its own, connects to the internet via the 4G or 5G mobile network. Then, this mobile router connects to the energy controller (A regulator or similar device) via Modbus over either TCP or RTU.

All of this is secured by exchanging data over an encrypted MQTT connection.

NODA requires this level of interaction with the energy controller to get all required measurement values, along with the ability to modify control parameters. This way, the controller can go about its business doing what it's good at, controlling. Whilst being nudged in the right direction by the analytic processes provided by NODA.

Mobile router introduction

Communication with equipment in the field can be solved using various solutions. Choosing one of these solutions always boils down to weighing functionality vs cost.

Using a customer's existing infrastructure to communicate with the internet is always a problem. Especially so, if the customer is unfamiliar with their own infrastructure.

As a result, NODA decided to go with a mobile router solution. A device which, on its own, connects to the internet via the 4G or 5G mobile network. Then, this mobile router connects to the energy controller (A regulator or similar device) via Modbus over either TCP or RTU.

All of this is secured by exchanging data over an encrypted MQTT connection.

NODA requires this level of interaction with the energy controller to get all required measurement values, along with the ability to modify control parameters. This way, the controller can go about its business doing what it's good at, controlling. Whilst being nudged in the right direction by the analytic processes provided by NODA.

Hardware options

NODA relies on hardware from the manufacturer Teltonika.

The router we use and support are;

• RUT240
• RUT950
• RUT955

The RUT240 is primarily used as a Mobile router for wired ethernet devices, while the RUT950 and RUT955 series are mainly used as Modbus Gateway.

Remote management

An essential function of equipment deployed in the field is accessing these devices securely.

Devices such as routers always require software upgrades or maintenance to fix newly discovered security vulnerabilities.

Often this requires a VPN solution at the customer site. Or that each router connects as a client to a central management system using VPN.

The should be no situations where equipment is directly exposed to the internet. Such a solution is fraught with troubles down the line.

The NODA routers provided by Teltonika solve this problem by providing a secure connection using secured MQTT as a transport layer. The device connects to Teltonikas Remote Management System (RMS), where all devices are accessible and easily managed.

Introduction

NODA Modbus Gateway provides a reliable Modbus TCP master/slave solution where data transmits over a secure MQTT connection.

The Modbus Gateway acts as a Modbus TCP or RTU master/slave. It can communicate with any Modbus TCP slave connected via the LAN interface or act as a Modbus TCP slave. It can also communicate with any Modbus RTU slave connected via an RS-485.

Data is transmitted over the mobile network using a 4G or 5G modem internal to the gateway. The LAN interface or the RS-485 bus is not used to transfer outbound data to NODA. Only the WLAN connection via Wired Ethernet or Mobile Internet can access the internet.

For a list of limitations concerning the installation, see the details in Modbus support.

Introduction

NODA Modbus Gateway provides a reliable Modbus TCP master/slave solution where data transmits over a secure MQTT connection.

The Modbus Gateway acts as a Modbus TCP or RTU master/slave. It can communicate with any Modbus TCP slave connected via the LAN interface or act as a Modbus TCP slave. It can also communicate with any Modbus RTU slave connected via an RS-485.

Data is transmitted over the mobile network using a 4G or 5G modem internal to the gateway. The LAN interface or the RS-485 bus is not used to transfer outbound data to NODA. Only the WLAN connection via Wired Ethernet or Mobile Internet can access the internet.

For a list of limitations concerning the installation, see the details in Modbus support.

Compatibility requirements

For a list of known compatible devices, take a look at Manufacturer templates.

General requirements

A typical installation requires the ability to READ the following tags/values;

• Outdoor temperature
• Primary side flow (supply) temperature
• Primary side return temperature
• Primary side flow (supply) volume
• Primary side volume
• Primary side heat energy
• Primary side heat power
• Secondary side #1 flow temperature
• Secondary side #1 return temperature
• Current secondary side supply temperature

NOTE: If additional secondary side loops exist, they can also be included.

Along with the ability to WRITE the following tags/values;

• Secondary side supply temperature offset

or

• Forced secondary side supply temperature

Whichever depends on the limitations of the Modbus slave and the control system behind it.

NOTE: Specific use cases may require situation-specific solutions. In such a case, don't hesitate to get in touch with NODA for further support.

Components

The NODA Modbus Gateway consists of;

• Teltonika Mobile Router
• Antennas
• Power Supply Unit
• SIM-card (may be omitted)
• Modbus Gateway Addon (required for certain energy controllers)

Teltonika Hardware options

There are two different hardware options available;

RUT950/RUT951

The RUT950 and RUT951 are 4G routers. They come with 3 LAN (Ethernet) ports and 1 WAN (Ethernet) port. This option is well suited for use with freely programmable energy controllers with support for Modbus TCP.

RUT955/RUT956

The RUT955 and RUT956 are 4G routers. They come with 3 LAN (Ethernet) ports and 1 WAN (Ethernet) port; they also have 1 RS-485 port and 1 RS-232 port, along with a few generic I/O ports. This option is well suited for use with freely programmable energy controllers with support for Modbus TCP or Modbus RTU.

Introduction

The NODA Modbus Gateway Addon acts as a tiny external brain-aid for application-specific energy controllers.

Whenever a controller cannot handle the logic required to return to zero from an affected state, this solution is needed to restore the default state on the controller.

For example, if an offset of the supply temperature on the secondary side is 6.5 degrees Celsius and the internet connection goes down. Then, the controller will happily continue with the same 6.5 degrees offset until internet connectivity is restored. For a worst-case scenario, this can take several days.

This addon's sole purpose is to add logic to the energy controller without putting it in the environment of an operating system that is frankly less stable than a microcontroller's.

Components

The hardware we choose, 10 I/O's Digital Module is made by the Spanish company; Boot and Work Corp S.L. (Industrial Shields).

The hardware is built around an ESP32 and supports the Arduino Development Environment.

In the future, we aim to support several off-the-shelf Arduino-compatible products from different manufacturers.

Communication

The NODA Modbus Gateway Addon can communicate with Modbus devices over either Modbus TCP (Ethernet) or Modbus RTU (RS-485).

The solution uses the same protocol over MQTT as the NODA Modbus Gateway.

Modbus TCP

Communication with any Modbus TCP compatible Modbus Slave is possible over any port.

See the Setup section for more details about configuring the Modbus TCP support.

Modbus RTU

The communication protocol does not support specifying an RS-485 target. Instead, only IP targets are supported.

To get around this limitation, the NODA Modbus Gateway Addon assigns special meaning to the IPv4 loopback addresses. The loopback address of 127.1.1.1 is used as a way to forward a request to the RS-485 interface. The TCP port (typically 502) is silently ignored in such a request.

See the Setup section for more details about how to configure the RS-485 support.

Setup of Modbus Gateway Addon

Once powered on, the Addon will either request an IP address via DHCP or use the static IP configured via the user-interface.

When connected to a NODA Modbus Gateway, the Addon device will be assigned the IP 192.168.1.100.

Access the user-interface by entering the following in a web-browser; http://192.168.1.100.

It's is highly recommended to access this page in "incognito" or "private window" to avoid issues with password caching.

Login

The username is admin.

The password is unique for each device and can be requested from NODA.

Configuration

The following parameters can be changed.

Network

• MAC address: The MAC address can be changed here if required.
• Static IP: Assigning a static IP will disable DHCP. An empty field will active DHCP.
• Static DNS: Required if static IP is used.
• Static subnet: Required if static IP is used. On the form 255.255.255.255.

RS485 (for Modbus RTU)

• Baudrate: The speed over the RS-485 network. All devices must use the same speed.
• Mode: e.g. 8N1 or 7E1 etc.

MQTT

• ClientID: Identifier used when connecting to an MQTT broker.
• Host: The IP of the MQTT broker.
• Port: The TCP port of the MQTT broker.
• Username: Optional username used to connect to the MQTT broker.
• Password: Optional password used to connect to the MQTT broker.

Failover

• Communication timeout: The number of seconds without any data over MQTT, after which the device switches to failover state.
• On communication error: A list of instruction to execute when switching to a failover state. These instructions are used to clear any offset and return the energy controller to a clean-state.

Password

• WebUI Password: Used to change the password of the Web-UI.

Modbus support

Since Modbus was designed in the late 1970s to communicate to programmable logic controllers, the number of data types is limited to those understood by PLCs at the time. Therefore, large binary objects are not supported.

No standard way exists for a master device to find the description of a data object, for example, to determine whether a register value represents a temperature between 25 and 98 degrees Celsius.

Therefore the mapping and structure of the data have to be established for successful interoperability, as a client may store values not only in a single register but in several adjacent holding registers.

Limitations in the protocol support

As of this writing, the software used by NODA to achive communication with energy control equipment via Modbus over MQTT, is limited to the support implemented by Teltonika in their equipment.

This limits the available commands to send over Modbus to only Write Single Holding Register (6), Write Multiple Holding Registers (16) and Read Holding Registers (3). There is thus currently no support for reading and writing to coils and reading discrete inputs.

Single holding register data types

• 8 Bit Unsigned Integer (uint8)
• 8 Bit Signed Integer (int8)
• 16 Bit Unsigned Integer (uint16)
• 16 Bit Signed Integer (int16)
• 16 Bit Float (float16)

Multi (2) holding registers data types

• 32 Bit Unsigned Integer (uint32)
• 32 Bit Signed Integer (int32)
• 32 Bit Float (float32)

Both Word and Byte order can be Little- or Big Endian. But the order has to be consistent throughout.

NOTE: While NODA Modbus Gateway supports the above data types, your specific target slave device might not be able to handle them. Please refer to the manual for the slave device for details.

RS-485 limitations

The RS-485 driver can drive a maximum of 32 receivers, provided that the receiver input impedance is 12 k$\Omega$. If receiver impedances are higher, the maximum number of receivers in the network increases. Any combination of receiver types can be connected, provided their parallel impedance does not exceed $Rload > 375 \Omega$.

Solution for complete protocol support

To get around the current limitations in the Teltonika router, NODA implemented a separate solution with the capability of acting as an alternative to the Teltonika software in their router. This solution still requires Teltonika router to access the internet in a secure way. For more details about this solution take a look at the Modbus Gateway Addon

Recommendations

Depending on the usage scenario, limitations or flexibilities in the Modbus TCP slave, the data mapping will vary. Therefore, the following mapping is only the prefered mapping by NODA. As such, it can be changed in agreement with NODA to match the specific situation.

Modbus mapping for a typical building

Word Order: Big Endian
Byte Order: Little Endian

* Depends on specific circumstances

The structure outlined in the table can repeat if the Modbus TCP slave interfaces with several regulators and or control points.

NOTE: If additional secondary side circuits exist, they should be included.

NOTE: Holding register numbers are intentionally not outlined as they likely will vary from one Modbus TCP slave to another.

Installation preparation

The NODA Modbus Gateway comes prepared with all necessary certificates to connect to the NODA MQTT network securely.

Modbus TCP

For access to the Modbus TCP slave(s) or acting as a Modbus TCP slave itself. The NODA Modbus Gateway will need either a static or dynamic (DHCP) IP assigned to it in the LAN.

Don't hesitate to contact the network administrator as this information is only known to, and can be handled by, the network administrator. Once an IP number is assigned to the NODA Modbus Gateway, either via static or dynamic assignment, these details should be communicated to NODA, as they are required for device setup on the LAN.

NOTE: If the network administrator requests a MAC address. This address is labelled as LAN MAC on the underside of the NODA Modbus Gateway. If the label is missing or has been damaged, please get in touch with NODA for help.

Modbus RTU

To access Modbus RTU slave(s), the NODA Modbus Gateway will need access to an RS-485 network. Details on how an RS-485 network works are out of scope for this document.

To access Modbus RTU slave(s), the RS-485 bus configuration is required.

Default values are highlighted in bold.

• Baud rate (300, 1200, 2400, 4800, 9600, 19200, 38400, 57600 or 115200)
• Parity bits (none, odd, even)
• Stop bits (1, 2)
• Flow Control: (None, Xon/Xoff)
• Slave id or range of slave ids: (1-247)

Installation

The supplied DIN rail mount is the recommended way to mount the NODA Modbus Gateway. This may be in any larger installation cabinet, smaller installation box or similar. If the equipment is safe from water damage and dust ingress, it can be mounted without a separate enclosure as a last resort.

• Estimation of time required for installation
• Mounting location
  • Inside a larger installation cabinett
  • Inside a separate plastic box / enclosure
  • Without a protective enclose
• Configuration of the NODA Modbus Gateway
• Power supply
• Ethernet
• RS-485
  • 4-wire network
  • 2-wire network
• Wiring
  • Modbus Gateway without Addon
  • Modbus Gateway with Addon
• Setup

Estimation of time required for installation

The time required depends on a few factors;

• Familiarity with previous installations of NODA Modbus Gateway equipment.
• Familiarity with the control equipment.
• Knowledge of connecting Ethernet networks or RS485-bus networks.
• If the controller is freely programmable or an application-specific controller.

The tasks required for installation are (in general);

• Contact NODA and make a plan for installation a few days ahead of time
• Get to the installation location
• Find the energy controller
• Ensure that one can manage the controller over Modbus TCP / RTU
• Locate a suitable mounting location for the NODA Modbus Gateway
• Mount the equipment
• Wire the controller and NODA Modbus Gateway equipment together
• Configure the controller (often only required for freely programmable controllers)
• Validate the installation with NODA deployment staff

A skilled technician can perform these tasks in less than four hours without taking into account time for getting to the location, establishing a work environment and clean-up.

Mounting location

The NODA Modbus Gateway connects to the NODA MQTT network via the mobile network (4G / 5G). Therefore, install the device in a location where wireless transmission is allowed and the appliance can acquire a wireless signal.

Inside a larger installation cabinett

This option is one of the most well-suited installation locations. The equipment is safe from the environment, and if the cabinet is locked also secured from unauthorized access. Remember that the cabinet may work as a signal shield against the mobile network, resulting in a very low or no signal for the NODA Modbus Gateway. In this situation, your only option is to exchange the included antennas for antennas with an extension cord.

Inside a separate plastic box / enclosure

Another suitable choice is to use a larger box with a DIN rail to mount the NODA Modbus Gateway and the power supply. This box can be placed upwards to 50 meters from the controller if one can find no suitable location in the vicinity.

Without a protective enclose

As a last resort, one can mount the NODA Modbus Gateway directly on any suitable surface as long as the risk of water or dust ingress is low.

Configuration of the NODA Modbus Gateway

Configuration of the NODA Modbus Gateway is done remotely by NODA deployment staff. Depending on the installation scenario and the prep work done.

This configuration can often be done ahead of the shipment of the equipment. If any equipment configuration is required in the field, then once the equipment is connected to the internet, it can be accessed by the NODA deployment staff.

Power supply

The NODA Modbus Gateway is powered by the supplied power supply or any 9-30V industrial power supply.

Ethernet

When acting as a Modbus master, the NODA Modbus Gateway will connect to the network (LAN) via a switch from the ethernet port marked LAN1. However, suppose the slave device is not already on a LAN. In that case, one can directly connect the device to the NODA Modbus Gateway on the ethernet port marked LAN1 or the next available LAN port if used in conjunction with a NODA Modbus Gateway Addon.

When acting as a Modbus slave, the NODA Modbus Gateway will provide a Modbus TCP interface with a defined Holding Register scope on the LAN1 port. The default port number for this is 502.

RS-485

Wire the NODA Modbus Gateway to the network by using the following pinout.

4-wire network

If the NODA Modbus Gateway is wired to a 4-wire network (separate request and reply buses), then wire the D_P pin and the D_N pin to the request bus and wire the R_P pin and the R_N pin to the reply bus.

2-wire network

If the NODA Modbus Gateway is wired to a 2-wire network (single request and reply bus), bridge the pin D_P to the R_P pin and the D_N pin to the R_N pin before connecting to the bus.

Wiring

Modbus Gateway without Addon

Installation without the NODA Modbus Gateway Addon only works if the energy controller can be programmed (freely programmable controller). If the controller is an application-specific controller, then the NODA Modbus Gateway Addon is required.

Connect the energy controller to the NODA Modbus Gateway using either; Ethernet or RS-485.

Modbus Gateway with Addon

If you are using a NODA Modbus Gateway Addon, then see details in Addon > Wiring.

Setup

Once installed and up and running. The NODA Modbus Gateway should be visible in Teltonika RMS. Suppose you don't have access to this tool. Then contact NODA support for acknowledgement.

When a connection to Teltonika RMS has been established, you can continue with the Setup step.

Setup

Further network setup (see the Preparation section) is done remotely by NODA personnel via a remote management system once the NODA Modbus Gateway has successfully connected to the internet via the mobile network.

NOTE: For highly skilled technicians, if required, NODA can provide temporary access to the web interface of the NODA Modbus Gateway.

Slave device setup

The Modbus TCP/RTU slave device should be configured by a professional with the required knowledge of the specific equipment. Specifics on this task is out of scope for this document. Please refer to the technical manual for the particular slave device.

TCP Gateway setup

Ethernet Network

The default IP on the LAN interface for the NODA Modbus Gateway is 192.168.1.1. However, one can change the IP if the network requires it.

Ethernet Firewall

Suppose an optional and appropriately recommended firewall limits the communication between NODA Modbus Gateway and the Modbus TCP slave(s). In that case, the recommended solution is to port-forward the traffic over the firewall from the NODA Modbus Gateway and on to the target Modbus TCP slave on the LAN.

Such configuration is out of the scope of this document and should generally be handled by a network administrator.

RTU Gateway setup

If the settings for the RS-485 port matches the RS-485 network, there should be no further setup necessary.

Server-side request setup

Data exchange setup between the NODA Modbus Gateway and the Modbus TCP slave(s) is done via the online tool EnergyView, using administrative credentials. This step is out of scope for this document.

For help and more information on this, don't hesitate to get in touch with NODA.

Templates

NOTE: This list contains verified controllers. New controllers are added continuously and most Modbus controllers are compatible.

Please contact NODA if have any questions or if your controller is not listed.

Each energy controller is often unique in its particular, unique way. Still, manufacturers often retain the same patterns and layout throughout their offerings.

This section provides a verified list of required Modbus values in a controller to allow full functionality of the NODA Modbus Gateway.

Each template contains a details explanation of how to handle that specific controller.

Supported manufacturers

Select a manufacturer to get a list of supported controllers and mapping.

• Abelko
• Bastec
• Danfoss
• Regin

Controllers from other manufacturers

Any controller capable of acting as a Modbus TCP or Modbus RTU slave/server can likely be handled by our Modbus Gateway.

Any integration outside of what we support requires work and knowledge of the controller. Something we can't manage for all available controllers on the market.

Please read the Compatibility section for more details on determining the possibility of support for your specific controller.

If you have additional questions, please contact NODA.

Abelko controllers

https://abelko.se/produkter/

More documentation coming soon. :)

Bastec controllers

Integration with a Bastec controller is over Modbus TCP (Ethernet). The preferred setup is to use a NODA Modbus Gateway as a Modbus Slave.

The Bastec controller is freely programmable.

Table of Content

• BAS2 XE16
• BAS2 XL13
• Modbus values
  • Scaling of integer values
  • Outdoor sensors
  • Supply and Return temperature
  • Calculated supply temperature
  • M-Bus Heat Meter
  • Offset of supply temperature
  • Watchdog / Failover
• Installation
• Setup
  • Roles
  • Recommended mapping for integration

BAS2 XE16

BAS2 XL13

Modbus values

Using the following layout, at most four (4) heating systems are supported.

Scaling of integer values

Scale (factor) is used to transform a decimal value into an integer value by multiplying it with that value. This is often required as simple computers are often bad at handling decimal values. As a result, we lose the decimal part when converting a decimal value to an integer value.

For example, if the value 3.1415 is to be managed in such a way, it can be scaled using 10, 100, 1000 or even 10000. Giving us the integer values; 31, 314, 3141 or 31415.

These integer values can then be transmitted to a more intelligent computer, where they are divided by the same factor to produce a decimal value once more.

Remember that the scale factor decides how many decimals are retained once converted back to a decimal value.

Outdoor sensors

The following values are available as Holding Registers.

Supply and Return temperature

The following values are available as Holding Registers.

Calculated supply temperature

The following values are available as Holding Registers.

M-Bus Heat Meter

The following values are available as Holding Registers.

All M-Bus values are 32-bit wide and takes up two Holding Registers. They are organized in order as High Word and then Low Word.

Offset of supply temperature

The following values are available as Holding Registers.

Watchdog / Failover

The following values are available as Holding Registers.

There is only one (1) watchdog counter, and that is for the first HS. All related logic should use the same counter as a way to determine that any offset done to the system is a frozen value.

Suppose the counter hasn't changed in 30 minutes. The controller should reset the "Offset of supply temperature" to zero (0). The controller should automatically re-activate the offset when the counter starts working again.

Installation

Installation requires a NODA Modbus Gateway.

Installation steps can be found under Modbus Gateway > Installation.

Setup

Before performing this step. Please ensure that you have finished all necessary steps in Modbus Gateway > Installation.

To complete the following steps, administrative access to NODA EnergyView is required. If you do not have administrative access to NODA EnergyView then setup has to be carried out by NODA support personell.

For each heating system controlled, NODA requires the following;

• Outdoor sensors (C)
• Supply and return temperature (C)
• Offset of supply temperature (K)
• M-Bus Heat Meter values
  • Supply and return temperature (C)
  • Energy (MWh)
  • Power (kW)
  • Volume (m3)
  • Flow (l/h)
• Calculated supply temperature (C)

M-Bus Heat Meter values may be omitted if these values are transferred to NODA's system in some other way than via the Bastec controller.

Roles

• The NODA Modbus Gateway acts as a Modbus Slave.
• The Bastec controller acts as a Modbus Master.

Recommended mapping for integration

The following mapping is a recommended example of a single heating system installation. However, extend the mapping accordingly if there is more than one heating system.

Holding registers

Holding registers

Danfoss controllers

Integration with a Danfoss controller is over Modbus TCP (Ethernet) or Modbus RTU (RS-485). The NODA Modbus Gateway as a Modbus Client/Master and the Danfoss controller acts as a Server/Slave.

The Danfoss controller is application-specific and requires separate Application Key for different scenarios.

Danfoss ECL210/296/310 Applications

A2XX applications

• A207
• A214
• A217
• A230
• A231
• A232
• A237
• A247
• A260
• A266
• A267
• A275

A3XX applications

• A302
• A314
• A315
• A318
• A319
• A331
• A332
• A333
• A347
• A361
• A362
• A367
• A368
• A375
• A376
• A377
• A390

P3XX applications

• P302
• P314
• P318
• P330
• P348

P5XX applications

• P501

Danfoss ECL210/296/310 Application A207

This application contains 1 variant(s)

Table of Content

• Application A207.1
  • Example A

Application A207.1

Example A

Danfoss ECL210/296/310 Application A214

This application contains 6 variant(s)

Table of Content

• Application A214.1
  • Example A
  • Example B
  • Example C
  • Example D
  • Example E
• Application A214.2
  • Example A
  • Example B
• Application A214.3
  • Example A
  • Example B
• Application A214.4
  • Example A
  • Example B
• Application A214.5
  • Example A
  • Example B
  • Example C
• Application A214.6
  • Example A
  • Example B

Application A214.1

Example A

Example B

Example C

Example D

Example E

Application A214.2

Example A

Example B

Application A214.3

Example A

Example B

Application A214.4

Example A

Example B

Application A214.5

Example A

Example B

Example C

Application A214.6

Example A

Example B

Danfoss ECL210/296/310 Application A217

This application contains 3 variant(s)

Table of Content

• Application A217.1
  • Example A
  • Example B
  • Example C
  • Example D
  • Example E
• Application A217.2
  • Example A
  • Example B
• Application A217.3
  • Example A
  • Example B
  • Example C
  • Example D

Application A217.1

Example A

Example B

Example C

Example D

Example E

Application A217.2

Example A

Example B

Application A217.3

Example A

Example B

Example C

Example D

Danfoss ECL210/296/310 Application A230

This application contains 5 variant(s)

Table of Content

• Application A230.1
  • Example A
  • Example B
  • Example C
  • Example D
• Application A230.2
  • Example A
  • Example B
  • Example C
  • Example D
• Application A230.3
  • Example A
  • Example B
  • Example C
  • Example D
• Application A230.4
  • Example A
  • Example B
  • Example C
  • Example D
• Application A230.5
  • Example A

Application A230.1

Example A

Example B

Example C

Example D

Application A230.2

Example A

Example B

Example C

Example D

Application A230.3

Example A

Example B

Example C

Example D

Application A230.4

Example A

Example B

Example C

Example D

Application A230.5

Example A

Danfoss ECL210/296/310 Application A231

This application contains 2 variant(s)

Table of Content

• Application A231.1
  • Example A
• Application A231.2
  • Example A

Application A231.1

Example A

Application A231.2

Example A

Danfoss ECL210/296/310 Application A232

This application contains 1 variant(s)

Table of Content

• Application A232.1
  • Example A
  • Example B
  • Example C
  • Example D
  • Example E
  • Example F

Application A232.1

Example A

Example B

Example C

Example D

Example E

Example F

Danfoss ECL210/296/310 Application A237

This application contains 2 variant(s)

Table of Content

• Application A237.1
  • Example A
  • Example B
  • Example C
  • Example D
• Application A237.2
  • Example A
  • Example B

Application A237.1

Example A

Example B

Example C

Example D

Application A237.2

Example A

Example B

Danfoss ECL210/296/310 Application A247

This application contains 3 variant(s)

Table of Content

• Application A247.1
  • Example A
  • Example B
  • Example C
• Application A247.2
  • Example A
  • Example B
  • Example C
• Application A247.3
  • Example A
  • Example B
  • Example C

Application A247.1

Example A

Example B

Example C

Application A247.2

Example A

Example B

Example C

Application A247.3

Example A

Example B

Example C

Danfoss ECL210/296/310 Application A260

This application contains 1 variant(s)

Table of Content

• Application A260.1
  • Example A
  • Example B
  • Example C
  • Example D
  • Example E
  • Example F

Application A260.1

Example A

Example B

Example C

Example D

Example E

Example F

Danfoss ECL210/296/310 Application A266

This application contains 3 variant(s)

Table of Content

• Application A266.1
  • Example A
  • Example B
  • Example C
• Application A266.2
  • Example A
• Application A266.9
  • Example A

Application A266.1

Example A

Example B

Example C

Application A266.2

Example A

Application A266.9

Example A

Danfoss ECL210/296/310 Application A267

This application contains 1 variant(s)

Table of Content

• Application A267.1
  • Example A
  • Example B
  • Example C
  • Example D
  • Example E

Application A267.1

Example A

Example B

Example C

Example D

Example E

Danfoss ECL210/296/310 Application A275

This application contains 3 variant(s)

Table of Content

• Application A275.1
  • Example A
  • Example B
• Application A275.2
  • Example A
  • Example B
  • Example C
  • Example D
• Application A275.3
  • Example A
  • Example B
  • Example C
  • Example D
  • Example E
  • Example F
  • Example G

Application A275.1

Example A

Example B

Application A275.2

Example A

Example B

Example C

Example D

Application A275.3

Example A

Example B

Example C

Example D

Example E

Example F

Example G

Danfoss ECL210/296/310 Application A302

This application contains 6 variant(s)

Table of Content

• Application A302.1
  • Example A
• Application A302.2
  • Example A
• Application A302.3
  • Example A
• Application A302.4
  • Example A
• Application A302.5
  • Example A
• Application A302.6
  • Example A

Application A302.1

Example A

Application A302.2

Example A

Application A302.3

Example A

Application A302.4

Example A

Application A302.5

Example A

Application A302.6

Example A

Danfoss ECL210/296/310 Application A314

This application contains 8 variant(s)

Table of Content

• Application A314.1
  • Example A
  • Example B
• Application A314.2
  • Example A
  • Example B
• Application A314.3
  • Example A
  • Example B
• Application A314.4
  • Example A
  • Example B
  • Example C
  • Example D
  • Example E
• Application A314.5
  • Example A
  • Example B
  • Example C
  • Example D
  • Example E
• Application A314.6
  • Example A
  • Example B
  • Example C
• Application A314.7
  • Example A
  • Example B
  • Example C
• Application A314.9
  • Example A
  • Example B

Application A314.1

Example A

Example B

Application A314.2

Example A

Example B

Application A314.3

Example A

Example B

Application A314.4

Example A

Example B

Example C

Example D

Example E

Application A314.5

Example A

Example B

Example C

Example D

Example E

Application A314.6

Example A

Example B

Example C

Application A314.7

Example A

Example B

Example C

Application A314.9

Example A

Example B

Danfoss ECL210/296/310 Application A315

This application contains 8 variant(s)

Table of Content

• Application A315.1
  • Example A
  • Example B
• Application A315.3
  • Example A
  • Example B
  • Example C
  • Example D
  • Example E
  • Example F
• Application A315.4
  • Example A
  • Example B
  • Example C
  • Example D
  • Example E
  • Example F
• Application A315.5
  • Example A
  • Example B
  • Example C
  • Example D
  • Example E
  • Example F
• Application A315.6
  • Example A
  • Example B
  • Example C
• Application A315.10
  • Example A
  • Example B
  • Example C
• Application A315.11
  • Example A
• Application A315.12
  • Example A

Application A315.1

Example A

Example B

Application A315.3

Example A

Example B

Example C

Example D

Example E

Example F

Application A315.4

Example A

Example B

Example C

Example D

Example E

Example F

Application A315.5

Example A

Example B

Example C

Example D

Example E

Example F

Application A315.6

Example A

Example B

Example C

Application A315.10

Example A

Example B

Example C

Application A315.11

Example A

Application A315.12

Example A

Danfoss ECL210/296/310 Application A318

This application contains 1 variant(s)

Table of Content

• Application A318.1
  • Example A
  • Example B
  • Example C

Application A318.1

Example A

Example B

Example C

Danfoss ECL210/296/310 Application A319

This application contains 2 variant(s)

Table of Content

• Application A319.1
  • Example A
• Application A319.2
  • Example A

Application A319.1

Example A

Application A319.2

Example A

Danfoss ECL210/296/310 Application A331

This application contains 2 variant(s)

Table of Content

• Application A331.1
  • Example A
• Application A331.2
  • Example A

Application A331.1

Example A

Application A331.2

Example A

Danfoss ECL210/296/310 Application A332

This application contains 4 variant(s)

Table of Content

• Application A332.1
  • Example A
• Application A332.2
  • Example A
  • Example B
  • Example C
  • Example D
• Application A332.3
  • Example A
  • Example B
• Application A332.4
  • Example A

Application A332.1

Example A

Application A332.2

Example A

Example B

Example C

Example D

Application A332.3

Example A

Example B

Application A332.4

Example A

Danfoss ECL210/296/310 Application A333

This application contains 3 variant(s)

Table of Content

• Application A333.1
  • Example A
  • Example B
  • Example C
  • Example D
  • Example E
• Application A333.2
  • Example A
• Application A333.3
  • Example A

Application A333.1

Example A

Example B

Example C

Example D

Example E

Application A333.2

Example A

Application A333.3

Example A

Danfoss ECL210/296/310 Application A347

This application contains 3 variant(s)

Table of Content

• Application A347.1
  • Example A
  • Example B
  • Example C
  • Example D
• Application A347.2
  • Example A
  • Example B
  • Example C
  • Example D
• Application A347.3
  • Example A

Application A347.1

Example A

Example B

Example C

Example D

Application A347.2

Example A

Example B

Example C

Example D

Application A347.3

Example A

Danfoss ECL210/296/310 Application A361

This application contains 2 variant(s)

Table of Content

• Application A361.1
  • Example A
• Application A361.2
  • Example A

Application A361.1

Example A

Application A361.2

Example A

Danfoss ECL210/296/310 Application A362

This application contains 1 variant(s)

Table of Content

• Application A362.1
  • Example A
  • Example B
  • Example C

Application A362.1

Example A

Example B

Example C

Danfoss ECL210/296/310 Application A367

This application contains 2 variant(s)

Table of Content

• Application A367.1
  • Example A
  • Example B
  • Example C
  • Example D
  • Example E
• Application A367.2
  • Example A
  • Example B
  • Example C

Application A367.1

Example A

Example B

Example C

Example D

Example E

Application A367.2

Example A

Example B

Example C

Danfoss ECL210/296/310 Application A368

This application contains 6 variant(s)

Table of Content

• Application A368.1
  • Example A
• Application A368.2
  • Example A
• Application A368.3
  • Example A
• Application A368.4
  • Example A
• Application A368.5
  • Example A
• Application A368.6
  • Example A

Application A368.1

Example A

Application A368.2

Example A

Application A368.3

Example A

Application A368.4

Example A

Application A368.5

Example A

Application A368.6

Example A

Danfoss ECL210/296/310 Application A375

This application contains 5 variant(s)

Table of Content

• Application A375.1
  • Example A
  • Example B
  • Example C
  • Example D
  • Example E
  • Example F
  • Example G
  • Example H
  • Example I
• Application A375.2
  • Example A
• Application A375.3
  • Example A
• Application A375.4
  • Example A
• Application A375.5
  • Example A

Application A375.1

Example A

Example B

Example C

Example D

Example E

Example F

Example G

Example H

Example I

Application A375.2

Example A

Application A375.3

Example A

Application A375.4

Example A

Application A375.5

Example A

Danfoss ECL210/296/310 Application A376

This application contains 6 variant(s)

Table of Content

• Application A376.1
  • Example A
  • Example B
• Application A376.2
  • Example A
  • Example B
• Application A376.3
  • Example A
  • Example B
• Application A376.4
  • Example A
• Application A376.9
  • Example A
  • Example B
• Application A376.10
  • Example A

Application A376.1

Example A

Example B

Application A376.2

Example A

Example B

Application A376.3

Example A

Example B

Application A376.4

Example A

Application A376.9

Example A

Example B

Application A376.10

Example A

Danfoss ECL210/296/310 Application A377

This application contains 3 variant(s)

Table of Content

• Application A377.1
  • Example A
  • Example B
  • Example C
• Application A377.2
  • Example A
  • Example B
  • Example C
• Application A377.3
  • Example A

Application A377.1

Example A

Example B

Example C

Application A377.2

Example A

Example B

Example C

Application A377.3

Example A

Danfoss ECL210/296/310 Application A390

This application contains 6 variant(s)

Table of Content

• Application A390.1
  • Example A
  • Example B
  • Example C
• Application A390.2
  • Example A
• Application A390.3
  • Example A
  • Example B
• Application A390.11
  • Example A
  • Example B
  • Example C
  • Example D
  • Example E
• Application A390.12
  • Example A
  • Example B
• Application A390.13
  • Example A
  • Example B

Application A390.1

Example A

Example B

Example C

Application A390.2

Example A

Application A390.3

Example A

Example B

Application A390.11

Example A

Example B

Example C

Example D

Example E

Application A390.12

Example A

Example B

Application A390.13

Example A

Example B

Danfoss ECL210/296/310 Application P302

This application contains 1 variant(s)

Table of Content

• Application P302.1
  • Example A

Application P302.1

Example A

Danfoss ECL210/296/310 Application P314

This application contains 7 variant(s)

Table of Content

• Application P314.4
  • Example A
  • Example B
• Application P314.5
  • Example A
  • Example B
• Application P314.6
  • Example A
  • Example B
• Application P314.7
  • Example A
  • Example B
• Application P314.8
  • Example A
  • Example B
• Application P314.10
  • Example A
  • Example B
• Application P314.11
  • Example A
  • Example B

Application P314.4

Example A

Example B

Application P314.5

Example A

Example B

Application P314.6

Example A

Example B

Application P314.7

Example A

Example B

Application P314.8

Example A

Example B

Application P314.10

Example A

Example B

Application P314.11

Example A

Example B

Danfoss ECL210/296/310 Application P318

This application contains 6 variant(s)

Table of Content

• Application P318.1
  • Example A
  • Example B
  • Example C
  • Example D
  • Example E
  • Example F
• Application P318.2
  • Example A
  • Example B
  • Example C
• Application P318.5
  • Example A
  • Example B
  • Example C
  • Example D
• Application P318.10
  • Example A
  • Example B
  • Example C
• Application P318.11
  • Example A
  • Example B
  • Example C
  • Example D
• Application P318.21
  • Example A
  • Example B

Application P318.1

Example A

Example B

Example C

Example D

Example E

Example F

Application P318.2

Example A

Example B

Example C

Application P318.5

Example A

Example B

Example C

Example D

Application P318.10

Example A

Example B

Example C

Application P318.11

Example A

Example B

Example C

Example D

Application P318.21

Example A

Example B

Danfoss ECL210/296/310 Application P330

This application contains 15 variant(s)

Table of Content

• Application P330.1
  • Example A
• Application P330.2
  • Example A
• Application P330.3
  • Example A
• Application P330.4
  • Example A
• Application P330.5
  • Example A
• Application P330.6
  • Example A
• Application P330.7
  • Example A
• Application P330.8
  • Example A
• Application P330.9
  • Example A
• Application P330.10
  • Example A
• Application P330.11
  • Example A
• Application P330.12
  • Example A
• Application P330.13
  • Example A
• Application P330.14
  • Example A
• Application P330.15
  • Example A

Application P330.1

Example A

Application P330.2

Example A

Application P330.3

Example A

Application P330.4

Example A

Application P330.5

Example A

Application P330.6

Example A

Application P330.7

Example A

Application P330.8

Example A

Application P330.9

Example A

Application P330.10

Example A

Application P330.11

Example A

Application P330.12

Example A

Application P330.13

Example A

Application P330.14

Example A

Application P330.15

Example A

Danfoss ECL210/296/310 Application P348

This application contains 3 variant(s)

Table of Content

• Application P348.1
  • Example A
  • Example B
  • Example C
  • Example D
• Application P348.2
  • Example A
  • Example B
  • Example C
  • Example D
• Application P348.3
  • Example -
  • Example A

Application P348.1

Example A

Example B

Example C

Example D

Application P348.2

Example A

Example B

Example C

Example D

Application P348.3

Example -

Example A

Danfoss ECL210/296/310 Application P501

This application contains 3 variant(s)

Table of Content

• Application P501.1
  • Example A
• Application P501.11
  • Example A
• Application P501.12
  • Example A
  • Example B

Application P501.1

Example A

Application P501.11

Example A

Application P501.12

Example A

Example B

Danfoss ECL 210/296/310

A controller supports three different ways of receiving external offset signals;

• SCADA outdoor temperature (C)
• SCADA heat offset (-10 to +10 K)
  • Up to four circuits are supported.
• Offset/adjustment of measurement for port S1 to S10.

Via SCADA outdoor temperature, the regulator's current outdoor temperature gets replaced with any value written.

Via SCADA heat offset, a range limited offset is applied to the four possible circuits, 1 to 4.

Adjustment of measurements on port S1 to S10 should be avoided as a way to perform external control.

Table of Content

• Hardware
  • Interfaces
• Applications
• Modbus
  • Supported functions
  • Sensors
    • Raw sensor values
    • Non-raw sensor values
  • Outdoor sensors
  • Supply and Return temperature
  • Offset of supply temperature
  • M-Bus Heat Meter
  • Calculated supply temperature
  • Watchdog / Failover
  • SCADA offset type
• Installation
• Setup
  • Roles
  • Wiring
    • Ethernet
    • RS-485
    • USB Serial
  • Recommended mapping for integration

Hardware

The ECL hardware platform supports up to ten (10) signal inputs. They range from S1 to S10. Depending on the Application selected for the circumstances of the installation of the controller, these signal inputs will have different purposes, such as temperature or pressure sensors for various points in the installation.

Interfaces

The ECL 296 and 310 supports Modbus TCP and Modbus RTU. The ECL 210 only supports Modbus RTU.

Applications

An ECL controller supports many different scenarios. The hardware is the same; the only thing that changes is the software. Danfoss supplies these Applications as separate components of an installation. With prices vary depending on the functionality.

For details about the various Applications, see the Danfoss store. If the link doesn't work, then use your common sense and a search engine.

Some typical applications are;

• A230: Heating control with wind compensation. Cooling control.
• A260: 2 x heating control
• A266: Heating and DHW control
• A302: Zone control

Modbus

For an extended explaination of the Modbus protocol, see the educational material.

Noteable sections include;

• Scaling of values

Supported functions

The controller only supports Holding Registers. The functions supported are;

• 03 (0x03) Read Holding Registers
• 04 (0x04) Read Input Registers
• 06 (0x06) Write Single Register

Sensors

The controller exposes all sensor values (S1-S10) either as raw or non-raw values in two different segments.

The following values are available as Holding Registers.

Raw sensor values

Non-raw sensor values

Outdoor sensors

It seems that S1 is always the outdoor temperature sensor for all Applications. However, this is not guaranteed. Always check the Application specification.

The example below is taken from A230.1.

The following values are available as Holding Registers.

|

Supply and Return temperature

The example below is taken from A230.1.

The following values are available as Holding Registers.

Offset of supply temperature

In the Danfoss ECL Comfort 210/296/310 documentation. This is described as SCADA Heat Offset.

The example below is taken from A230.1.

It seems that these registers are always the same for all Applications.

Allowed range is -100 (65436) and +100 (100), i.e. -10 Kelvin and +10 Kelvin.

The following values are available as Holding Registers.

M-Bus Heat Meter

Only available on ECL Comfort 296/310.

It seems that these registers are always the same for all Applications.

32-bit values are integer values.

The following values are available as Holding Registers.

Calculated supply temperature

The following values are available as Holding Registers.

Watchdog / Failover

ECL 210/296/310 controllers use an internal watchdog for all SCADA values.

There is a poorly documented SCADA (before 2022) variable hidden at Modbus Number (PNU) 10399. Firmware version 1.54 and above contains support for a SCADA time-out register and newer documentation contains information regarding that functionality as well.

This value represents the number of minutes (Time-To-Live) after which any SCADA offset returns to zero (0).

This should be changed to 30 (minutes).

SCADA offset type

ECL 210/296/310 controllers use a control register to define the type of SCADA offset.

The value is a bitmask. Which, in order of least significant bit, represents the offset type for Modbus Number 10400 up to 10404.

The bit value 0 represents relative offset. While 1 represents absolut offset.

For example, an 8bit value of 0b00010010 (18) activetes absolute offset for HS1 and HS4. While setting outdoortemp, HS2, HS3 remains as relative offset.

This should (in most cases) be set to 0 (all relative offset).

Installation

A NODA Modbus Gateway is required for installation.

Installation steps can be found under Modbus Gateway > Installation.

Setup

Before performing this step. Please ensure that you have finished all necessary steps in Modbus Gateway > Installation.

To complete the following steps, administrative access to NODA EnergyView is required. If you do not have administrative access to NODA EnergyView then setup has to be carried out by NODA support personell.

For each heating system controlled, NODA requires the following;

• Outdoor sensors (C)
• Supply and return temperature (C)
• Offset of supply temperature (K)
• M-Bus Heat Meter values
  • Supply and return temperature (C)
  • Energy (MWh)
  • Power (kW)
  • Volume (m3)
  • Flow (l/h)
• Calculated supply temperature (C)

M-Bus Heat Meter values may be omitted if these values are transferred to NODA's system in some other way than via the Danfoss controller.

Roles

• The NODA Modbus Gateway acts as a Modbus Client/Master and as a secure transport of data from and to the internet.
• The Danfoss controller acts as a Modbus Server/Slave.

Wiring

Ethernet

The NODA Modbus Gateway can be connected to the ECL controller either via the LAN1 port on the NODA Modbus Gateway or via the WAN port to an existing LAN network. For more details on this see NODA Modbus Gateway: Ethernet.

RS-485

An ECL 210/296/310 can be connected via Modbus RTU over RS-485. This is done via the screw terminals 34 (B), 35 (A), 36 (S. Gnd). The bus must be terminated using 120 Ohm resistors.

All devices in the network must use the same communication settings. Multiple communication settings are not allowed;

• 9600, 19200 or 38400 (default) baud rate
• 1 start bit
• 8 data bits
• even parity
• 1 stop bit

(a total of 11 bits).

• RS-485 (A) should be wired to D_N and R_N.
• RS-485 (B) should be wired to D_P and R_P.
• RS-485 (GND) should be wired to GND.

For more details on this see NODA Modbus Gateway: RS-485.

USB Serial

The USB interface on the ECL Comfort 210/296/310 exposes an Modbus RTU interface.

As an alternative to the RS-485 interface, this interface can be used together with an RUT955/956 and the "USB Serial" support.

Recommended mapping for integration

The following mapping is a recommended example of a single heating system installation using the A230.1 Application.

For other Applications you are required to extend this example as needed.

Holding registers

Holding registers

Regin controllers

Most Regin controllers use the same variable list (4.3) Making each variation of a product almost the same from a variable perspective.

Depending on the controller, there is support for up to 4 different heating systems. However, a typical NODA Modbus Gateway only manages one (1) Heating System.

A NODA Modbus Gateway Addon is required to be able to read Discrete Inputs from the Regin controller. Along with the support for watchdog/failover functionality.

Both Modbus TCP and Modbus RTU are supported with the NODA Modbus Gateway Addon

Table of Content

• Getting the version information
• Exigo Ardo
• Exigo Vido
• Corrigo Ardo

Getting the version information

First, ensure that you are on the start page to get the version information from a Regin controller.

Then Press the Right button (arrow right) three (3) times to reach the Program details. Here you will find a version string in the format X.Y-x-y, with a date string. At the bottom of the screen, you will see a serial number.

Press the Right button (arrow right) twice (2) to reach another version information screen. Here you will find something along the line of EXOreal C and a version string in the format X.Y-x-y.

Exigo Ardo

Exigo Vido

Corrigo Ardo

Modbus Mapping for Regin Exigo Ardo & Exigo Vido

Table of Content

• Modbus
  • Outdoor sensors
  • Supply and Return temperature
  • Calculated supply temperature
  • Offset of supply temperature
  • M-Bus Heat Meter
  • Watchdog / Failover
• Installation
• Setup
  • Roles
  • Recommended mapping for integration
  • Wiring

Modbus

For an extended explaination of the Modbus protocol, see the educational material.

Noteable sections include;

• Scaling of values

Outdoor sensors

The following values are available as Input Registers.

Supply and Return temperature

The following values are available as Input Registers.

Calculated supply temperature

The following values are available as Input Registers.

Offset of supply temperature

The following values are available as Holding Registers.

Allowed range is -100 (65436) and +100 (100), i.e. -10 Celsius and +10 Celsius.

M-Bus Heat Meter

The following values are available as Input Registers.

Watchdog / Failover

These controllers do not support watchdog/failover logic of any of the "Parallel transfer of setpoint-curve" options. To solve this, NODA recommends using the NODA Modbus Gateway Addon.

Installation

A NODA Modbus Gateway Addon is required for installation.

Installation steps can be found under Modbus Gateway > Installation.

Setup

Before performing this step. Please ensure that you have finished all necessary steps in Modbus Gateway > Installation.

To complete the following steps, administrative access to NODA EnergyView is required. If you do not have administrative access to NODA EnergyView then setup has to be carried out by NODA support personell.

For each heating system controlled, NODA requires the following;

• Outdoor sensors (°C)
• Supply and return temperature (°C)
• Offset of supply temperature (K)
• M-Bus Heat Meter values
  • Supply and return temperature (°C)
  • Energy (MWh)
  • Power (kW)
  • Volume (m3)
  • Flow (l/h)
• Calculated supply temperature (°C)

M-Bus Heat Meter values may be omitted if these values are transferred to NODA's system in some other way than via the Regin controller.

Roles

• The NODA Modbus Gateway Addon acts as a Modbus Master.
• The Regin controller acts as a Modbus Slave.
• The NODA Modbus Gateway acts as a secure transport for the transmission of MQTT messages, from and to the Modbus Gateway Addon.

Recommended mapping for integration

The following mapping is a recommended example of a single heating system installation. However, extend the mapping accordingly if there is more than one heating system.

Discrete inputs

Holding registers

Wiring

If you are connecting the NODA Modbus Gateway to the Regin controller using Ethernet, then you must communicate the IP number of the controller to NODA.

On the controller, navigate to Configuration > Communication > TCP/IP to find the current IP of the controller.

On the other hand, if you are connecting the NODA Modbus Gateway to the Regin controller using RS485. Then the following is required;

• Modbus Number
• Baudrate
• Stop bits (1 or 2)
• Parity (none, odd or even)

The prefered settings here are; 19200 baud, one stop bit and no parity.

Modbus Mapping for Regin Corrigo Ardo

Table of Content

• Modbus
  • Limitations
  • Outdoor sensors
  • Supply and Return temperature
  • Calculated supply temperature
  • Offset of supply temperature
  • M-Bus District Heat Meter
  • Watchdog / Failover
• Installation
• Setup
  • Roles
  • Recommended mapping for integration
  • Wiring

Modbus

A Regin Corrigo Ardo supports real (R), integer (I), index (X) and logical (L) values.

Real signal have a scale factor 10, except for the time setting signals which have scale factor 100, and the air flow signals which have scale factor 1.

Integer, Index and Logic always have scale factor 1.

For a more general explaination of the Modbus protocol, see the educational material.

Limitations

• A maximum of 47 registers can be read in one message.

Outdoor sensors

The following values are available as Input Registers.

Supply and Return temperature

The following values are available as Input Registers.

Calculated supply temperature

The following values are available as Input Registers.

Offset of supply temperature

The following values are available as Holding Registers.

Verify:
Allowed range is -100 (65436) and +100 (100), i.e. -10 Celsius and +10 Celsius.

M-Bus District Heat Meter

The following values are available as Input Registers.

Watchdog / Failover

These controllers do not support watchdog/failover logic of any of the "Parallel transfer of setpoint-curve" options. To solve this, NODA recommends using the NODA Modbus Gateway Addon.

Installation

A NODA Modbus Gateway Addon is required for installation.

Installation steps can be found under Modbus Gateway > Installation.

Setup

Before performing this step. Please ensure that you have finished all necessary steps in Modbus Gateway > Installation.

To complete the following steps, administrative access to NODA EnergyView is required. If you do not have administrative access to NODA EnergyView then setup has to be carried out by NODA support personell.

For each heating system controlled, NODA requires the following;

• Outdoor sensors (C)
• Supply and return temperature (C)
• Offset of supply temperature (K)
• M-Bus Heat Meter values
  • Supply and return temperature (C)
  • Energy (MWh)
  • Power (kW)
  • Volume (m3)
  • Flow (l/h)
• Calculated supply temperature (C)

M-Bus Heat Meter values may be omitted if these values are transferred to NODA's system in some other way than via the Regin controller.

Roles

• The NODA Modbus Gateway Addon acts as a Modbus Master.
• The Regin controller acts as a Modbus Slave.
• The NODA Modbus Gateway acts as a secure transport for the transmission of MQTT messages, from and to the Modbus Gateway Addon.

Recommended mapping for integration

The following mapping is a recommended example of a single heating system installation. However, extend the mapping accordingly if there is more than one heating system.

Input Registers

Holding registers

Wiring

If you are connecting the NODA Modbus Gateway to the Regin controller using Ethernet, then you must communicate the IP number of the controller to NODA.

On the controller, navigate to Configuration > Communication > TCP/IP to find the current IP of the controller.

On the other hand, if you are connecting the NODA Modbus Gateway to the Regin controller using RS485. Then the following is required;

• Modbus Number
• Baudrate
• Stop bits (1 or 2)
• Parity (none, odd or even)

The prefered settings here are; 19200 baud, one stop bit and no parity.

Communication

The NODA Modbus Gateway communicates with the NODA MQTT network over a 4G mobile network.

Communication is secured using standard client-based certificates where only a holder of a valid certificate can connect to the network.

Each client is further locked down using ACL (access control lists), declaring which topics (communication channels) a specific client is allowed to subscribe and publish.

A certificate can easily be black-listed (by NODA) if, for any reason, the certificate is compromised.

All communication over this MQTT channel is encrypted.

Communication protocol

The NODA Modbus Gateway relies on software written by the manufacturer (Teltonika) of the Gateway hardware. Teltonika developed a simple protocol for transferring Modbus requests over MQTT. The protocol works by;

A controller publishes a message in the format below on a request topic. The software interprets the message and performs a Modbus request based on instructions from the message. The software then replies on the response topic.

Request message

0 <COOKIE> <IP_TYPE> <IP> <PORT> <TIMEOUT> <SLAVE_ID> <MODBUS_FUNCTION> <REGISTER_NUMBER> <REGISTER_COUNT/VALUE> <DATA>

Explanation:

• 0: must be 0, which signifies a textual format (currently the only one implemented).

• Cookie: a 64-bit unsigned integer in range [0..2^64]). A cookie is used to distinguish which response belongs to which request. Each request and the corresponding response contain a matching cookie: a 64-bit unsigned integer.

• IP type: host IP address type. Possible values:

  • 0: IPv4 address;
  • 1: IPv6 address;
  • 2: hostname pointing to an IP address.

• IP: IP address of a Modbus TCP slave. IPv6 must be presented in full form (e.g., 2001:0db8:0000:0000:0000:8a2e:0370:7334).

• Port: port number of the Modbus TCP slave.

• Timeout: timeout for Modbus TCP connection, in seconds. Range [1..999].

• Slave ID: Modbus TCP slave ID. Range [1..255].

• Modbus function:

  • 1: read coils
  • 2: read discrete inputs
  • 3: read holding registers
  • 4: read input registers
  • 5: force/write single coil
  • 6: preset/write a single holding register
  • 15: force/write multiple coils
  • 16: preset/write to multiple holding registers

• Register number: number of the first register (in the range [1..65536]) from which the registers will be read/written.

• Register count/value: this value depends on the Modbus function:

  • 1, 2, 3, 4: coil/register count (in range [1..125]). Must not exceed the boundary (first register number + register count <= 65537)
  • 5: coil value (in range [0..1])
  • 6: register value (in range [0..65535])
  • 15: register count (in range [1..123])
  • 16: register count (in range [1..123]). Must not exceed the boundary (first register number + register count <= 65537)

• Data: this value only exists for Modbus functions 15 (coil) and 16 (register). A series of coil/register values separated with commas, without spaces (e.g., 0,1,1,0,0,1 or 1,2,3,654,21,789). There must be exactly as many values as specified in register count. Each coil value must be in the range of [0..1]. Each register value must be in the range of [0..65535].

Response message

A particular response message can take one of the following forms:

For functions 5, 6, 15 and 16

<COOKIE> OK

For function 1, 2, 3 and 4

<COOKIE> OK <VALUE> <VALUE> <VALUE>

Where are the values read.

For failures

<COOKIE> ERROR: <message>

Where is the error description.

Examples

Reading five coils

Request

0 16468394968118163995 0 10.0.0.126 5020 5 1 1 1 5

Response

16468394968118163995 OK 1 1 1 1 1

Reading three input registers

Request

0 9958479625634 0 10.0.0.126 5020 5 1 4 1 3

Response

9958479625634 OK 1234 5678 9101

Sending too few holding register values

Request

0 565842596387 0 10.0.0.126 5020 5 1 16 1 3 1234,5678

Response

565842596387 ERROR: INVALID REQUEST

Packages

Installing external packages on a Teltonika RUT9XX is quite cumbersome.

When talking about embedded systems in general, maintainers often reject package systems in preference of upgrading the entire system (firmware). The reason can be to save space or to be able to ensure compatibility.

Nonetheless, as a user or an advanced reseller of an embedded solution, developing and adding new software to a system is often required since the wanted functionality is usually missing. This lack of functionality is due to the simple fact that the manufacturer usually works with requirements which differ from other organisations. Therefore, unless you buy hundreds of thousands of devices, they see no benefit in introducing more work and complexity in their processes.

OpenWRT, the Linux distro the RUT9XX series uses as its OS, is somewhere between an embedded system and a server system. Developed as a "router OS", its intended target is of no question. Still, it maintains an extensive package system which allows for the installation of most server-related software. Components one seldom thinks of as part of a router. Then again, it is common for systems to have multiple roles these days. Whether or not this is a good thing is not to be debated today.

Compiling a piece of software and building an OpenWRT-compatible package is an adventure (rabbit hole) in itself. As such, we will not discuss it here, as our goal lies elsewhere.

Package format

OpenWRT uses the opkg package format, which derives from the now defunct ipkg package format. Yet still, the extension remains as .ipk.

These files are compressed tar archives with a fixed structure similar to, but not compatible with, Debian packages.

Adding a new package source on OpenWRT

Opkg packages use one or several repositories (feeds) as the remote storage location. You can find the declaration of these repositories in the folder /etc/opkg. Here you will find a couple of .conf files. Each file (often) points to a particular origin. In the RUT9XXX firmware, the available files are;

• customfeeds.conf
• distfeeds.conf
• teltonikafeeds.conf

The Teltonika-specific file points to a repository with Teltonika's packages for software such as MQTT, Modbus etc.

The Distfeeds file contains several repositories with OpenWRT packages. These files are not only for the RUT9XX but for all devices compatible with the same CPU architecture.

Last, there is the Customfeeds file. Here one can add references to other custom repositories. For example, to add the current NODA repository, add the following line to the file.

src/gz noda https://opkg.noda.se

Save it and run the following commands.

$ cd /tmp
$ wget https://opkg.noda.se/public.key
$ opkg-key add public.key $ opkg update

NOTE: If you get an error containing;

opkg_download: Failed to download https://downloads.openwrt.org/.../mips_24kc/vuci/Packages.gz

Then you can safely ignore this error. It is due to the removal of the vuci feed from OpenWRT mainline, something Teltonika still needs to patch in their firmware.

Installing NODA packages

The following packages are available in the NODA repository (feed).

• simple-modbus-server; a plain Modbus TCP server (slave) to act as an intermediary between two or more Modbus clients (masters). It supports multiple simultaneous connections, something lacking from the Modbus server available in the RUT9XX firmware since it can only handle one connection at a time.

To install a package; run the following command;

$ opkg install package-name

Simple Modbus Server

By default, this software runs on the same port as the Modbus server in the firmware and since two different software can't listen on the same TCP port. Therefore, you must disable the internal Modbus server before installing and deploying this software.

$ opkg install simple-modbus-server

The default configuration should suffice for most cases. If you need to change anything, you can find the configuration in;

$ cat /etc/config/modbus_server

config modbus 'modbus'
	option enabled '1'
	option port '502'
	option address '0.0.0.0'
	option coil '0:0'
	option discrete '0:0'
	option holding '0:9999'
	option input '0:0'
	option connections '32'

To enable the service to run at startup, execute the command;

$ /etc/init.d/modbus_server enable

To manually start the service, execute the command;

$ /etc/init.d/modbus_server start

Firmware upgrade

There is one major caveat with all of this, and that is a firmware upgrade. In stark contrast to desktop systems, an embedded system doesn't perform an upgrade of newer packages. Instead, it replaces its entire OS environment with a new one on every upgrade.

Such an upgrade will completely wipe all modifications from the system and will, in essence, restore the device to factory default. To avoid losing configuration, OpenWRT uses a separate storage system, UCI, to store all configuration files. When performing a firmware upgrade, one can choose to retain or wipe this store.

Still, this only pertains to configuration files. Packages are not part of the UCI system. As a result, the system must download and install packages after each firmware upgrade—something it doesn't do independently.

Teltonika solves this in their firmware by keeping track of installed packages in a temporary file which survives the upgrade and is then automatically installed once the router is online. However, this only works for packages in Teltonika's feed, not those from mainline OpenWRT or our custom feed.

There exists an attempt at solving this dilemma in OpenWRT, which is called opkg-extras, but it's not a maintained solution and doesn't work as-is. Why this is not part of the mainline OpenWRT firmware is a good question.

Examples

A typical Modbus TCP installation

A typical Modbus RTU installation

Questions and answers

Why does it say 'Teltonica RUTXXX' on the NODA Modbus Gateway?

NODA relies on hardware from many different manufacturers. For the NODA Modbus Gateway, we have decided on equipment from a Lithuanian company called Teltonika.

Why doesn't the NODA Modbus Gateway connect to the internet?

Please ensure that the status LED in the lower right corner of the front faceplate is green. If the signal strength indicator next to the status LED is low, please mount the device in a location with a better mobile network signal. If the status LED is flashing yellow or red, please refer to the Teltonika manual found at www.teltonika.lt or contact NODA for support.

Will the NODA Modbus Gateway work with my slave?

As long as the slave has support for Modbus TCP and Holding Registers is where the data is stored, then it should work.

However, there are situations when it is unwise for the NODA Modbus Gateway to write to the Modbus TCP slave continuously. For example, when writes will cause wear on an EEPROM flash. In such situations, data can still be read, but data can not (continuously) be written to the slave.

Introduction

NOTICE: This solution reaches end of life (EOL) on the 31st of December 2022.

This handbook contains instructions on how to install and configure the Intelligent Energy Controller (IEC).

IEC operation

The IEC sits between an outdoor temperature sensor and a regulating device (i.e. a controller).

Its main functions are:

• to provide an interface for an outdoor temperature sensor
• to emulate an actual temperature sensor
• to interface with 1-Wire temperature sensors
• to interface with an energy meter
• to communicate with the NODA cloud platform

As an outdoor temperature sensor interface, it supports a range of temperature sensors that can be connected. See section Input modes for details.

The outdoor temperature reading, i.e. the reference temperature, is sent to NODA's platform along with readings from 1-Wire temperature sensors and the energy meter.

NODA's system calculates the optimal change in temperature for the (heating/cooling) system, based on the outdoor temperature (reference), gathered data, system parameters and various operational targets. This calculated temperature is then transmitted back to the IEC.

As a temperature sensor emulator, the IEC then feeds a customised temperature value to the controller, i.e. the calculated temperature.

This change the controller's measured outdoor temperature, which in turn decreases or increases the heating/cooling of the building.

The data exchange between the IEC and NODA is once every 10 minutes.

\pagebreak

Mounted system overview

1. Cooling/Heating system Controller.
2. Outdoor temperature sensor.
3. Energy meter.
4. Intelligent Energy Controller (IEC).
5. 1-Wire temperature sensors.
6. Teltonica RUT 3G/4G router (optional if the infrastructure already exists and can be used).

End-of-life notification

Due to the EOL of several components required, NODA is forced to shelf this product as of the 31st of December 2022.

A direct replacement does not exist at this time. For an alternative solution, see Modbus Gateway

Introduction

NOTICE: This solution reaches end of life (EOL) on the 31st of December 2022.

This handbook contains instructions on how to install and configure the Intelligent Energy Controller (IEC).

IEC operation

The IEC sits between an outdoor temperature sensor and a regulating device (i.e. a controller).

Its main functions are:

• to provide an interface for an outdoor temperature sensor
• to emulate an actual temperature sensor
• to interface with 1-Wire temperature sensors
• to interface with an energy meter
• to communicate with the NODA cloud platform

As an outdoor temperature sensor interface, it supports a range of temperature sensors that can be connected. See section Input modes for details.

The outdoor temperature reading, i.e. the reference temperature, is sent to NODA's platform along with readings from 1-Wire temperature sensors and the energy meter.

NODA's system calculates the optimal change in temperature for the (heating/cooling) system, based on the outdoor temperature (reference), gathered data, system parameters and various operational targets. This calculated temperature is then transmitted back to the IEC.

As a temperature sensor emulator, the IEC then feeds a customised temperature value to the controller, i.e. the calculated temperature.

This change the controller's measured outdoor temperature, which in turn decreases or increases the heating/cooling of the building.

The data exchange between the IEC and NODA is once every 10 minutes.

\pagebreak

Mounted system overview

1. Cooling/Heating system Controller.
2. Outdoor temperature sensor.
3. Energy meter.
4. Intelligent Energy Controller (IEC).
5. 1-Wire temperature sensors.
6. Teltonica RUT 3G/4G router (optional if the infrastructure already exists and can be used).

Components

I/O board

Status LEDs on the I/O board

There are 6 separate LED:s to the left of the KOMM2 expansion port. They are marked (from right to left), D13, D14, D5, D6, D7 and D12.

ARM CPU board

1. Communication pins.
2. Micro SD card.
3. Power LED (green) and Status LED (red).
4. Ethernet port.

When the Power LED lights up, the CPU board has power. During start-up, the Status LED will briefly (for a few seconds) light up.

If the Status LED is continuously lit for more than 30 seconds, then an unknown fault has occurred.

The ethernet ports leftmost LED (green) lights up only if the board has detected a 100MBit/s link. A limited 10Mbit/s link does not light the LED. The rightmost (orange) LED blinks when there is network traffic over the port.

KOMM2 add-on board (optional)

1. 20-pin ribbon cable. Connects to P1 on the I/O board.
2. GPRS modem connector (optional).
3. M-Bus port.

PSU

Power adaptor, 100-240V AC 50/60Hz to 5V DC, 3A

• Max cable length: 1.5m
• Center Pin positive
• Inner barrel diameter; 2.1mm
• Outer barrel diameter; 5.5mm
• Barrel length; 12mm

Preparing for installation

It is highly advised to review this documentation before setting out to install the IEC on site. Some preparations are required for a technician to be able to perform the IEC installation and its configuration on site.

Compile a list of materials required for the installation. Including, but not limited to, the following:

• IEC hardware
• power supply
• GSM module and antenna
• 1-wire sensors
• Opto eye cable
• resistors (shunt)
• cabling and other materials

If the configuration of the IEC hardware is going to be performed on-site, then a laptop is required with the following:

• an up to date or LTS version of a major GNU/Linux distribution OS or
• Windows 10 or 11 OS
• a free USB port
• NODA Installation Utility v16 or newer
• USB drivers for the configuration cable TTL-232R-3V3
• the TTL-232R-3V3 configuration cable

Other recommended equipment:

• a multimeter
• a screwdriver set
• a permanent marker (blue)
• a permanent marker (red)

Installation and wiring

Input modes

The IEC supports two different input modes; High resolution with a narrow scope and Low resolution with a broad scope.

Switching between these two modes is done with a jumper on the I/O board. To move this jumper you first need to detach the ARM CPU board from the I/O board.

Search for a jumper in the middle of the I/O board marked P13. You can find it north (11'o clock) of the S1 / RC connector (P12).

With the jumper attached on P13, the board operates at high resolution with a narrow scope.

By removing the jumper, the board switches to low resolution with a broad scope.

This step is necessary to manage RTD sensors with a resistance (R) of more than 7.5 kOhm.

Place the jumper on a single header pin for safekeeping.

Failover relays

As a safeguard, the IEC has two relays which bridge the S1 port directly to the RC port in case of a fault.

Whenever the power is lost, or there is a failure in communication between the CPU board and the I/O board (for >= 30min), the I/O board automatically switches to this failover state.

In this case, the IEC decouples from the controller and the outdoor temperature sensor is then directly connected to the controller.

This failover can also be activated remotely by NODA.

Shunt resistor

When using a sensor with a resistance ($Rsensor$) of more than 43 kOhm, it is required to use an appropriately sized resistor ($Rshunt$) on P14 to scale down the resistance reported to the IEC ($Riec$).

The sensor is wired to the IEC after the failover relays and in parallel with the shunt resistor. As such, the resistance reported to the IEC can be calculated using the equation for calculating resistors in parallel:

$${1 \over Riec } = { 1 \over Rsensor } + { 1 \over Rshunt } $$

Solving for $Rshunt$, the equation becomes:

$$ Rshunt = { Rsensor * Riec \over Rsensor - Riec } $$

Use the above equation to calculate the value of the shunt resistor where required.

See details in Appendix B for more information and an example.

Supported passive sensors (RTD)

As long as an RTD sensor is within the measurements range of the I/O board and the resolution is adequate, the IEC can support any RTD sensor. However, sensors not listed in this table require implementation effort by NODA.

* Depends on the requirement to read low temperatures.

Supported active sensors (Volt)

Output modes

The IEC supports two different output modes;

• Voltage (standard for passive and active sensors)
• Transistor (only for passive sensors)

Voltage mode is the preferred mode and is used to simulate both passive and active sensors. If calibration towards the controller fails, you may need to switch to transistor mode.

Changing from a voltage to transistor mode

For changing the output mode, three jumpers need to move on the I/O board:

• P9 (marked as 2 in the figure)
• P10
• P11 (marked as 1 in the figure)

Mode	P9	P10, P11	Sensor type
Voltage			Passive and active
Transistor			Passive

Connecting to the outdoor sensor and controller

Before any wiring takes place, it is essential to know if the outdoor sensor is a passive or an active sensor.

If it is a passive sensor (RTD), then there are no special polarity requirements. However, if it's an active sensor, then the polarity must be respected. I.e. it must be wired from plus to plus and from minus (GND) to minus.

Outdoor sensor wiring

RTD Sensors

When connecting a passive outdoor temperature sensor to the S1 port of the IEC, no particular attention to the polarity is necessary.

Wiring from the IEC RC port to the controller requires the polarity of the I/O board to match the polarity of the Analog Input (AI) port of the controller.

If this is not marked, then use a multimeter while the outdoor temperature sensor is still attached to the controller and identify the polarity. If wired incorrectly; the controller, the IEC or both might take damage.

0-10V Sensors

When connecting an active outdoor temperature sensor to the IEC, make sure that the polarity matches the screw terminal. If wired incorrectly the IEC might take damage.

Wiring from the IEC RC port to the controller requires the polarity of the I/O board to match the polarity of the Analog Input (AI) port of the controller.

If this is not marked, then use a multimeter while the outdoor temperature sensor is still attached to the controller and identify the polarity. If wired incorrectly; the controller, the IEC or both might take damage.

0-10V Controller AO

This variant is a situation where the controller can supply an Analog Output (AO) with a 0-10V signal that corresponds to the outdoor temperature sensor measurement.

The outdoor temperature sensor connects directly to the controller, or via a bus and does not connect to the IEC.

In this case, the controller's AO port communicates the outdoor temperature as a 0-10V signal to the IEC's S1 port.

The IEC reads port S1, performs it's computations and writes a 0-10V signal (using the same temperature span as defined for the input sensor) on its RC port. This signal represents the new outdoor temperature.

Make sure to match the polarity on both sides. If wired incorrectly; the controller, the IEC or both might take damage.

This scenario often requires a one-time re-programming of the controller.

1-Wire Sensors

1-Wire is a device communications bus system designed by Dallas Semiconductor Corp. that provides low-speed data, signalling, and power over a single conductor.

The IEC supports up to 8 devices on a bus.

Temperature probes

The IEC is compatible with any DS18S20 or DS18B20 sensor. The ones supplied are wired to the screw terminal on the I/O board as follows:

Wiring

It is possible the generalise any bus into three different topologies:

• Linear topology: One main 1-Wire bus with insignificant (less than 3m) branches or stubs.
• Stubbed topology: One main 1-Wire bus with significant (more than 3m) branches or stubs.
• Star topology. The main 1-Wire bus splits into multiple branches.

It is highly recommended to keep to either a linear topology or a stubbed topology.

Network (Bus) length

The radius of a network is the wire distance from the IEC to the most remote device. This length S measures in meters. The network weight is the total amount of connected wire in the network, and also measures in meters.

For example, a star network configuration with three branches of 10m, 20m, and 30m would have a radius of 30m (i.e., the distance from 1-Wire master to the furthest slave) and weight of 60m (i.e., the total length of wire in the network, 10m + 20m + 30m).

The total weight of the network should not exceed 100 meters to prevent communication issues.

Cable recommendation

It is highly recommended to use a UTP cat 5 cable as this type of cable is readily available and has been proven reliable.

RS232 optical probe (IEC 62056-21)

The optical probe comes with 2m of cable. If additional length is required, then use a low capacitance (UTP cat 5) cable for a maximum combined length of 50 meters.

Wiring