1. Home
  2. Installer guides
  3. Integration of the Ampio system with Node-RED

Integration of the Ampio system with Node-RED

Integration via predefined nodes

In order to use the functionality of integration between the Ampio system and Node-RED, you have to launch the interface in your browser and provide the server IP address, as well as the admin’s password.

The Node-RED interface can be accessed on M-SERV via port 1880 by entering IP:1880 (e.g. 192.168.1.2:1880) into the browser.

A selection of Node-RED nodes is on the left side of the interface, where you can also find Ampio’s predefined nodes that will facilitate creating dependencies.

Each of the nodes has its own guideline in the Help tab.

In order to ensure that the node-red-contrib-ampio library is up to date, enter Menu → Manage palette and check whether an update is available, or not. If an update is performed, you must reset the server.

Code testing

Node-RED enables code debugging and displaying information (data) on the right side of the interface. Examples are provided below:

  • orange – Flow name
  • red – activation of the debug tab
  • blue – a node allowing for displaying information in debug
  • purple – data displayed in the debug option

Ampio IN node – obtaining information from inputs

Parameters:

  1. Server address – server’s IP address; if Node-RED is on the server, select localhost
  2. Target device – a device in the CAN network with a unique MAC address
  3. Value Type – used for the selection of the type of values that are received from the device. Select types from the following list:
    • Analog value
    • RGB color
    • Digital input
    • Digital output
    • Flag
    • Temperature
  4. I/O ID – the device’s input or output number
  5. Optionally, you may add a name for the node in the Name field.

If the Ampio IN node is configured correctly, you will see “connected” under the node.

Ampio OUT node – output control

Parameters:

  1. Server address – server’s IP address; if Node-RED is on the server, select localhost
  2. Target device – a device in the CAN network with a unique MAC address
  3. Cmd Type – used for the selection of the type of values that you want to control. Select types from the following list:
    • Standard – binary and analogue outputs
    • RAW CAN broadcast – RAW type is used for the control of raw data included in a separate CAN network documentation.
    • Digital input
    • Digital output
    • Flag
    • Temperature
  4. I/O ID –the device’s input or output number
  5. Optionally, you may add a name for the node in the Name field.

If the Ampio OUT node is configured correctly, you will see “connected” under the node.

Ampio LCD node – displaying information on M-DOT panels

Parameters :

  1. Server address – server’s IP address; if Node-RED is on the server, select localhost
  2. Target device – a device in the CAN network with a unique MAC address
  3. LCD font size – selection of a font between Standard (10×16), Big (20×32) and Icon (40×40). The last type is available only, if icons have been loaded onto the panel.
  4. LCD X position – beginning of a text line, X coordinate
  5. LCD Y position – beginning of a text line, Y coordinate
  6. LCD text color – hexadecimal text colour
  7. LCD bg color – hexadecimal background colour
  8. Name – optional name

The starting point is the top left corner of the screen. Its coordinates are LCD X=00 and LCD Y=00. Increasing the LCD X value will move the text towards the right side. Increasing the LCD Y value will lower the text, as shown below.

Ampio Event node – broadcasting events to or from the Ampio system

Parameters:

  1. Server address – server’s IP address; if Node-RED is on the server, select localhost
  2. Name – optional name

An example of usage

Here, we present an example of how to obtain the temperature from an Ampio module and display it, together with a description, on an M-DOT panel.  

In the Ampio IN node, select, from which module you would like to get the temperature values, set the value type and the sensor’s ID.

In the functional block, add a description using the Javascript language.

In the Ampio LCD node, select the M-DOT module and set up the position of text, the font size and colour, as well as the background colour.

Connect the nodes and click deploy.

The settings presented above will give you a white text ” TEMP: *temperature value*” in the middle of the screen on black background.

Integration via the MQTT broker

MQTT nodes

There is a possibility of integrating the Node-RED platform with the Ampio system without using predefined nodes. An MQTT broker will let you do that. With MQTT you can also track more events in the CAN network and control more advanced functions.

In order to do that, use nodes mqtt in and mqtt out.

If you are using Node-RED installed on the M-SERV module, enter localhost in server properties. In other cases, credentials for login are the same as the ones used for the Smart Home Manager application and the server is provided with the use of an IP address. Once you are done, click on Add, Done and Deploy.

