Chapter 3. Getting Started with Internet of Things (IoT) on AMQ Online

Important

The Internet of Things (IoT) feature of AMQ Online is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service-level agreements (SLAs) and might not be functionally complete; therefore, Red Hat does not recommend implementing any Technology Preview features in production environments. This Technology Preview feature provides early access to upcoming product innovations, enabling you to test functionality and provide feedback during the development process. For more information about support scope, see Technology Preview Features Support Scope.

3.1. Installing AMQ Online using a YAML bundle

The simplest way to install AMQ Online is to use the predefined YAML bundles.

Procedure

  1. Log in as a user with cluster-admin privileges:

    oc login -u system:admin
  2. (Optional) If you want to deploy to a namespace other than amq-online-infra you must run the following command and substitute amq-online-infra in subsequent steps:

    sed -i 's/amq-online-infra/my-namespace/' install/bundles/amq-online/*.yaml
  3. Create the project where you want to deploy AMQ Online:

    oc new-project amq-online-infra
  4. Deploy using the amq-online bundle:

    oc apply -f install/bundles/amq-online
  5. (Optional) Install example plans and infrastructure configuration:

    oc apply -f install/components/example-plans
  6. (Optional) Install example roles:

    oc apply -f install/components/example-roles
  7. (Optional) Install the standard authentication service:

    oc apply -f install/components/example-authservices/standard-authservice.yaml

3.2. Installing IoT services

To get started using the IoT feature on AMQ Online, you must first install the IoT services.

Procedure

  1. Deploy the IoT bundles:

    oc apply -f install/preview-bundles/iot
  2. Create certificates for the MQTT protocol adapter. For testing purposes, you can create a self-signed certificate:

    ./install/components/iot/examples/k8s-tls/create
    oc create secret tls iot-mqtt-adapter-tls --key=install/components/iot/examples/k8s-tls/build/iot-mqtt-adapter-key.pem --cert=install/components/iot/examples/k8s-tls/build/iot-mqtt-adapter-fullchain.pem
    Note

    If your cluster is not running on localhost, you need to specify the cluster host name when creating certificates to allow external clients (like MQTT) to properly connect to the appropriate services. For example:

    CLUSTER=x.x.x.x.nip.io install/components/iot/examples/k8s-tls/create
  3. Install an example IoT infrastructure configuration:

    oc apply -f install/components/iot/examples/iot-config.yaml

3.3. Creating an IoT project

After installing the IoT services, you create an IoT project.

Procedure

  1. Log in as a messaging tenant:

    oc login -u developer
  2. Create a managed IoT project:

    oc new-project myapp
    oc create -f install/components/iot/examples/iot-project-managed.yaml
  3. Wait for the resources to be ready:

    oc get addressspace -w
    oc get iotproject -w
  4. Create a messaging consumer user:

    oc create -f install/components/iot/examples/iot-user.yaml

3.4. Creating an IoT device

After installing the IoT services and creating an IoT project, you can create an IoT device for the device you want to monitor.

Procedure

  1. Register a device:

    curl --insecure -X POST -i -H 'Content-Type: application/json' --data-binary '{"device-id": "4711"}' https://$(oc -n enmasse-infra get routes device-registry --template='{{ .spec.host }}')/registration/myapp.iot
  2. Add credentials for a device:

    curl --insecure -X POST -i -H 'Content-Type: application/json' --data-binary '{"device-id": "4711","type": "hashed-password","auth-id": "sensor1","secrets": [{"hash-function" : "sha-512","pwd-plain":"'hono-secret'"}]}' https://$(oc -n enmasse-infra get routes device-registry --template='{{ .spec.host }}')/credentials/myapp.iot

3.5. Sending and receiving telemetry data

3.5.1. Starting the telemetry consumer

Procedure

  1. In the Hono project, run:

    cd cli
  2. Run the following command at least once:

    mvn package -am
  3. Get the messaging endpoint certificate:

    oc -n myapp get addressspace iot -o jsonpath={.status.caCert} | base64 --decode > target/config/hono-demo-certs-jar/tls.crt
  4. Export the messaging endpoint host and port:

    export MESSAGING_HOST=$(oc -n myapp get addressspace iot -o jsonpath={.status.endpointStatuses[?\(@.name==\'messaging\'\)].externalHost})
    export MESSAGING_PORT=443
  5. Run the consumer application:

    mvn spring-boot:run -Drun.arguments=--hono.client.host=$MESSAGING_HOST,--hono.client.port=$MESSAGING_PORT,--hono.client.username=consumer,--hono.client.password=foobar,--tenant.id=myapp.iot,--hono.client.trustStorePath=target/config/hono-demo-certs-jar/tls.crt,--message.type=telemetry

3.5.2. Sending telemetry data

Procedure

  1. Send a message using HTTP protocol:

    curl --insecure -X POST -i -u sensor1@myapp.iot:hono-secret -H 'Content-Type: application/json' --data-binary '{"temp": 5}' https://$(oc -n enmasse-infra get routes iot-http-adapter --template='{{ .spec.host }}')/telemetry
  2. Send a message using MQTT protocol:

    mosquitto_pub -d -h $(oc -n enmasse-infra get routes iot-mqtt-adapter --template='{{ .spec.host }}') -p 443 -u 'sensor1@myapp.iot' -P hono-secret -t telemetry -m '{"temp": 5}' -i 4711 --cafile install/components/iot/examples/k8s-tls/build/iot-mqtt-adapter-fullchain.pem

3.6. Sending and receiving event data

3.6.1. Starting the event consumer

Procedure

  1. In the Hono project, run:

    cd cli
  2. Run the following command at least once:

    mvn package -am
  3. Get the messaging endpoint certificate:

    oc -n myapp get addressspace iot -o jsonpath={.status.caCert} | base64 --decode > target/config/hono-demo-certs-jar/tls.crt
  4. Export the messaging endpoint host and port:

    export MESSAGING_HOST=$(oc -n myapp get addressspace iot -o jsonpath={.status.endpointStatuses[?\(@.name==\'messaging\'\)].externalHost})
    export MESSAGING_PORT=443
  5. Run the consumer application:

    mvn spring-boot:run -Drun.arguments=--hono.client.host=$MESSAGING_HOST,--hono.client.port=$MESSAGING_PORT,--hono.client.username=consumer,--hono.client.password=foobar,--tenant.id=myapp.iot,--hono.client.trustStorePath=target/config/hono-demo-certs-jar/tls.crt,--message.type=event

3.6.2. Sending event data

Procedure

  1. Send a message using HTTP protocol:

    curl --insecure -X POST -i -u sensor1@myapp.iot:hono-secret -H 'Content-Type: application/json' --data-binary '{"temp": 5}' https://$(oc -n enmasse-infra get routes iot-http-adapter --template='{{ .spec.host }}')/event
  2. Send a message using MQTT protocol:

    mosquitto_pub -d -h $(oc -n enmasse-infra get routes iot-mqtt-adapter --template='{{ .spec.host }}') -p 443 -u 'sensor1@myapp.iot' -P hono-secret -t event -m '{"temp": 5}' -i 4711 --cafile install/components/iot/examples/k8s-tls/build/iot-mqtt-adapter-fullchain.pem