HTTP-XMPP Bridge

The IoTBridgeHttp repository provides an IoT bridge between external devices that POST sensor data to the bridge using HTTP, for use in closed intra-networks or enterprise networks, or the public Internet, and the harmonized XMPP-based Neuro-Foundation network, for open and secure cross-domain interoperation on the Internet.

To run the bridge, you need access to an XMPP broker that supports the Neuro-Foundation extensions. You can use the TAG Neuron for XMPP.

Running and configuring the bridge

The code is written using .NET Standard, and compiled to a .NET Core console application that can be run on most operating systems. Basic configuration is performed using the console interface during the first execution, and persisted. You can also provide the corresponding configuration using environment variables, making it possible to run the bridge as a container. If an environmental variable is missing, the user will be prompted to input the value on the console.

Environmental Variable	Type	Description
`XMPP_HOST`	String	XMPP Host name
`XMPP_PORT`	Integer	Port number to use when connecting to XMPP (default is `5222`)
`XMPP_USERNAME`	String	User name to use when connecting to XMPP.
`XMPP_PASSWORD`	String	Password (or hashed password) to use when connecting to XMPP. Empty string means a random password will be generated.
`XMPP_PASSWORDHASHMETHOD`	String	Algorithm or method used for password. Empty string means the password is provided in the clear.
`XMPP_APIKEY`	String	API Key. If provided together with secret, allows the application to create a new account.
`XMPP_APISECRET`	String	API Secret. If provided together with key, allows the application to create a new account.
`REGISTRY_COUNTRY`	String	Country where the bridge is installed.
`REGISTRY_REGION`	String	Region where the bridge is installed.
`REGISTRY_CITY`	String	City where the bridge is installed.
`REGISTRY_AREA`	String	Area where the bridge is installed.
`REGISTRY_SRTEET`	String	Street where the bridge is installed.
`REGISTRY_STREETNR`	String	Street number where the bridge is installed.
`REGISTRY_BUILDING`	String	Building where the bridge is installed.
`REGISTRY_APARTMENT`	String	Apartment where the bridge is installed.
`REGISTRY_ROOM`	String	Room where the bridge is installed.
`REGISTRY_NAME`	String	Name associated with bridge.
`REGISTRY_LOCATION`	Boolean	If location has been completed. (This means, any location-specific environment variables not provided, will be interpreted as intensionally left blank, and user will not be prompted to input values for them.
`JWT_SECRET`	String	Secret used to create JWT tokens. If not provided, a random secret will be created.
`X509_FILENAME`	String	File name to X.509 certificate to use. If not provided, HTTPS will not be enabled.
`X509_PASSWORD`	String	Password to X.509 certificate.
`HTTP_PORT`	Integer	Port number to use for unencrypted HTTP. (default is `80`)
`HTTPS_PORT`	Integer	Port number to use for encrypted HTTPS. (default is `443`)
`ADMIN_NAME`	String	Administrator User name.
`ADMIN_PASSWORD`	String	Administrator Password.
`USER_COUNT`	Integer	Number of users to create. (Default is `0`, which will trigger manual input of users.)
`USER_N_NAME`	String	User name for user `N`. (where `N` is a number between `1` and `USERS_COUNT`)
`USER_N_PASSWORD`	String	Password for user `N`. (where `N` is a number between `1` and `USERS_COUNT`)
`USER_N_PRIVILEGE`	String	Regular expression specifying the privilege or privileges held by the user. (Default is `Admin.SensorData.Post`.)

Running in a Docker container

You can run the bridge in a Docker container. When doing so it is important to either configure all settings via the environment variables, or to redirect stdin and allocate a TTY. You do this using the -it switch to docker run. For example:

docker run -it iot-bridge-http

Setting up persistent storage

Persistent storage is required to store configuration, as well as data about the bridge, its nodes, and ownerships, etc. You can do this by mapping the local folder /var/lib/IoT Gateway to a Volume when creating the container.

Using an environment file

You can provide environment variables using an environment file. Create a new text file based on the IoTBridgeHttp.env file in the repository. Set the values you want to provide, and then use the --env-file switch when creating the container. For example:

docker run -it --env-file IoTBridgeHttp.env -v /my/local/folder:/var/lib/IoT\ Gateway iot-bridge-http

Note: If providing credentials, make sure the file is not accessible by others, and make sure it is not checked in to any repository. An alternative to providing credentials in an environment file, is to enable standard and terminal input, and provide it via the prompt (see above).

Claiming ownership of bridge

Once the bridge has been configured, it will generate an iotdisco URI, and save it to its programd data folder. It will also create a file with extension .url, containing a shortcut with the iotdisco URI inside. A .png file with a QR code will also be generated. All three files contain information about the bridge, and allows the owner to claim ownership of it. This can be done by using the Neuro-Access App. This app is also downloadable for Android and iOS. You scan the QR code (or enter it manually), and claim the device. Once the device is claimed by you, you will receive notifications when someone wants to access the deice. They will only be able to access it with the owner’s permission. For more information, see:

Configuring the bridge

The bridge can be configured in detail by a client that implements the concentrator interface. Concentrators consist of data sources, each containing tree structures of nodes. Nodes may be partitioned into partitions, which permits the nesting of subsystems seamlessly into container systems. Each node can be of different types, and have different properties and underlying functionality. They can each implement then sensor interface and actuator interface.

You can use the Simple IoT Client to configure concentrators and their nodes in detail. An initial setup is done using the initial configuration of the bridge. The client is also available in the IoTGateway repository, in the Clients folder.

Node Types

The bridge includes several different node types that can be used to configure its operation:

The Local Web Server Node represents the local web server in the gateway. This node hosts the web service that allows external devices to POST sensor data to the bridge. It also acts as the root node for the subtree of nodes representing devices that receive sensor data via HTTP POST requests.
The XMPP Broker maintains a connection to an XMPP Broker. It allows the bridge to connect to other entities on the federated network and communicate with them. It supports communication with remote standalone sensors and actuators, as well as remote concentrators embedding devices into data sources and nodes. Such concentrators can be bridges to other protocols and networks.

Note: The bridge has a client-to-server connection by default, setup during initial configuration. Through this connection, the bridge acts as a concentrator. Through the use of XMPP Broker nodes you can setup additional XMPP connections to other brokers. In these cases the bridge will only act as a client, to connect to remove devices for the purposes of interacting with them.
IP Host nodes allow you to monitor network hosts accessible from the bridge.
Script nodes allow you to create nodes with custom script logic. They can be used to interface bespoke devices in the network accessible from the bridge, for example.
Virtual nodes are placeholders where external logic (or script logic) can aggregate information in a way that makes them accessible by others in the federated network.

API Reference

The local web service registers a series of web resources that external devices can use. Following is a brief overview, with references for more details.

Sensor Data Receptor

The Sensor data receptor resource /ReportSensorData is used by external devices to POST sensor data to the bridge. The device needs to authenticate with the bridge, before it can be authorized to access this resource. The device can use different mechanisms to authenticate itself with the bridge:

Use of Mutual TLS (mTLS). This requires the bridge to be configured with a certificate.
Use of WWW-Authenticate web login procedure.
Use of JSON Web Tokens (JWT) Bearer tokens for authentication. This requires the device to login first using the Login resource (see below).

For details on how the resource works, see the Sensor Data Receptor API endpoint on lab.tagroot.io as an example. The same page can be viewed on the bridge, once it is up and running.

Login resource

The Login resource /Login is used to login to the bridge. If successful, a Bearer JWT token is returned. External devices need to login to the bridge before they can POST sensor data to it. A token is valid for 1 hour. The external device needs to renew the token by loggin in again, if accessing the bridge for a longer period of time.

Input payload is expected to be a JSON object of the following type.

{
	"UserName": Required(Str(PUserName)),
	"PasswordHash": Required(Str(PPasswordHash)),
	"Nonce": Required(Str(PNonce))
}

The response is a JSON object of the following type:

{
	"Ok": Required(Bool(POK)),
	"Message": Required(Str(PMessage)),
	"Token": Optional(Str(PToken))
}

See the Web login procedure article for more details on how to compute the password hash and nonce values, and use them in the login process.

Root folder resource

The Root folder resource /. If no specific resource above is referenced, the default is to look for a file resource in the Root folder, and return it if found. This allows you to host custom web content on the bridge.

Web Page

The root resource / makes a temporary redirection to /Index.md, which is the landing page for the bridge. It contains basic information about the bridge, as well as a login-mechanism to access the setup of the bridge. Once logged in, you can manually edit roles and users.

Security

The HTTP bridge supports multiple levels of security:

Access to things published on the federated network is protected by provisioning. When the gateway starts, it generates an iotdisco URI, which can be used to claim ownership of the device. Once claimed, the owner receives notifications when someone wants to access the device, and can decide whether to allow access or not.
The bridge supports a set of users and roles, each defining a set of privileges. During first start, the initial users and roles are configured. This can be done either using environment variables, or by providing input on the console. An administrator user is created, which will have all privileges. Once the bridge is up and running, the administrator can login and configure existing users and roles, and create new ones.
A Web-Application Firewall (WAF) is included in the bridge. The administrator can configure the WAF to block or allow access to specific resources, based on application-level rules. This can be used to restrict access to certain pages (such as the administrative pages) to certain IPs, for instance, or rate-limit access to certain resources, such as sensor-data publication resrouces.

The Web-Application Firewall is defined in the WAF.xml file. It is an XML file that needs to validate against the https://waher.se/Schema/WAF.xsd namespace. The default version restricts access to the administration pages to local area network IP addresses.

#new, #repository, #iot, #http, #xmpp, #bridge

10 Simulated Accounts with Digital Identities online for test

10 accounts with simulated digital identities are now available online, accessible via XMPP. They can be used for test, for instance, if you are implementing a service relying on Multi-Factor Authentication using the Remote Login API, or similar.

Following is the list of accounts being used, and the corresponding digital identities:

Simulated identities
JID	Legal ID
`SimLegal1@lab.tagroot.io`	`30f421e9-c12c-4731-d432-0c297a1697db@legal.lab.tagroot.io`
`SimLegal2@lab.tagroot.io`	`30f421ea-c12c-4736-d432-0c297a3d84c9@legal.lab.tagroot.io`
`SimLegal3@lab.tagroot.io`	`30f421ea-c12c-4750-d432-0c297a14f4b8@legal.lab.tagroot.io`
`SimLegal4@lab.tagroot.io`	`30f421ea-c12c-4758-d432-0c297aaeb627@legal.lab.tagroot.io`
`SimLegal5@lab.tagroot.io`	`30f421eb-c12c-476d-d432-0c297a7108a0@legal.lab.tagroot.io`
`SimLegal6@lab.tagroot.io`	`30f421eb-c12c-4788-d432-0c297a728f7e@legal.lab.tagroot.io`
`SimLegal7@lab.tagroot.io`	`30f421eb-c12c-4794-d432-0c297ae03870@legal.lab.tagroot.io`
`SimLegal8@lab.tagroot.io`	`30f421ec-c12c-47aa-d432-0c297a24fd6c@legal.lab.tagroot.io`
`SimLegal9@lab.tagroot.io`	`30f421ec-c12c-47b8-d432-0c297a2fade1@legal.lab.tagroot.io`
`SimLegal10@lab.tagroot.io`	`30f421ec-c12c-47be-d432-0c297a74a7e4@legal.lab.tagroot.io`

QR Codes

The following QR codes are available for ease of access to the above devices.

Petitions

The accounts will automatically accept the following petitions:

Identity Petitions: Scan the QR Codes (or enter the Legal IDs manually) using the Neuro-Access App to send an Identity Petition to the account. The petition will be accepted and approved automatically.
Signature Petitions: Initiating a Remote Login using the Remote Login API will send a Signature Petition to the account. This petition will be automatically approved as well. The Remote Login API will return a JWT token as soon as the petition has been approved and signed.

Note: The model controlling the simulation can be reviewed in the ComSim repository

#simulation, #comsim, #iot, #iotid

Modbus-XMPP Bridge

The IoTBridgeModbus repository provides an IoT bridge between devices connected to Modbus, for use in closed intra-networks or enterprise networks, and the harmonized XMPP-based Neuro-Foundation network, for open and secure cross-domain interoperation on the Internet.

To run the bridge, you need access to both a Modbus gateway, and an XMPP broker, that supports the Neuro-Foundation extensions. You can use the TAG Neuron for XMPP.

Running and configuring the bridge

Environmental Variable	Type	Description
`XMPP_HOST`	String	XMPP Host name
`XMPP_PORT`	Integer	Port number to use when connecting to XMPP (default is `5222`)
`XMPP_USERNAME`	String	User name to use when connecting to XMPP.
`XMPP_PASSWORD`	String	Password (or hashed password) to use when connecting to XMPP. Empty string means a random password will be generated.
`XMPP_PASSWORDHASHMETHOD`	String	Algorithm or method used for password. Empty string means the password is provided in the clear.
`XMPP_APIKEY`	String	API Key. If provided together with secret, allows the application to create a new account.
`XMPP_APISECRET`	String	API Secret. If provided together with key, allows the application to create a new account.
`MODBUS_HOST`	String	Modbus Gateway Host name
`MODBUS_TLS`	String	If TLS encryption is to be used when connecting to the Modbus gateway.
`MODBUS_PORT`	String	Port number to use when connecting to the Modbus gateway (default is `502`).
`REGISTRY_COUNTRY`	String	Country where the bridge is installed.
`REGISTRY_REGION`	String	Region where the bridge is installed.
`REGISTRY_CITY`	String	City where the bridge is installed.
`REGISTRY_AREA`	String	Area where the bridge is installed.
`REGISTRY_SRTEET`	String	Street where the bridge is installed.
`REGISTRY_STREETNR`	String	Street number where the bridge is installed.
`REGISTRY_BUILDING`	String	Building where the bridge is installed.
`REGISTRY_APARTMENT`	String	Apartment where the bridge is installed.
`REGISTRY_ROOM`	String	Room where the bridge is installed.
`REGISTRY_NAME`	String	Name associated with bridge.
`REGISTRY_LOCATION`	Boolean	If location has been completed. (This means, any location-specific environment variables not provided, will be interpreted as intensionally left blank, and user will not be prompted to input values for them.

Claiming ownership of bridge

Configuring the bridge

Node Types

The bridge includes several different node types that can be used to configure its operation:

The Modbus Gateway maintains a connection to a Modbus Gateway using TCP/IP, and converts requests into binary Modbus TCP/IP communication.
The XMPP Broker maintains a connection to an XMPP Broker. It allows the bridge to connect to other entities on the federated network and communicate with them. It supports communication with remote standalone sensors and actuators, as well as remote concentrators embedding devices into data sources and nodes. Such concentrators can be bridges to other protocols and networks.

Note: The bridge has a client-to-server connection by default, setup during initial configuration. Through this connection, the bridge acts as a concentrator. Through the use of XMPP Broker nodes you can setup additional XMPP connections to other brokers. In these cases the bridge will only act as a client, to connect to remove devices for the purposes of interacting with them.
IP Host nodes allow you to monitor network hosts accessible from the bridge.
Script nodes allow you to create nodes with custom script logic. They can be used to interface bespoke devices in the network accessible from the bridge, for example.
Virtual nodes are placeholders where external logic (or script logic) can aggregate information in a way that makes them accessible by others in the federated network.

#new, #repository, #iot, #modbus, #xmpp, #bridge

MQTT-XMPP Bridge

The IoTBridgeMqtt repository provides an IoT bridge between devices connected to MQTT, for use in closed intra-networks or enterprise networks, and the harmonized XMPP-based Neuro-Foundation network, for open and secure cross-domain interoperation on the Internet.

To run the bridge, you need access to both an MQTT broker, and an XMPP broker, that supports the Neuro-Foundation extensions. You can use the Mosquitto broker for MQTT, and the TAG Neuron for XMPP.

Running and configuring the bridge

Environmental Variable	Type	Description
`XMPP_HOST`	String	XMPP Host name
`XMPP_PORT`	Integer	Port number to use when connecting to XMPP (default is `5222`)
`XMPP_USERNAME`	String	User name to use when connecting to XMPP.
`XMPP_PASSWORD`	String	Password (or hashed password) to use when connecting to XMPP. Empty string means a random password will be generated.
`XMPP_PASSWORDHASHMETHOD`	String	Algorithm or method used for password. Empty string means the password is provided in the clear.
`XMPP_APIKEY`	String	API Key. If provided together with secret, allows the application to create a new account.
`XMPP_APISECRET`	String	API Secret. If provided together with key, allows the application to create a new account.
`MQTT_HOST`	String	MQTT Host name
`MQTT_TLS`	String	If TLS encryption is to be used when connecting to the MQTT broker.
`MQTT_PORT`	String	Port number to use when connecting to MQTT (default is `1883` for unencrypted MQTT and 8883 for encrypted MQTT).
`MQTT_USERNAME`	String	User name to use when connecting to MQTT. Can be empty if no user credentials are provided.
`MQTT_PASSWORD`	String	Password to use when connecting to XMPP. Can be empty if no user credentials are provided.
`REGISTRY_COUNTRY`	String	Country where the bridge is installed.
`REGISTRY_REGION`	String	Region where the bridge is installed.
`REGISTRY_CITY`	String	City where the bridge is installed.
`REGISTRY_AREA`	String	Area where the bridge is installed.
`REGISTRY_SRTEET`	String	Street where the bridge is installed.
`REGISTRY_STREETNR`	String	Street number where the bridge is installed.
`REGISTRY_BUILDING`	String	Building where the bridge is installed.
`REGISTRY_APARTMENT`	String	Apartment where the bridge is installed.
`REGISTRY_ROOM`	String	Room where the bridge is installed.
`REGISTRY_NAME`	String	Name associated with bridge.
`REGISTRY_LOCATION`	Boolean	If location has been completed. (This means, any location-specific environment variables not provided, will be interpreted as intensionally left blank, and user will not be prompted to input values for them.

Claiming ownership of bridge

Configuring the bridge

Node Types

The bridge includes several different node types that can be used to configure its operation:

The MQTT Broker maintains a connection to an MQTT Broker, and allows the bridge to subcribe to content published on topics, as well as publish content to topics on the broker. The topic hierarchy will be modelled using MQTT Topic nodes, or derivatives. Common data types are recognized and parsed. You can read each topic individually, or a parent topic, and receive information from all child topics, as field values.
The XMPP Broker maintains a connection to an XMPP Broker. It allows the bridge to connect to other entities on the federated network and communicate with them. It supports communication with remote standalone sensors and actuators, as well as remote concentrators embedding devices into data sources and nodes. Such concentrators can be bridges to other protocols and networks.

Note: The bridge has a client-to-server connection by default, setup during initial configuration. Through this connection, the bridge acts as a concentrator. Through the use of XMPP Broker nodes you can setup additional XMPP connections to other brokers. In these cases the bridge will only act as a client, to connect to remove devices for the purposes of interacting with them.
IEEE 1451 nodes are derivatives of MQTT nodes, and implement support for the IEEE 1451 family of standards, of which IEEE 1451.1.6 manages communication over MQTT.
IP Host nodes allow you to monitor network hosts accessible from the bridge.
Script nodes allow you to create nodes with custom script logic. They can be used to interface bespoke devices in the network accessible from the bridge, for example.
Virtual nodes are placeholders where external logic (or script logic) can aggregate information in a way that makes them accessible by others in the federated network.

#new, #repository, #iot, #mqtt, #xmpp, #bridge

Data Sheets in Digital Sensor Twins

The LegalLab repository contains an example smart contract for creating digital sensor twins. This template, together with the LegalLab utility, has been updated to support uploading and presentation of data sheets for the underlying sensors being mirrored digitally.

The process of attaching such data sheets is straight-forward:

Publish the new digital sensor template to your Neuron®, and get it approved.
Create a smart contract based on this template, pointing to the sensor you want to mirror.
Before signing the contract, upload any number of data-sheets appropriate for the digital twin. If these attachments are in the following formats, they will be presented together with sensor data from the sensor:
- Plain text file (*.txt)
- Markdown text file (*.md)
- Image files (*.jpg, *.png, *.webp, and other supported formats)
- Microsoft Word files, in the interoperable OpenXML format (*.docx)
- Microsoft Excel files, in the interoperable OpenXML format (*.xlsx)
Once data sheets have been uploaded, sign the contract accordingly.
Once the token has been created, create a Present Report to view sensor data, together with associated data sheets.

Note: For performance reasons, it might be less resource-intensive and quicker to pre-convert MS Word files to Markdown, and upload the Markdown file.

Note 2: For security reasons, only files (actually Internet Content-Types) recognized by both LegalLab and the Neuron® will be accepted.

Note 3: To be able to upload and process Microsoft Word documents and Excel spreadsheets, you need to install the Microsoft Interoperability package. You can also check microsoft for more information related to Microsoft interoperability.

#new, #features, #contracts, #legallab, #sensor, #iot

Posts tagged #iot

No more posts with the given tag could be found. You can go back to the main view by selecting Home in the menu above.