MQTT topic

Communication with the MQTT broker is mostly two-directional (from and to). A topic that begins with ampio/from allows for checking the status of devices. A topic that begins with ampio/to is used to control devices.

Examples of ampio/to usage:

ampio/to/<mac>/cmd – run the command

ampio/to/<mac>/raw – raw data frame

ampio/to/can/dev/list – a list of devices in the CAN network

ampio/to/event – broadcast the event

A list of commands:

CommandTopicPayload
set a single outputampio/to/<mac>/o/<nr>/cmdon,off
0..255
RGBampio/to/<mac>/rgbw/<nr>/cmdoff
0..255,0..255,0..255 (on)
roller blindsampio/to/<mac>/o/<nr>/cmd0 – STOP
1 – DOWN
2 – UP
flagsampio/to/<mac>/f/<nr>/cmdon,off
0..255
MRT- temperatureampio/to/<mac>/rs/<nr>/cmd-99.9..155.0
MRT-temperature day/nightampio/to/<mac>/rsdn/<nr>/cmdtemperature_day, temperature_night (example: 19,20)
MRT- operating modeampio/to/<mac>/rm/<nr>/cmd0 – calendar ; 1 – MANUAL;
2 – MANUAL2; 3 – holidays ; 4 – blocked;

Examples of the ampio/from topic:

TypeTopicPayload stringPayload example
temperaturesampio/from/<mac>/state/t/<nr>from -99.9 to1000.0 (and more)21.5
binary inputampio/from/<mac>/state/i/<nr>0 or 11
binary outputampio/from/<mac>/state/o/<nr>0 or 11
analog inputampio/from/<mac>/state/a/<nr>0 or 2550
binary input extendedampio/from/<mac>/state/bi/<nr>0 or 10
binary output extendedampio/from/<mac>/state/bo/<nr>0 or 10
rgbampio/from/<mac>/state/rgb/<nr>0..255,0..255,0..255128,220,13
flagsampio/from/<mac>/state/f/<nr>
line flags ampio/from/<mac>/state/afu8/<nr>0..255
MRT – temperatureampio/from/<mac>/state/rs/<nr>25.5
8-bit analogue values (DALI, LED)ampio/from/<mac>/state/au/<nr>0…255234
16-bit analogue values (signed)ampio/from/<mac>/state/au16/<nr>0…65536
16-bit reduced by 10Kampio/from/<mac>/state/au16l/<nr>0…6553.623.4
32-bit values, e.g MODBUSampio/from/<mac>/state/au32/<nr>0…4 294 967 2961234

MQTT test

If you want to check all the available information in the system, use the mqtt in node, set the topic to ampio/# and connect debug. Then, click Done and Deploy. The data should appear in the debug window.

If you would like to check the data from one, selected module, set the topic to ampio/from/MAC/# (e.g. ampio/from/ABCD/#).

MAC address should always be entered without leading zeros.

Checking statuses

Always use the local MAC address to control modules.

If you want to check the status of a field in an M-DOT module, set the topic to:  ampio/from/3910/state/i/1 , where:

  • from stands for the direction, 
  • 3910 is a MAC address, 
  • state stands for checking the current status, 
  • 1 stands for the number of an input (M-DOT field 1)

Controlling outputs

In order to activate the first output in a device with the MAC address ABCD, set the topic to: ampio/to/ABCD/o/1/cmd , and payload to: on.

Both options presented below will bring the same result:

M-DOT control

Apart from controlling outputs with commands, there is also a possibility to create own texts on the M-DOT display with the use of API commands. In order to use them, select the topic RAW. It might be necessary to update the software of the M-DOT module.

Control via API can be divided according to different LCD displays’ dimensions, as follows:

M-DOT-M18 and M-DOT-M6 (from pcb 8) – resolution 240×320

Commands to be displayed (for multi-screen displays):

  • 1E 01 – change the screen number (e.g. 1E 01 05 – change the screen to number 6)
  • 1E 02 xx yy yy…- set text (small row), on screen nr xx to caption yy yy…., max. 12 characters
  • 1E 03 xx yy yy…- set text (big row), on screen nr xx to caption yy yy…., max. 9 characters

