Omnia Gateway

The Omnia Gateway is a core component of the Omnia Network. It handles the communication between the Omnia Backend and the IoT devices.

We suggest reading the Architecture document to understand how the Omnia Network works before diving into the code.

Considerations

The Omnia Gateway is written in Typescript, mainly because the most popular and more maintained Web of Things (WoT) library is node-wot. The plans are to migrate to Rust in the future.

IoT protocols support

In the current version, the Omnia Gateway supports Matter only, but the plans are to expand to any other relevant IoT protocol.

We want to expand the support to HTTP, so that the Omnia Gateway can be deployed on top of any other IoT gateway that already handles the IoT protocol of that specific use case.

WoT mappings

To make the underlying IoT protocols interoperable, the Omnia Gateway uses the Web of Things (WoT) standard. An example of how Matter is mapped to WoT can be found in wot-mapping.json. This JSON file is generated using the generate-matter-wot-mapping script.

Getting started

The current version has been tested on a Raspberry Pi 4 (with Ubuntu Server 22.04 LTS (64-bit) OS).

Prerequisites

• Node.js (v16.14.1 or higher)
• npm (v8.5.5)
• Docker (v23.0.6 or higher)
• Docker Compose (v2.17.2 or higher)
• a chip-tool binary (the Matter Controller) for the Raspberry Pi 4 (see Building Matter guide and pay attention to Prerequisites on Raspberry Pi 4)

Configuration

Copy the .env.example file to .env and fill in the required values.

The following environment variables need an explanation:

• MATTER_CONTROLLER_CHIP_TOOL_PATH is the path to the Matter Controller binary (the chip-tool mentioned in the prerequisites)
• ENABLE_MATTER_CONTROLLER is a flag to enalbe/disable the Matter Controller (useful to set it to false during development if the Matter Controller is not available)
• WIFI_SSID and WIFI_PASSWORD are the credentials of the WiFi network to which the Gateway is connected to. This is used to configure Matter Devices during the commissioning process.
• ENABLE_PROXY is a flag to enable/disable the connection to the Omnia Proxy. This is particularly useful when the Gateway is deployed on a local network and it's not reachable from the Internet. See Omnia Proxy for details on how to configure the other required variables.
• DFX_NETWORK: in the current version the only supported IC replica is the local one, available when running dfx start. See Omnia Backend for details.

Running (Docker)

We suggest running the Omnia Gateway using Docker, so that an NGINX reverse proxy can be used to handle the HTTPS communication from Internet Computer Canisters.

Make sure Docker engine is running and then run the following command:

docker compose up

This will build the Gateway Docker image and run it.

Tests

We use Jest to run tests. All tests are in the __tests__ folder.

Currently, only few unit tests are available.

To run tests, simply run:

npm test

To have also the coverage report, run:

npm run test:coverage

License

Licensed under the MIT License.

Dependencies report

To generate a report of all dependencies licenses, run the following command:

npm run report:licenses