..
    Copyright 2019,2020 NXP


.. highlight:: shell

.. _linux-demos-azure:

Azure Demo for iMX Linux / Raspberry Pi
========================================================================

This demo demonstrates connection to Azure IoTHub using pre-provisioned
device credentials and demonstrates publish/subscribe procedure using MQTT.

Prerequisites
----------------------------------

-  Azure account
-  SD Card image with SE050 Middleware pre-installed. The application is
   built on the iMX platform.
-  IMX6UL-EVK platform or Raspberry pi connected to the Internet

Preparing the credentials and Provisioning the secure element
-------------------------------------------------------------------------

Use ssscli tool from iMX/Rpi platform

1) Complete :numref:`cli-doc-pre-steps` :ref:`cli-doc-pre-steps`

#)  To create certificates on imx and Raspberry Pi, call::

        cd simw-top/pycli/Provisioning
        python3 GenerateAZURECredentials.py
        python3 ResetAndUpdate_AZURE.py

#) Certificates and Keys are generated at ``simw-top/pycli/Provisioning/azure``


Registering Device
-------------------------------------------------------------

To register the device onto the IoT Hub portal, we can either upload Root credentials manually
or we can register an individual device using ``azure_imx_register`` application. If you wish
to upload Root credentials, skip the next steps and proceed to :ref:`azure-imx-upload-root`.


.. _azure-register-device:

Create device enrollment in azure IoT Hub portal
-------------------------------------------------------------
**This step is only for individual device enrollment.**

Prerequisite: Azure IOT hub and Azure IOT HUB DPS account which are linked.

Refer: https://docs.microsoft.com/en-us/azure/iot-dps/tutorial-set-up-cloud

https://docs.microsoft.com/en-us/azure/iot-dps/quick-setup-auto-provision

Once required accounts exist we can enroll the devices.
For this we only need device certificate which we created in above steps.

Follow the steps to enroll the device: https://docs.microsoft.com/en-us/azure/iot-dps/tutorial-provision-device-to-hub

.. note:: When creating device certificates be sure to use only lower-case alphanumerics and hyphens in your device name.

Run ``azure_imx_register`` application to register the device onto your IoT Hub.

``azure_imx_register`` application can take parameters either via JSON file or via command line.
The required parameters are:

- registerid: Registration id of the device (common name of device certificate)
- keypath:  Path to reference key pem file
- devcert: Path to device certificate
- rootpath: Path to azure root CA certificate
- idscope: IDScope (can found in Azure IoT-DPS account - Overview)

Run via command line as::

  ./azure_imx_register --registerid test-device --keypath keyref.pem --rootpath azureRootCA.pem --devcert cert.pem --idscope 0ne00068F95

Or pass JSON file as::

  ./azure_imx_register --json json_register_config.json

Sample JSON file::

  {
    "devcert": "cert.pem",
    "keypath": "keyref.pem",
    "id_scope": "0ne00068F95",
    "registration_id": "test-device",
    "rootpath": "azureRootCA.pem"
  }

Upon successful registration, "DeviceID".txt file is created with DeviceID, assigned hub along with keyref, device certificate and root certificate path.
This file can be given as input to connect to device and send messages.

The device is now registered and appears on IoT Azure hub under devices tab

We can pass this JSON file to ``azure_imx_connect`` application to connect to IoT Hub. You can skip the next step and proceed to :ref:`azure-openssl-build`.


.. _azure-imx-upload-root:

Uploading root certificates to IoT Hub
-------------------------------------------------------------

1) On Azure IoT Hub portal, Navigate to ``Dashboard --> <Your IoT Hub> --> Certificates``. Click on Add

#) Enter a friendly name and upload the root certificate created in the previous step. Location -  ``simw-top/pycli/Provisioning/azure/RootCA.cer`` -> Save

#) Your certificate will show in the Certificate Explorer list. Click on certificate added

#) In Certificate Details, click Generate Verification Code

#) The provisioning service creates a Verification Code that you can use to validate the certificate ownership. Copy the code to your clipboard

#) Use the verification_certificate.py to generate a verify certificate (verifyCert4.cer) ::

        cd simw-top/pycli/Provisioning
        python verification_certificate.py <RootCA_Certificate> <RootCA_Keypair> <Verification Code>

#) On ``Azure portal -> Certificate Details``, upload the verifyCert4.cer file generated and click Verify.

   STATUS of your certificate should change to ``Verified`` in the Certificate Explorer list


.. _azure-openssl-build:


Build the OpenSSL engine [Optional]
-------------------------------------------------------------

.. note::
    This step is optional in case you are using a prepared
    SD card image from NXP.

The OpenSSL engine uses the sss abstraction layer to access the crypto
services of the secure element, the implementation remains dependent on
the secure element attached. The following illustrates compiling the
OpenSSL engine for SE050 connected over I2C.

::

   cd simw-top
   python scripts/create_cmake_projects.py
   cd ../simw-top_build/imx_native_se050_t1oi2c
   cmake --build .
   make install
   ldconfig /usr/local/lib

.. note::
    Replace ``imx_native_se050_t1oi2c`` with ``raspbian_native_se050_t1oi2c``
    when building for Raspberry Pi.

Run the example
---------------

1) Use 'buildScript.sh' script at simw-top/demos/linux/azure/ to download all dependencies and build the mqtt application for azure call::

    cd /simw-top/demos/linux/azure
    ./buildScript.sh

#) Based on OpenSSL version and applicable Secure Element, select the appropriate configuration file in
   ``<MW_SRC_DIR>/simw-top/demos/linux/common`` directory::

        openssl11_sss_a71ch.cnf   ----- OpenSSL 1.1.1 and A71CH
        openssl11_sss_se050.cnf   ----- OpenSSL 1.1.1 and SE050
        openssl_sss_a71ch.cnf     ----- OpenSSL 1.0.0 and A71CH
        openssl_sss_se050.cnf     ----- OpenSSL 1.0.0 and SE050

#) Set the openssl config path as call::

    $ export OPENSSL_CONF=/simw-top/demos/linux/common/<appropriate-cnf-file>

#) To run the application, call::

    $ ./azure_imx_connect --deviceid "<devive_name>" --keypath simw-top/pycli/Provisioning/azure/<UID>_device_reference_key.pem --rootpath simw-top/demos/linux/azure/azureRootCA.pem --devcert simw-top/pycli/Provisioning/azure/<UID>_device_certificate.cer --hubname <IotHubName>.azure-devices.net --username <IotHubName> --payload "<MESSAGE>"


   Or pass JSON file as::

    ./azure_imx_connect --json json_connect_config.json

   Sample json_connect_config.json::

    {
      "assignedHub": "ABCD.azure-devices.net",
      "deviceId": "test-device",
      "registration_id": "test-device",
      "status": "assigned",
      "keypath": "keyref.pem",
      "devcert": "cert.pem",
      "rootpath": "azureRootCA.pem",
      "payload": "hello message from device test-device"
    }

   .. note:: If you have used ``azure_imx_register`` application, ``json_connect_config.json`` is same as ``"DeviceID".txt``


.. note::
    1) Export the OpenSSL conf path to the exact location of the file. The above example is for illustrative purpose
    2) While executing the application, use the appropriate values for device cert, Device id, Path, hubname and username