Functions not related to screens, always overwriting the current screen:

  • 29 03 – clear the screen
  • 29 14 x1 x1 y1 y1 xs xs ys ys ff ff cc cc – draw a frame on the screen, (x1 x1 – starting point on the X-axis, y1 y1 – starting point on the Y-axis, xs xs – x dimension, ys ys – y dimension, ff ff – frame width, cc cc – frame colour)
  • 29 0C x1 x1 x2 x2 y1 y1 y2 y2 ff ff cc cc – draw a rectangle on the screen, (x1 x1 – starting point on the X-axis, x2 x2 – end point on the X-axis, y1 y1 – starting point on the Y-axis, y2 y2 – end point on the y-axis, ff ff – frame width, cc cc – frame colour)
  • 29 18 xx xx yy yy cc cc bb bb zz zz zz zz zz – insert text in font 40×64 (xx xx – starting point on the X-axis, yy yy – starting point on the Y-axis, cc cc – text colour, bb bb – background colour, zz – max. 6 characters, only 0-9 and $ , – . / : + -)
  • 29 13 xx xx yy yy cc cc bb bb zz zz zz zz zz – insert text in font 26×48 (xx xx – starting point on the X-axis, yy yy – starting point on the Y-axis, cc cc – text colour, bb bb – background colour, zz – max. 9 characters)
  • 29 12 xx xx yy yy cc cc bb bb zz zz zz zz zz – insert text in font 20×32 (xx xx – starting point on the X-axis, yy yy – starting point on the Y-axis, cc cc – text colour, bb bb – background colour, zz – max. 12 characters)
  • 29 12 xx xx yy yy cc cc bb bb zz zz zz zz zz – insert text in font 10×16 (xx xx – starting point on the X-axis, yy yy – starting point on the Y-axis, cc cc – text colour, bb bb – background colour, zz – max. 24 characters)

For example, sending:

msg.topic = ampio/to/ABAB/raw
msg.payload = “1E03003031303130313031”; 

changes the big row to 1 and 0 (in accordance with the ASCII code) on M-DOT with the MAC address ABAB.

Sending msg.payload = “2918000000003344AABB30313233” will return 0123 on the screen in specified colours.

Note: please mind the bit significance – LSB/MSB.

Sending 291251000001… will start writing from 81 on the X-axis and 256 on the Y-axis. It is worth using a Windows calculator in a programmer mode for the calculations (hex 51 gives decimal 81, hex 100 gives decimal 256).

Sending 290C0000EF006A00D300000000 will draw a black rectangle extending over the whole width of the screen, between 1/3 and 2/3 of its height (it is the second row for the option 3 text rows).

Other M-DOT modules with smaller displays – resolution 128×160

  • 29 01 07 xx yy cc cc bb bb nn zz zz zz.. – insert text – small row, max. 11 characters (xx – x position, yy – y position, cc cc – text colour, bb bb – background colour, nn – number of characters, zz zz … – characters in Windows-1250 format)
  • 29 01 09 xx yy cc cc bb bb nn zz zz zz.. – insert text – big row, max. 6 characters (xx – x position, yy – y position, cc cc – text colour, bb bb – background colour, nn – number of characters, zz zz … – characters in Windows-1250 format)
  • 29 01 03 – clear the screen
  • 29 01 04 x1 y1 x2 y2 c1 c2 – draw a rectangle in a specified colour (x1 – starting point on the X-axis, y1 – starting point on the Y-axis, x2 – end point on the X-axis, y2 – end point on the Y-axis, c1 + c2 – rectangle colour 2-byte)
  • 29 01 0A ic x1 y1 cc cc bb bb – draw an icon (from the M-DOT’s memory, uploaded in the configurator), ic – icon number, x1 – starting point on the X-axis, y1 -starting point on the Y-axis, cc cc – icon colour, bb bb – background colour

2-byte colours are saved in an RGB565 format.

Multisensor M-SENS

Data that can be read from multisensor M-SENS:

  • Humidity: ampio/from/<mac>/state/au16l/1
  • Absolute pressure: ampio/from/<mac>/state/au16l/2
  • Volume: ampio/from/<mac>/state/au16l/3
  • Brightness: ampio/from/<mac>/state/au16l/4
  • Air quality: ampio/from/<mac>/state/au16l/5
  • Relative pressure: ampio/from/<mac>/state/au16l/6
  • Temperature: ampio/from/<mac>/state/t/1

Related Articles