================== Connecting Devices ================== This section will show, how devices can be connected to EDP. Raspberry Pi will be used as device, and Apache Felix 7.0.5 and JamaicaAMS 1.1.1 will be taken as concrete OSGi framework examples. For details on connection settings when using Karaf or Equinox, please contact **info@aicas.com**. ---------------------- Runtime and EDP Client ---------------------- For users to connect their devices to the EDP web portal running in their chosen URL, the first step would be to download the OSGi framework, also referred to here as runtime. Central to the connection is the EDP Client, which establishes the link between the device and the EDP portal. It comprises artifacts that bind together functionalities and dependencies as OSGi bundles, compatible with the runtime in the devices. The structure of the EDP Client zip file is shown below. .. code-block:: text . |-- build.info |-- com.aicas.edp.client-.jar |-- conf |-- logging.properties ‘-- system.properties |-- provisioning.properties |-- provisioning.sh ‘-- README.md 1 directory, 7 files The EDP Client includes a Bash script that supports an automatic approach, allowing users to bypass certain manual procedures during installation. The main advantage of this automation is the possibility to provision multiple devices in parallel. The script *provisioning.sh* is responsible for downloading the necessary certificates, copying files, updating configurations, and starting services on target devices. It supports simultaneous provisioning of devices using CSV files and logging the whole process for each device. *Please note that this provisioning workaround is currently supported for devices running aicas’ JamaicaAMS, Apache Felix and Equinox. For other use cases, all manual steps described below are valid. On the other hand, the steps covered by the automatic provisioning will be indicated*. Initial Settings ================ In terms of general configuration, users must see that the correct **endpoint is declared**, so that the EDP Client residing in the device can communicate with the EDP web portal. In the AWS console, the IoT endpoint can be found at *AWS > IoT Core > Connect > Domain configurations*. This value must be declared as the Endpoint in *conf/system.properties*. Please note that *conf/system.properties* is part of the setup structure of both JamaicaAMS and Apache Felix. .. code-block:: bash # Please adapt the paths to the policy files as needed java.security.policy=./conf/all.policy edp.client.keystore=./conf/example.p12 edp.client.iot-endpoint= *Please note: By the automatic provisioning of devices running JamaicaAMS, the IoT Endpoint is not manually declared in system.properties as shown above. Instead, its value must be entered in the file provisioning.properties. The same applies to all properties listed (as seen in the example below).* .. code-block:: text $ cat distribution/src/main/resources/provisioning.properties # Global Device Provisioning Configuration # # This file contains the global configuration of device provisioning. # It is highly recommended to put this file in a restricted environment, e.g., # protect it not accessible to other users on your system, and set restricted # file permissions, e.g., ‘chmod 600 provisioning.properties‘. # aicas EDP authentication server (Keycloak) URL. EDP_AUTH_SERVER="" # aicas EDP web server URL. EDP_PROD_SERVER="" # The realm EDP_REALM="" # The aicas EDP IoT Endpoint EDP_IOT_ENDPOINT="" # The username of the aicas EDP user account with privileges to provision devices EDP_USERNAME="" # The password of the aicas EDP user account EDP_PASSWORD="" After these values are filled into **provisioning.properties** during initial settings, they will be read and automatically transferred to **system.properties** by the provisioning script. *Note that the two steps described below are only to be manually performed for devices not running JamaicaAMS. In which case, all actions related to the generation of device certificates, their storage and the acknowledge of their paths in* **system.properties** *are automatically taken care of during the initial settings*. Moving forward, the **device certificates must be generated and stored**. In the EDP web portal, under the user menu options, access to the Swagger APIs is provided, so that device certificates can be generated. .. figure:: ./image/menu-swagger.png :align: center :alt: menu-swagger Access to the Swagger APIs .. figure:: ./image/swagger-cert.png :align: center :alt: swagger-certificate *Please note that, in case of a failure in the device certificate generation, it may be needed to restart the EDP instance. For more details on how to restart an EDP instance please see the troubleshooting section of the EDP Deployment documentation*. Once the certificate is downloaded as **.p12** file, it should normally be saved in the folder */conf*. **The path to the certificate** also needs to be entered in **system.properties**. Following is a step by step on how to set up the devices to work with EDP. Raspberry Pi is used as an example. Setting up a Raspberry Pi ========================= **Note:** By the automatic provisioning of devices running JamaicaAMS, only the number 1 of the settings described below is needed. The other steps are executed by the provisioning script included in the distribution. For example, as described in step 2, the EDP Client artifacts will be stored in the folder *bundle.3*, to ensure the runtime can automatically install and start them. Also, as instructed in step 4, the keystore file will be stored in folder *jamaicaams>/conf/*. 1. Copy the OSGi-runtime to the Raspberry Pi: This can be done by either using SSH or MicroSD card. 2. Copy the EDP Client to the Raspberry Pi: This can be done by either using SSH or MicroSD card. The EDP Client artifacts should be put in a location such, that the runtime can automatically install and start them. 3. Get a device certificate: A device certificate **.p12** file is required to connect your device to EDP 2.7.0-SNAPSHOT. 4. Copy the device certificate to the Raspberry Pi: You can copy the device certificate either by SSH or MicroSD card. Put the file in a location such, that the runtime has read access. 5. Configure the OSGi runtime: Edit the configuration file of the runtime so that the properties required by the EDP client are properly loaded. In general, the only necessary setting would be **edp.client.keystore=**. 6. Start the OSGi runtime: When the EDP Client runs well, the device shall appear as “online” on the **Runtimes** page of the EDP web portal. Using Apache Felix ================== 1. Download Apache Felix 7.0.5 from *https://felix.apache.org/documentation/downloads.html* and unzip it to the following folders: - felix-framework-7.0.5/bin - felix-framework-7.0.5/bundle - felix-framework-7.0.5/conf - felix-framework-7.0.5/doc 2. Download the EDP Client 3. Copy Apache Felix to the Raspberry Pi: Copy the unzipped folder *felix-framework-7.0.5* to the Raspberry Pi in */home/pi/felix-framework-7.0.5* 4. Copy the EDP Client to the Raspberry Pi: Copy the Client artifacts to */home/pi/felix-framework-7.0.5/bundle* for device provision of Raspberry Pi *Linux armv7-le* 5. Copy the device certificate to the Raspberry Pi, as described above. Supposing you already have a device certificate, for example **es-0001.p12**, you will need to copy this file in */home/pi/felix-framework-7.0.5/conf* and append the following lines in */home/pi/felix-framework-7.0.5/conf/system.properties*: **edp.client.keystore=./conf/es-0001.p12** (if the file **system.properties** does not exist, it needs to be created) 6. Start the connection: A Java runtime is needed to run Apache Felix .. code-block:: bash sudo apt install openjdk-8-jre -y 7. Start Felix .. code-block:: text cd /home/pi/felix-framework-7.0.5 java -jar ./bin/felix.jar 8. When you see a message “Device Shadow Updating”, it means that the Raspberry Pi is connected to EDP. In this example, the runtime *es-0001* shall be listed in the **Runtimes** page of EDP, and its status shall be “online”. Otherwise, please contact **support@aicas.com**. Using JamaicaAMS ================ 1. Download JamaicaAMS: Please contact **info@aicas.com** to request the latest version of JamaicaAMS 2. By unzipping the JamaicaAMS 1.1.1 distribution, you will see the following structure: .. code-block:: text . |-- bundles.optional |-- doc |-- example |-- license ‘-- setup |-- bin |-- bundle.1 |-- bundle.2 |-- bundle.3 |-- conf ‘-- lib 3. Download the EDP Client 4. Copy JamaicaAMS to the Raspberry Pi: The folder *jamaica-ams/setup* contains the OSGi runtime. You need to copy the following folders to the Raspberry Pi in */home/pi/jamaica-ams/*: - bin - bundle.1 - bundle.2 - bundle.3 - conf - lib 5. When JamaicaAMS is deployed, the provisioning script will run and take care of the necessary steps for the connection. Logs will be displayed and clearly inform if the Raspberry Pi was successfully connected to EDP, in which case the device shall appear on the list of the EDP **Runtimes** page. Otherwise, please contact **support@aicas.com** for help. During provisioning, the runtime shows as “online”, but when the provisioning script stops executing, it turns to “offline” since JamaicaAMS no longer runs. However, users can restart JamaicaAMS to connect to EDP with their own auto-start programs. If it is needed to manually start JamaicaAMS, log into the Raspberry Pi and enter: .. code-block:: bash cd /home/pi/jamaica-ams/ ./bin/jams Auto-Connect Raspberry Pi to EDP ================================ Optionally, create a System Daemon Service to start JamaicaAMS when the device boots. As a first step, log into Raspberry Pi and create a file named **jamaica-ams.service** in the folder */home/pi/jamaica-ams/* with the following content: .. code-block:: text [Unit] Description=JamaicaAMS Wants=network-online.target [Service] User=pi WorkingDirectory=/home/pi/jamaica-ams EnvironmentFile=/home/pi/jamaica-ams/conf/environment.properties ExecStart=/home/pi/jamaica-ams/bin/jams Restart=always [Install] WantedBy=multi-user.target Then install the created **jamaica-ams.service** to the Raspberry Pi by typing the following commands: .. code-block:: bash cd /home/pi/jamaica-ams sudo install -m 644 jamaica-ams.service /lib/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable jamaica-ams.service sudo sync JamaicaAMS will start automatically after rebooting the Raspberry Pi. You can start using: .. code-block:: bash sudo systemctl start jamaica-ams.service A runtime **es-0001** shall be listed in the EDP portal, and its status shall be “online”. Additionally, here are some useful commands to control JamaicaAMS: - Start JamaicaAMS service: .. code-block:: bash sudo systemctl start jamaica-ams.service - Stop JamaicaAMS service: .. code-block:: bash sudo systemctl stop jamaica-ams.service - Enable autostart of JamaicaAMS service after device reboot: .. code-block:: bash sudo systemctl enable jamaica-ams.service - Disable autostart of JamaicaAMS service after device reboot: .. code-block:: bash sudo systemctl disable jamaica-ams.service - Get current status of JamaicaAMS service: .. code-block:: bash sudo systemctl status jamaica-ams.service - Get logs of JamaicaAMS service: .. code-block:: bash journalctl -f -u jamaica-ams.service - Remove JamaicaAMS service: .. code-block:: bash sudo systemctl stop jamaica-ams.service sudo systemctl disable jamaica-ams.service sudo rm /lib/systemd/system/jamaica-ams.service sudo systemctl daemon-reload sudo sync *Note that GoGo shell will immediately terminate JamaicaAMS running in the background, since the inputs expected by GoGo shell are not provided in this case. This can be avoided by adding the property “gosh.args=-noninteractive” in conf/system.properties, or using a terminal multiplexer to invoke JamaicaAMS, e.g., “screen -dm ./bin/jams &”*. :doc:`← Previous Page `