Try calling the GET/xsrfToken to get an XSRF token, if the request succeeds a vaild session is already available, it is possible to proceed to step 4.
+
+
It is not necessary to call GET/xsrfToken again until the current session expires, the obtained token is valid as long as the current session is valid.
The device will return a session cookie with the response, make sure to provide it in successive requests. If the request is performed by a browser, this should be done automatically.
If password authentication has been used and the response object reports that a password change is needed, perform the Update password workflow
@@ -3367,7 +3366,7 @@
POST/login/certificate
GET/xsrfToken
REST API path : /services/session/v1/xsrfToken
-
description : Gets the XSRF token associated with the current session.
+
description : Gets the XSRF token associated with the current session. It is not necessary to call this method again until the current session expires, the obtained token is valid as long as the current session is valid.
responses :
200
description : Request succeeded, the XSRF token is returned in response body.
diff --git a/docs-develop/search/search_index.json b/docs-develop/search/search_index.json
index 645ad4c0d5f..fd115e65389 100644
--- a/docs-develop/search/search_index.json
+++ b/docs-develop/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Welcome to the Eclipse Kura\u2122 Documentation The emergence of an Internet of Thing (IoT) service gateway model running modern software stacks, operating on the edge of an IoT deployment as an aggregator and controller, has opened up the possibility of enabling enterprise level technologies to IoT gateways. Advanced software frameworks, which abstract and isolate the developer from the complexity of the hardware and the networking sub-systems, re-define the development and re-usability of integrated hardware and software solutions. Eclipse Kura is an Eclipse IoT project that provides a platform for building IoT gateways. It is a smart application container that enables remote management of such gateways and provides a wide range of APIs for allowing you to write and deploy your own IoT application. Kura runs on top of the Java Virtual Machine (JVM) and leverages OSGi, a dynamic component system for Java, to simplify the process of writing reusable software building blocks. Kura APIs offer easy access to the underlying hardware including serial ports, GPS, watchdog, USB, GPIOs, I2C, etc. It also offer OSGI bundle to simplify the management of network configurations, the communication with IoT servers, and the remote management of the gateway. Kura components are designed as configurable OSGi Declarative Service exposing service API and raising events. While several Kura components are in pure Java, others are invoked through JNI and have a dependency on the Linux operating system. Kura comes with the following services: I/O Services Serial port access through javax.comm 2.0 API or OSGi I/O connection USB access and events through javax.usb, HID API, custom extensions Bluetooth access through javax.bluetooth or OSGi I/O connection Position Service for GPS information from an NMEA stream Clock Service for the synchronization of the system clock Kura API for GPIO/PWM/I2C/SPI access Data Services Store and forward functionality for the telemetry data collected by the gateway and published to remote servers. Policy-driven publishing system, which abstracts the application developer from the complexity of the network layer and the publishing protocol used. Eclipse Paho and its MQTT client provide the default messaging library used. Cloud Services Easy to use API layer for IoT application to communicate with a remote server. In addition to simple publish/subscribe, the Cloud Service API simplifies the implementation of more complex interaction flows like request/response or remote resource management. Allow for a single connection to a remote server to be shared across more than one application in the gateway providing the necessary topic partitioning. Configuration Service Leverage the OSGi specifications ConfigurationAdmin and MetaType to provide a snapshot service to import/export the configuration of all registered services in the container. Remote Management Allow for remote management of the IoT applications installed in Kura including their deployment, upgrade and configuration management. The Remote Management service relies on the Configuration Service and the Cloud Service. Networking Provide API for introspects and configure the network interfaces available in the gateway like Ethernet, Wifi, and Cellular modems. Watchdog Service Register critical components to the Watchdog Service, which will force a system reset through the hardware watchdog when a problem is detected. Web administration interface Offer a web-based management console running within the Kura container to manage the gateway. Drivers and Assets A unified model is introduced to simplify the communication with the devices attached to the gateway. The Driver encapsulates the communication protocol and its configuration parameters, while the Asset, which is generic across Drivers, models the information data channels towards the device. When an Asset is created, a Mirror of the device is automatically available for on-demand read and writes via Java APIs or via Cloud through remote messages. Wires Offers modular and visual data flow programming tool to define data collection and processing pipelines at the edge by simply selecting components from a palette and wiring them together. This way users can, for example, configure an Asset, periodically acquire data from its channels, store them in the gateway, filter or aggregate them using powerful SQL queries, and send the results to the Cloud. The Eclipse Kura Marketplace is a repository from which additional Wires components can be installed into your Kura runtime with a simple drag-and-drop.","title":"Home"},{"location":"#welcome-to-the-eclipse-kuratm-documentation","text":"The emergence of an Internet of Thing (IoT) service gateway model running modern software stacks, operating on the edge of an IoT deployment as an aggregator and controller, has opened up the possibility of enabling enterprise level technologies to IoT gateways. Advanced software frameworks, which abstract and isolate the developer from the complexity of the hardware and the networking sub-systems, re-define the development and re-usability of integrated hardware and software solutions. Eclipse Kura is an Eclipse IoT project that provides a platform for building IoT gateways. It is a smart application container that enables remote management of such gateways and provides a wide range of APIs for allowing you to write and deploy your own IoT application. Kura runs on top of the Java Virtual Machine (JVM) and leverages OSGi, a dynamic component system for Java, to simplify the process of writing reusable software building blocks. Kura APIs offer easy access to the underlying hardware including serial ports, GPS, watchdog, USB, GPIOs, I2C, etc. It also offer OSGI bundle to simplify the management of network configurations, the communication with IoT servers, and the remote management of the gateway. Kura components are designed as configurable OSGi Declarative Service exposing service API and raising events. While several Kura components are in pure Java, others are invoked through JNI and have a dependency on the Linux operating system. Kura comes with the following services: I/O Services Serial port access through javax.comm 2.0 API or OSGi I/O connection USB access and events through javax.usb, HID API, custom extensions Bluetooth access through javax.bluetooth or OSGi I/O connection Position Service for GPS information from an NMEA stream Clock Service for the synchronization of the system clock Kura API for GPIO/PWM/I2C/SPI access Data Services Store and forward functionality for the telemetry data collected by the gateway and published to remote servers. Policy-driven publishing system, which abstracts the application developer from the complexity of the network layer and the publishing protocol used. Eclipse Paho and its MQTT client provide the default messaging library used. Cloud Services Easy to use API layer for IoT application to communicate with a remote server. In addition to simple publish/subscribe, the Cloud Service API simplifies the implementation of more complex interaction flows like request/response or remote resource management. Allow for a single connection to a remote server to be shared across more than one application in the gateway providing the necessary topic partitioning. Configuration Service Leverage the OSGi specifications ConfigurationAdmin and MetaType to provide a snapshot service to import/export the configuration of all registered services in the container. Remote Management Allow for remote management of the IoT applications installed in Kura including their deployment, upgrade and configuration management. The Remote Management service relies on the Configuration Service and the Cloud Service. Networking Provide API for introspects and configure the network interfaces available in the gateway like Ethernet, Wifi, and Cellular modems. Watchdog Service Register critical components to the Watchdog Service, which will force a system reset through the hardware watchdog when a problem is detected. Web administration interface Offer a web-based management console running within the Kura container to manage the gateway. Drivers and Assets A unified model is introduced to simplify the communication with the devices attached to the gateway. The Driver encapsulates the communication protocol and its configuration parameters, while the Asset, which is generic across Drivers, models the information data channels towards the device. When an Asset is created, a Mirror of the device is automatically available for on-demand read and writes via Java APIs or via Cloud through remote messages. Wires Offers modular and visual data flow programming tool to define data collection and processing pipelines at the edge by simply selecting components from a palette and wiring them together. This way users can, for example, configure an Asset, periodically acquire data from its channels, store them in the gateway, filter or aggregate them using powerful SQL queries, and send the results to the Cloud. The Eclipse Kura Marketplace is a repository from which additional Wires components can be installed into your Kura runtime with a simple drag-and-drop.","title":"Welcome to the Eclipse Kura\u2122 Documentation"},{"location":"administration/application-management/","text":"Application Management Package Installation After developing your application and generating a deployment package that contains the bundles to be deployed (refer to the Development section for more information), you may install it on the gateway using the Packages option in the System area of the Kura Gateway Administration Console as shown below. Upon a successful installation, the new component appears in the Services list (shown as the Heater example in these screen captures). Its configuration may be modified according to the defined parameters as shown the Heater display that follows. Eclipse Kura Marketplace Kura allows the installation and update of running applications via the Eclipse Kura Marketplace. The Packages page has, in the top part of the page a section dedicated to the Eclipse Kura Marketplace. Dragging an application reference taken from the Eclipse Kura Marketplace to the specific area of the Kura Web Administrative Console will instruct Kura to download and install the corresponding package, as seen below: Warning If the installation from the Eclipse Marketplace fails, it can be for the lack of the correct certificates. In this case, import the certificate in the SSLKeystore from the Certificate List tab under the Security section. For more details about the procedure see here . If the bundle is an official add-on for Eclipse Kura, the following certificate has to be imported: -----BEGIN CERTIFICATE----- MIIHxzCCBq+gAwIBAgIQCCxCSNb4iszmNPNCflUcGTANBgkqhkiG9w0BAQsFADBP MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMSkwJwYDVQQDEyBE aWdpQ2VydCBUTFMgUlNBIFNIQTI1NiAyMDIwIENBMTAeFw0yMzA5MTEwMDAwMDBa Fw0yNDEwMTEyMzU5NTlaMG8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdPbnRhcmlv MQ8wDQYDVQQHEwZPdHRhd2ExJTAjBgNVBAoTHEVjbGlwc2Uub3JnIEZvdW5kYXRp b24sIEluYy4xFjAUBgNVBAMMDSouZWNsaXBzZS5vcmcwggIiMA0GCSqGSIb3DQEB AQUAA4ICDwAwggIKAoICAQC5hXH2cQoOQlXs5cQ5itZ1Dzct9R+bqr2HaF+imlgo xJ+Vw1ukfQPpSbmSO17A0hLgpSJyVgoPlpOKkg6LGTz8/2qB7DWHdQbg2p0IGQhr dm4oJN2qknnGNl/YYkjz2QJswr1M98raydmq0hqJi0M3q9JSO64O3wOMNduvNG+O rCBol7cbxLr7NNoFxZncZ9giP7QF0XYS6nA8dtIyXU3SARRSPn6y9OX1ttltveck 41ocaU8ORiTF7i89t649XAbtsvxUWM+qVnvlMxpaXqbhnrXMQ/pV2yfdU/qiFQth +RqFgBYoX5roxvmjB14+2qlymn236N4KOGhvfr+Fp8C8Fv6N6wFyKZctXewQ6IsA 3zDvJmF3QaCz6h88lg+IqbRjX5MOjhSkE7XDNKb+xAw5pYzkn9LP+QJLf0iYJw2D Z/X+InVPiZ5UdXyXWypN3q0W5vlz/TmWuVZv76/azZ3anoSPiKh+F3si1xZVEMZQ IkqsgUfq69M4KvHrdi4nGEOfdBHxjos9ul1AsJR57hrhIchsESthUK04e7d2LYOB hHAr0uJNdwFsFD2EBR25ogN83bZ8NaDrrdK2P6sV+hWWK+MY1qRuRub7/fYuR4AU 82toms9p1usjuyMmuIGEpLwk7jZe6XITcbXQEXDA8JKSZrZ/mOA4yTfIGR/gXXB7 wQIDAQABo4IDfTCCA3kwHwYDVR0jBBgwFoAUt2ui6qiqhIx56rTaD5iyxZV2ufQw HQYDVR0OBBYEFO8gL5LNWmSgCqbujR1qH0bUfrIrMCUGA1UdEQQeMByCDSouZWNs aXBzZS5vcmeCC2VjbGlwc2Uub3JnMD4GA1UdIAQ3MDUwMwYGZ4EMAQICMCkwJwYI KwYBBQUHAgEWG2h0dHA6Ly93d3cuZGlnaWNlcnQuY29tL0NQUzAOBgNVHQ8BAf8E BAMCBaAwHQYDVR0lBBYwFAYIKwYBBQUHAwIGCCsGAQUFBwMBMIGPBgNVHR8EgYcw gYQwQKA+oDyGOmh0dHA6Ly9jcmwzLmRpZ2ljZXJ0LmNvbS9EaWdpQ2VydFRMU1JT QVNIQTI1NjIwMjBDQTEtNC5jcmwwQKA+oDyGOmh0dHA6Ly9jcmw0LmRpZ2ljZXJ0 LmNvbS9EaWdpQ2VydFRMU1JTQVNIQTI1NjIwMjBDQTEtNC5jcmwwfwYIKwYBBQUH AQEEczBxMCQGCCsGAQUFBzABhhhodHRwOi8vb2NzcC5kaWdpY2VydC5jb20wSQYI KwYBBQUHMAKGPWh0dHA6Ly9jYWNlcnRzLmRpZ2ljZXJ0LmNvbS9EaWdpQ2VydFRM U1JTQVNIQTI1NjIwMjBDQTEtMS5jcnQwDAYDVR0TAQH/BAIwADCCAX4GCisGAQQB 1nkCBAIEggFuBIIBagFoAHYAdv+IPwq2+5VRwmHM9Ye6NLSkzbsp3GhCCp/mZ0xa OnQAAAGKhcgXYgAABAMARzBFAiEApQsk19PxbsLa452EPaPCXe7SAtpbm5RHnrwj yKAjWx0CICli5A3XAGwmg7IEy4lVA5YBt+mhvlegWkXrKt+oc/CoAHUASLDja9qm RzQP5WoC+p0w6xxSActW3SyB2bu/qznYhHMAAAGKhcgXWQAABAMARjBEAiAvx7lc MyKS6bbnsjbzYOLzJbcS2aAjCzQz4mFiuFA59AIgbt+rpE40/RO0JnFyLP9fsbUf pUj16ZYinOLorqDk9r0AdwDatr9rP7W2Ip+bwrtca+hwkXFsu1GEhTS9pD0wSNf7 qwAAAYqFyBc3AAAEAwBIMEYCIQDCrdQYGYA7BlsT5gXZmkutN15gDQDjlfJBxIRb Z0FAAgIhAIr0eNFvkpec6VJ5pPrNklFt78XP0NjEOJxjrCFTLKVdMA0GCSqGSIb3 DQEBCwUAA4IBAQCvENXlAGP311/gV5rMD2frsK+hlcs/4wjRKUS+nwp3RLTRd3w4 cZLHcsw9qCxeniuHsc/Wa6myr0kKdRc4V6movLq9vMdSjT9dDOZWtZgFaadB0+z2 A/Jsq1/AFFWqWisF64627j/Wf7RwuasxM0dnkAl3m9Hli5xKPgjbovXiH/dCeMvS MTxD1p3ewIYITzV+1Q5FoFuGyIyuh1Kzo7A41xKPe+XfWHqt+hKL8MWkJ9ACD2b0 ZDlD2OaX7K+vI8aWprmwVdpp3deuUoHgBqa1PkHPRmP0bFbamBdB4H6goRX5+DEy cTW2rRm8jFiLm1kf0/iOL7/ddw0yZQAUMthU -----END CERTIFICATE----- that has the following description: Common Name: *.eclipse.org Subject Alternative Names: *.eclipse.org, eclipse.org Organization: Eclipse.org Foundation, Inc. Locality: Ottawa State: Ontario Country: CA Valid From: September 10, 2023 Valid To: October 11, 2024 Issuer: DigiCert TLS RSA SHA256 2020 CA1, DigiCert Inc Write review of DigiCert Key Size: 4096 bit Serial Number: 082c4248d6f88acce634f3427e551c19 If the bundle is not an official one and it is not hosted by Eclipse, retrieve the certificate with this command: openssl s_client -showcerts -connect :443 and import it in the SSLKeystore . Package Signature Once the selected application deployment package (dp) file is installed, it will be listed in the Packages page and detailed with the name of the deployment package, the version and the signature status. The value of the signature field can be true if all the bundles contained in the deployment package are digitally signed, or false if at least one of the bundles is not signed.","title":"Application Management"},{"location":"administration/application-management/#application-management","text":"","title":"Application Management"},{"location":"administration/application-management/#package-installation","text":"After developing your application and generating a deployment package that contains the bundles to be deployed (refer to the Development section for more information), you may install it on the gateway using the Packages option in the System area of the Kura Gateway Administration Console as shown below. Upon a successful installation, the new component appears in the Services list (shown as the Heater example in these screen captures). Its configuration may be modified according to the defined parameters as shown the Heater display that follows.","title":"Package Installation"},{"location":"administration/application-management/#eclipse-kura-marketplace","text":"Kura allows the installation and update of running applications via the Eclipse Kura Marketplace. The Packages page has, in the top part of the page a section dedicated to the Eclipse Kura Marketplace. Dragging an application reference taken from the Eclipse Kura Marketplace to the specific area of the Kura Web Administrative Console will instruct Kura to download and install the corresponding package, as seen below: Warning If the installation from the Eclipse Marketplace fails, it can be for the lack of the correct certificates. In this case, import the certificate in the SSLKeystore from the Certificate List tab under the Security section. For more details about the procedure see here . If the bundle is an official add-on for Eclipse Kura, the following certificate has to be imported: -----BEGIN CERTIFICATE----- MIIHxzCCBq+gAwIBAgIQCCxCSNb4iszmNPNCflUcGTANBgkqhkiG9w0BAQsFADBP MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMSkwJwYDVQQDEyBE aWdpQ2VydCBUTFMgUlNBIFNIQTI1NiAyMDIwIENBMTAeFw0yMzA5MTEwMDAwMDBa Fw0yNDEwMTEyMzU5NTlaMG8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdPbnRhcmlv MQ8wDQYDVQQHEwZPdHRhd2ExJTAjBgNVBAoTHEVjbGlwc2Uub3JnIEZvdW5kYXRp b24sIEluYy4xFjAUBgNVBAMMDSouZWNsaXBzZS5vcmcwggIiMA0GCSqGSIb3DQEB AQUAA4ICDwAwggIKAoICAQC5hXH2cQoOQlXs5cQ5itZ1Dzct9R+bqr2HaF+imlgo xJ+Vw1ukfQPpSbmSO17A0hLgpSJyVgoPlpOKkg6LGTz8/2qB7DWHdQbg2p0IGQhr dm4oJN2qknnGNl/YYkjz2QJswr1M98raydmq0hqJi0M3q9JSO64O3wOMNduvNG+O rCBol7cbxLr7NNoFxZncZ9giP7QF0XYS6nA8dtIyXU3SARRSPn6y9OX1ttltveck 41ocaU8ORiTF7i89t649XAbtsvxUWM+qVnvlMxpaXqbhnrXMQ/pV2yfdU/qiFQth +RqFgBYoX5roxvmjB14+2qlymn236N4KOGhvfr+Fp8C8Fv6N6wFyKZctXewQ6IsA 3zDvJmF3QaCz6h88lg+IqbRjX5MOjhSkE7XDNKb+xAw5pYzkn9LP+QJLf0iYJw2D Z/X+InVPiZ5UdXyXWypN3q0W5vlz/TmWuVZv76/azZ3anoSPiKh+F3si1xZVEMZQ IkqsgUfq69M4KvHrdi4nGEOfdBHxjos9ul1AsJR57hrhIchsESthUK04e7d2LYOB hHAr0uJNdwFsFD2EBR25ogN83bZ8NaDrrdK2P6sV+hWWK+MY1qRuRub7/fYuR4AU 82toms9p1usjuyMmuIGEpLwk7jZe6XITcbXQEXDA8JKSZrZ/mOA4yTfIGR/gXXB7 wQIDAQABo4IDfTCCA3kwHwYDVR0jBBgwFoAUt2ui6qiqhIx56rTaD5iyxZV2ufQw HQYDVR0OBBYEFO8gL5LNWmSgCqbujR1qH0bUfrIrMCUGA1UdEQQeMByCDSouZWNs aXBzZS5vcmeCC2VjbGlwc2Uub3JnMD4GA1UdIAQ3MDUwMwYGZ4EMAQICMCkwJwYI KwYBBQUHAgEWG2h0dHA6Ly93d3cuZGlnaWNlcnQuY29tL0NQUzAOBgNVHQ8BAf8E BAMCBaAwHQYDVR0lBBYwFAYIKwYBBQUHAwIGCCsGAQUFBwMBMIGPBgNVHR8EgYcw gYQwQKA+oDyGOmh0dHA6Ly9jcmwzLmRpZ2ljZXJ0LmNvbS9EaWdpQ2VydFRMU1JT QVNIQTI1NjIwMjBDQTEtNC5jcmwwQKA+oDyGOmh0dHA6Ly9jcmw0LmRpZ2ljZXJ0 LmNvbS9EaWdpQ2VydFRMU1JTQVNIQTI1NjIwMjBDQTEtNC5jcmwwfwYIKwYBBQUH AQEEczBxMCQGCCsGAQUFBzABhhhodHRwOi8vb2NzcC5kaWdpY2VydC5jb20wSQYI KwYBBQUHMAKGPWh0dHA6Ly9jYWNlcnRzLmRpZ2ljZXJ0LmNvbS9EaWdpQ2VydFRM U1JTQVNIQTI1NjIwMjBDQTEtMS5jcnQwDAYDVR0TAQH/BAIwADCCAX4GCisGAQQB 1nkCBAIEggFuBIIBagFoAHYAdv+IPwq2+5VRwmHM9Ye6NLSkzbsp3GhCCp/mZ0xa OnQAAAGKhcgXYgAABAMARzBFAiEApQsk19PxbsLa452EPaPCXe7SAtpbm5RHnrwj yKAjWx0CICli5A3XAGwmg7IEy4lVA5YBt+mhvlegWkXrKt+oc/CoAHUASLDja9qm RzQP5WoC+p0w6xxSActW3SyB2bu/qznYhHMAAAGKhcgXWQAABAMARjBEAiAvx7lc MyKS6bbnsjbzYOLzJbcS2aAjCzQz4mFiuFA59AIgbt+rpE40/RO0JnFyLP9fsbUf pUj16ZYinOLorqDk9r0AdwDatr9rP7W2Ip+bwrtca+hwkXFsu1GEhTS9pD0wSNf7 qwAAAYqFyBc3AAAEAwBIMEYCIQDCrdQYGYA7BlsT5gXZmkutN15gDQDjlfJBxIRb Z0FAAgIhAIr0eNFvkpec6VJ5pPrNklFt78XP0NjEOJxjrCFTLKVdMA0GCSqGSIb3 DQEBCwUAA4IBAQCvENXlAGP311/gV5rMD2frsK+hlcs/4wjRKUS+nwp3RLTRd3w4 cZLHcsw9qCxeniuHsc/Wa6myr0kKdRc4V6movLq9vMdSjT9dDOZWtZgFaadB0+z2 A/Jsq1/AFFWqWisF64627j/Wf7RwuasxM0dnkAl3m9Hli5xKPgjbovXiH/dCeMvS MTxD1p3ewIYITzV+1Q5FoFuGyIyuh1Kzo7A41xKPe+XfWHqt+hKL8MWkJ9ACD2b0 ZDlD2OaX7K+vI8aWprmwVdpp3deuUoHgBqa1PkHPRmP0bFbamBdB4H6goRX5+DEy cTW2rRm8jFiLm1kf0/iOL7/ddw0yZQAUMthU -----END CERTIFICATE----- that has the following description: Common Name: *.eclipse.org Subject Alternative Names: *.eclipse.org, eclipse.org Organization: Eclipse.org Foundation, Inc. Locality: Ottawa State: Ontario Country: CA Valid From: September 10, 2023 Valid To: October 11, 2024 Issuer: DigiCert TLS RSA SHA256 2020 CA1, DigiCert Inc Write review of DigiCert Key Size: 4096 bit Serial Number: 082c4248d6f88acce634f3427e551c19 If the bundle is not an official one and it is not hosted by Eclipse, retrieve the certificate with this command: openssl s_client -showcerts -connect :443 and import it in the SSLKeystore .","title":"Eclipse Kura Marketplace"},{"location":"administration/application-management/#package-signature","text":"Once the selected application deployment package (dp) file is installed, it will be listed in the Packages page and detailed with the name of the deployment package, the version and the signature status. The value of the signature field can be true if all the bundles contained in the deployment package are digitally signed, or false if at least one of the bundles is not signed.","title":"Package Signature"},{"location":"administration/directory-layout/","text":"Directory Layout This section describes the default Kura directory layout that is created upon installation. The default installation directory is as follows: /opt/eclipse The kura sub-directory is a logical link on the actual Kura release directory: kura -> /opt/eclipse/kura_3.0.0_raspberry-pi-2 kura_3.0.0_raspberry-pi-2 Kura File Structure The idea behind the Kura file and folder structure is to separate user and framework configuration files, that is files that can be modified by the user to customize Kura behavior and files that are used by Kura to persist configurations. Moreover, some files are generated at runtime by Kura (i.e. database) and they are kept in specific folders. The user , console , log4j and packages directories contain files that can be modified by the user (i.e. the configuration for the logging or custom Kura properties). The framework folder keeps the configuration files used by Kura and that shouldn't be modified by the user. The data directory is used to persist files that are generated by Kura. Finally, the plugins folder contains all the jar files needed by Kura. All of the Kura files are located within /opt/eclipse/kura folder using the structure shown in the following table: Directory Description bin Scripts that start Kura. console This folder contains files that are used to customise the Kura Web UI appearance. data Data files generated by the Kura runtime. data/persistance Embedded Database files. packages Deployment package files that are not part of the standard Kura framework, but are installed at a later time. framework Configuration data for Kura framework. The user shouldn't directly modify these files. log Log file from the latest Kura installation. log4j Logger framework configuration plugins All of the libraries and Kura specific jar files needed for the framework execution. user Configuration files generated by the user or by Kura at runtime. These files can be modified by the user to customise the Kura behavior. user/snapshots XML snapshot files; up to 10 successive configurations including the original. user/security Files used by Kura to configure security. .data Backup files needed to restore factory configuration Log Files Kura regularly updates two log files in the /var/log directory: /var/log/kura-console.log - stores the standard console output of the application. This log file contains the eventual errors that are thrown upon Kura startup. /var/log/kura.log - stores all of the logging information from Kura bundles. The logger levels are defined in the log4j.xml configuration file as shown below: /opt/eclpse/kura/user/log4j.xml The default logger level in this file is set to INFO. This level may be modified for the whole application or for a specific package as shown in the following example: In this example, the logger level is set to DEBUG only for the net.admin bundle. Additionally, more specific, properties may be defined as required for your particular logging needs. The logger levels are hierarchical, so that those in a deeper level of the hierarchy will apply; otherwise, the more general logger level will override them. Once the logger levels are modified as needed and the log4j.xml configuration file is saved, Kura automatically loads the new configuration. By default Kura checks the file every 30 seconds.","title":"Directory Layout"},{"location":"administration/directory-layout/#directory-layout","text":"This section describes the default Kura directory layout that is created upon installation. The default installation directory is as follows: /opt/eclipse The kura sub-directory is a logical link on the actual Kura release directory: kura -> /opt/eclipse/kura_3.0.0_raspberry-pi-2 kura_3.0.0_raspberry-pi-2","title":"Directory Layout"},{"location":"administration/directory-layout/#kura-file-structure","text":"The idea behind the Kura file and folder structure is to separate user and framework configuration files, that is files that can be modified by the user to customize Kura behavior and files that are used by Kura to persist configurations. Moreover, some files are generated at runtime by Kura (i.e. database) and they are kept in specific folders. The user , console , log4j and packages directories contain files that can be modified by the user (i.e. the configuration for the logging or custom Kura properties). The framework folder keeps the configuration files used by Kura and that shouldn't be modified by the user. The data directory is used to persist files that are generated by Kura. Finally, the plugins folder contains all the jar files needed by Kura. All of the Kura files are located within /opt/eclipse/kura folder using the structure shown in the following table: Directory Description bin Scripts that start Kura. console This folder contains files that are used to customise the Kura Web UI appearance. data Data files generated by the Kura runtime. data/persistance Embedded Database files. packages Deployment package files that are not part of the standard Kura framework, but are installed at a later time. framework Configuration data for Kura framework. The user shouldn't directly modify these files. log Log file from the latest Kura installation. log4j Logger framework configuration plugins All of the libraries and Kura specific jar files needed for the framework execution. user Configuration files generated by the user or by Kura at runtime. These files can be modified by the user to customise the Kura behavior. user/snapshots XML snapshot files; up to 10 successive configurations including the original. user/security Files used by Kura to configure security. .data Backup files needed to restore factory configuration","title":"Kura File Structure"},{"location":"administration/directory-layout/#log-files","text":"Kura regularly updates two log files in the /var/log directory: /var/log/kura-console.log - stores the standard console output of the application. This log file contains the eventual errors that are thrown upon Kura startup. /var/log/kura.log - stores all of the logging information from Kura bundles. The logger levels are defined in the log4j.xml configuration file as shown below: /opt/eclpse/kura/user/log4j.xml The default logger level in this file is set to INFO. This level may be modified for the whole application or for a specific package as shown in the following example: In this example, the logger level is set to DEBUG only for the net.admin bundle. Additionally, more specific, properties may be defined as required for your particular logging needs. The logger levels are hierarchical, so that those in a deeper level of the hierarchy will apply; otherwise, the more general logger level will override them. Once the logger levels are modified as needed and the log4j.xml configuration file is saved, Kura automatically loads the new configuration. By default Kura checks the file every 30 seconds.","title":"Log Files"},{"location":"administration/remote-management-kapua/","text":"Remote Management with Eclipse Kapua Built-in Services Management This section describes the remote management of devices running Kura via Eclipse Kapua Console. The Eclipse Kapua Web Console provides the administration tools used for the management of the built-in services exposed by Kura. To remotely manage a device running Kura through the Eclipse Kapua Web Console, select the desired device from the Devices Table of the console and open the Configuration tab as shown in the screen capture below. Please refer to the Built-in Services section for a description of the available Services and their configuration parameters. Installation of a New Application As described in Application Management , a new application embedded in a deployment package can be deployed and configured using Eclipse Kapua Console. To do so, select a connected device and click on the Packages tab. Then, click on Install/Upgrade . The Install New Package window opens allowing the deployment package to be installed from an URL as shown in the screen capture below. Once installed, the new application parameters may be modified in the same way as the Built-in Services. Click on the Configuration tab to see the service that corresponds to your application. Snapshots As described in Snapshot Management , the overall Kura configuration, including the new installed applications, is stored in a snapshot xml file. The Eclipse Kapua Console also provides options to Download , Upload and Apply , or Rollback snapshots as shown in the screen capture below. Remote Command Execution from Eclipse Kapua Web Console The Eclipse Kapua Console provides the ability to run system commands directly on the device. Refer to Command Service for details on how to configure this service in Kura. It is also possible to send a script to execute using the File option of the Command tab in Eclipse Kapua Console as shown in the screen capture below. This script must be compressed into a zip file with the eventual associated resource files. Once the file is selected, click Execute . The zip file is sent embedded in an MQTT message on the device. The Command Service in the device stores the file in /tmp, unzips it, and tries to execute a shell script if one is present. Note that in this case, the Execute parameter cannot be empty; a simple command, such as \"ls -l /tmp\", may be entered.","title":"Remote Management with Eclipse Kapua"},{"location":"administration/remote-management-kapua/#remote-management-with-eclipse-kapua","text":"","title":"Remote Management with Eclipse Kapua"},{"location":"administration/remote-management-kapua/#built-in-services-management","text":"This section describes the remote management of devices running Kura via Eclipse Kapua Console. The Eclipse Kapua Web Console provides the administration tools used for the management of the built-in services exposed by Kura. To remotely manage a device running Kura through the Eclipse Kapua Web Console, select the desired device from the Devices Table of the console and open the Configuration tab as shown in the screen capture below. Please refer to the Built-in Services section for a description of the available Services and their configuration parameters.","title":"Built-in Services Management"},{"location":"administration/remote-management-kapua/#installation-of-a-new-application","text":"As described in Application Management , a new application embedded in a deployment package can be deployed and configured using Eclipse Kapua Console. To do so, select a connected device and click on the Packages tab. Then, click on Install/Upgrade . The Install New Package window opens allowing the deployment package to be installed from an URL as shown in the screen capture below. Once installed, the new application parameters may be modified in the same way as the Built-in Services. Click on the Configuration tab to see the service that corresponds to your application.","title":"Installation of a New Application"},{"location":"administration/remote-management-kapua/#snapshots","text":"As described in Snapshot Management , the overall Kura configuration, including the new installed applications, is stored in a snapshot xml file. The Eclipse Kapua Console also provides options to Download , Upload and Apply , or Rollback snapshots as shown in the screen capture below.","title":"Snapshots"},{"location":"administration/remote-management-kapua/#remote-command-execution-from-eclipse-kapua-web-console","text":"The Eclipse Kapua Console provides the ability to run system commands directly on the device. Refer to Command Service for details on how to configure this service in Kura. It is also possible to send a script to execute using the File option of the Command tab in Eclipse Kapua Console as shown in the screen capture below. This script must be compressed into a zip file with the eventual associated resource files. Once the file is selected, click Execute . The zip file is sent embedded in an MQTT message on the device. The Command Service in the device stores the file in /tmp, unzips it, and tries to execute a shell script if one is present. Note that in this case, the Execute parameter cannot be empty; a simple command, such as \"ls -l /tmp\", may be entered.","title":"Remote Command Execution from Eclipse Kapua Web Console"},{"location":"administration/snapshot-management/","text":"Snapshot Management The overall configuration of Kura is stored in an XML file called a snapshot. This file includes all of the parameters for every service running in Kura. The original configuration file is named snapshot_0.xml . This section describes how snapshots may be used. Each time a configuration change is made to one of the Kura components, a new XML file is created using the naming convention snapshot_[time as a long integer].xml . The nine most recent snapshots are saved, as well as the original snapshot 0. How to Access Snapshots To display snapshots using the Gateway Administration Console , select Settings from the System area, and then click on the Snapshots tab. The following three operations are available: Download , Upload and Apply , and Rollback . How to Use Snapshots Download The Download option provides the ability to save a snapshot file onto your computer. This file may then be edited, uploaded back to the device, or transferred to another equivalent device. Starting from Kura 5.1, the snapshot can be downloaded in two formats: XML : The original XML snapshot format. JSON : The JSON format used by the Configuration v2 REST APIs and CONF-V2 request handler . For example the downloaded snapshot can be used as is as a body for the PUT/configurableComponents/configurations/_update request. The takeSnapshot parameter specified by the CONF-V2 request is missing from the downloaded JSON file, if that parameter is not specified, a new snapshot will be created by default. Pressing the Download button will trigger a dialog that allows choosing the desired format. Upload and Apply The Upload and Apply option provides the ability to import an XML file from your computer and upload it onto the device. This function updates every service in Kura with the parameters defined in the XML file. Warning Carefully select the file to be uploaded. An incorrect file may crash Kura and make it unresponsive. Rollback The Rollback option provides the ability to restore the system to a previous configuration.","title":"Snapshot Management"},{"location":"administration/snapshot-management/#snapshot-management","text":"The overall configuration of Kura is stored in an XML file called a snapshot. This file includes all of the parameters for every service running in Kura. The original configuration file is named snapshot_0.xml . This section describes how snapshots may be used. Each time a configuration change is made to one of the Kura components, a new XML file is created using the naming convention snapshot_[time as a long integer].xml . The nine most recent snapshots are saved, as well as the original snapshot 0.","title":"Snapshot Management"},{"location":"administration/snapshot-management/#how-to-access-snapshots","text":"To display snapshots using the Gateway Administration Console , select Settings from the System area, and then click on the Snapshots tab. The following three operations are available: Download , Upload and Apply , and Rollback .","title":"How to Access Snapshots"},{"location":"administration/snapshot-management/#how-to-use-snapshots","text":"","title":"How to Use Snapshots"},{"location":"administration/snapshot-management/#download","text":"The Download option provides the ability to save a snapshot file onto your computer. This file may then be edited, uploaded back to the device, or transferred to another equivalent device. Starting from Kura 5.1, the snapshot can be downloaded in two formats: XML : The original XML snapshot format. JSON : The JSON format used by the Configuration v2 REST APIs and CONF-V2 request handler . For example the downloaded snapshot can be used as is as a body for the PUT/configurableComponents/configurations/_update request. The takeSnapshot parameter specified by the CONF-V2 request is missing from the downloaded JSON file, if that parameter is not specified, a new snapshot will be created by default. Pressing the Download button will trigger a dialog that allows choosing the desired format.","title":"Download"},{"location":"administration/snapshot-management/#upload-and-apply","text":"The Upload and Apply option provides the ability to import an XML file from your computer and upload it onto the device. This function updates every service in Kura with the parameters defined in the XML file. Warning Carefully select the file to be uploaded. An incorrect file may crash Kura and make it unresponsive.","title":"Upload and Apply"},{"location":"administration/snapshot-management/#rollback","text":"The Rollback option provides the ability to restore the system to a previous configuration.","title":"Rollback"},{"location":"administration/system-component-inventory/","text":"The Framework has the capability to report locally and to the associated cloud platform the list of currently installed components and their associated properties. This feature allows, locally and remotely, the system administrator to know which components are installed into the target device and the associated versions. The feature is particularly important for a system administrator because allows to identify vulnerable components and allows immediate actions in response. From the local Kura Web UI, the list of system components is available in the System Packages tab of the Device section. Once selected, the user will get the list of all the system installed components. The component's inventory list is available also via REST APIs and, with the same contract, from the cloud. The Mqtt contract defined for this component is available here","title":"System Component Inventory"},{"location":"cloud-api/app-dev-guide/","text":"Application developer guide This guide will provide information on how an application developer can leverage the new Generic Cloud Services APIs, in order to be able to properly use the CloudPublisher/CloudSubscriber API, publish a message, being notified of message delivery and of connection status changes. The Kura ExamplePublisher will be used as a reference. The application should bind itself to a CloudPublisher or CloudSubscriber instance, this can be done in different ways, such as using OSGi ServiceTracker s or by leveraging the Declarative Service layer. The recommended way to perform this operation is choosing the latter and allowing the user to customize the service references through component configuration. If the component metatype and definition are structured as described below, the Kura Web UI will show a dedicated widget in component configuration that helps the user to pick compatible CloudPublisher or CloudSubscriber instances. Write component definition The first step involves declaring the Publisher or Subscriber references in component definition: The snipped above shows the definition of Kura ExamplePublisher, this component is capable of sending and receiving messages, and therefore defines two references, the first to a CloudPublisher and the second to a CloudSubscriber . In order to allow the user to customize the bindings at runtime, the target attribute of the references should not be specified at this point in component definition, as it will be set by the Web UI. Reference cardinality should be use the 0..1 or 0..n form, as it is not guaranteed that the references will point to a valid service instance during all the lifetime of the application component. For example, references can not be bound if the application has not been configured by the user yet or if the target service is missing. Create component metatype Application metatype should declare an AD for each Publisher/Subscriber reference declared in component definition: It is important to respect the following rules for some of the AD attributes: id This attribute must have the following form: .target where should match the value of the name attribute of the corresponding reference in component definition. required must be set to true default must not be empty and must be a valid OSGi filter. The Web UI will renderer a dedicated widget for picking CloudPublisher and CloudSubscriber instances: Write the bind/unbind methods in applicaiton code The last step involves defining some bind...() / unbind...() methods with a name that matches the values of the bind / unbind attributes of the references in component definition. public void setCloudPublisher ( CloudPublisher cloudPublisher ) { ... } public void unsetCloudPublisher ( CloudPublisher cloudPublisher ) { ... } public void setCloudSubscriber ( CloudSubscriber cloudSubscriber ) { ... } public void unsetCloudSubscriber ( CloudSubscriber cloudSubscriber ) { ... } As stated above, since reference cardinality is declared as 0.. , the application must be prepared to handle the cases where references are not satisfied, and therefore CloudPublisher and CloudSubscriber instances are not available. Publish a message If a CloudPublisher instance is bound, the application can publish messages using its publish() method: if ( nonNull ( this . cloudPublisher )) { KuraMessage message = new KuraMessage ( payload ); String messageId = this . cloudPublisher . publish ( message ); } Receiving messages using a CloudSubscriber In order to receive messages from a CloudSubscriber , the application must implement and attach a CloudSubscriberListener to it. This can be done for example during CloudSubscriber binding: public class ExamplePublisher implements CloudSubscriberListener , ... { ... public void setCloudSubscriber ( CloudSubscriber cloudSubscriber ) { this . cloudSubscriber = cloudSubscriber ; this . cloudSubscriber . registerCloudSubscriberListener ( ExamplePublisher . this ); ... } public void unsetCloudSubscriber ( CloudSubscriber cloudSubscriber ) { this . cloudSubscriber . unregisterCloudSubscriberListener ( ExamplePublisher . this ); ... this . cloudSubscriber = null ; } ... @Override public void onMessageArrived ( KuraMessage message ) { logReceivedMessage ( message ); } ... } The CloudSubscriber will invoke the onMessageArrived() method when new messages are received. Receiving connection state notifications If an application is interested in cloud connection status change events (connected, disconnected, etc), it can implement and attach a CloudConnectionListener to a CloudPublisher or CloudSubscriber instance. public class ExamplePublisher implements CloudConnectionListener , ... { ... public void setCloudPublisher ( CloudPublisher cloudPublisher ) { this . cloudPublisher = cloudPublisher ; this . cloudPublisher . registerCloudConnectionListener ( ExamplePublisher . this ); ... } public void unsetCloudPublisher ( CloudPublisher cloudPublisher ) { this . cloudPublisher . unregisterCloudConnectionListener ( ExamplePublisher . this ); ... this . cloudPublisher = null ; } public void setCloudSubscriber ( CloudSubscriber cloudSubscriber ) { this . cloudSubscriber = cloudSubscriber ; ... this . cloudSubscriber . registerCloudConnectionListener ( ExamplePublisher . this ); } public void unsetCloudSubscriber ( CloudSubscriber cloudSubscriber ) { ... this . cloudSubscriber . unregisterCloudConnectionListener ( ExamplePublisher . this ); this . cloudSubscriber = null ; } ... @Override public void onConnectionEstablished () { logger . info ( \"Connection established\" ); } @Override public void onConnectionLost () { logger . warn ( \"Connection lost!\" ); } @Override public void onDisconnected () { logger . warn ( \"On disconnected\" ); } ... } Receiving message delivery notifications If an application is interested in message confirmation events and the underlying cloud connection supports it, it can implement and attach a CloudDeliveryListener to a CloudPublisher instance. public class ExamplePublisher implements CloudDeliveryListener , ... { ... public void setCloudPublisher ( CloudPublisher cloudPublisher ) { this . cloudPublisher = cloudPublisher ; ... this . cloudPublisher . registerCloudDeliveryListener ( ExamplePublisher . this ); } public void unsetCloudPublisher ( CloudPublisher cloudPublisher ) { ... this . cloudPublisher . registerCloudDeliveryListener ( ExamplePublisher . this ); this . cloudPublisher = null ; } ... @Override public void onMessageConfirmed ( String messageId ) { logger . info ( \"Confirmed message with id: {}\" , messageId ); } ... } The CloudSubscriber will invoke the onMessageConfirmed() method when a published message is confirmed. In order to determine which message has been confirmed, the provided messageId can be compared with the id returned by the publish() call that published the message. Please note that if the underlying cloud connection is not able to provide message confirmation for the published message, the id returned by publish() will be null .","title":"Application Developer Guide"},{"location":"cloud-api/app-dev-guide/#application-developer-guide","text":"This guide will provide information on how an application developer can leverage the new Generic Cloud Services APIs, in order to be able to properly use the CloudPublisher/CloudSubscriber API, publish a message, being notified of message delivery and of connection status changes. The Kura ExamplePublisher will be used as a reference. The application should bind itself to a CloudPublisher or CloudSubscriber instance, this can be done in different ways, such as using OSGi ServiceTracker s or by leveraging the Declarative Service layer. The recommended way to perform this operation is choosing the latter and allowing the user to customize the service references through component configuration. If the component metatype and definition are structured as described below, the Kura Web UI will show a dedicated widget in component configuration that helps the user to pick compatible CloudPublisher or CloudSubscriber instances. Write component definition The first step involves declaring the Publisher or Subscriber references in component definition: The snipped above shows the definition of Kura ExamplePublisher, this component is capable of sending and receiving messages, and therefore defines two references, the first to a CloudPublisher and the second to a CloudSubscriber . In order to allow the user to customize the bindings at runtime, the target attribute of the references should not be specified at this point in component definition, as it will be set by the Web UI. Reference cardinality should be use the 0..1 or 0..n form, as it is not guaranteed that the references will point to a valid service instance during all the lifetime of the application component. For example, references can not be bound if the application has not been configured by the user yet or if the target service is missing. Create component metatype Application metatype should declare an AD for each Publisher/Subscriber reference declared in component definition: It is important to respect the following rules for some of the AD attributes: id This attribute must have the following form: .target where should match the value of the name attribute of the corresponding reference in component definition. required must be set to true default must not be empty and must be a valid OSGi filter. The Web UI will renderer a dedicated widget for picking CloudPublisher and CloudSubscriber instances: Write the bind/unbind methods in applicaiton code The last step involves defining some bind...() / unbind...() methods with a name that matches the values of the bind / unbind attributes of the references in component definition. public void setCloudPublisher ( CloudPublisher cloudPublisher ) { ... } public void unsetCloudPublisher ( CloudPublisher cloudPublisher ) { ... } public void setCloudSubscriber ( CloudSubscriber cloudSubscriber ) { ... } public void unsetCloudSubscriber ( CloudSubscriber cloudSubscriber ) { ... } As stated above, since reference cardinality is declared as 0.. , the application must be prepared to handle the cases where references are not satisfied, and therefore CloudPublisher and CloudSubscriber instances are not available. Publish a message If a CloudPublisher instance is bound, the application can publish messages using its publish() method: if ( nonNull ( this . cloudPublisher )) { KuraMessage message = new KuraMessage ( payload ); String messageId = this . cloudPublisher . publish ( message ); } Receiving messages using a CloudSubscriber In order to receive messages from a CloudSubscriber , the application must implement and attach a CloudSubscriberListener to it. This can be done for example during CloudSubscriber binding: public class ExamplePublisher implements CloudSubscriberListener , ... { ... public void setCloudSubscriber ( CloudSubscriber cloudSubscriber ) { this . cloudSubscriber = cloudSubscriber ; this . cloudSubscriber . registerCloudSubscriberListener ( ExamplePublisher . this ); ... } public void unsetCloudSubscriber ( CloudSubscriber cloudSubscriber ) { this . cloudSubscriber . unregisterCloudSubscriberListener ( ExamplePublisher . this ); ... this . cloudSubscriber = null ; } ... @Override public void onMessageArrived ( KuraMessage message ) { logReceivedMessage ( message ); } ... } The CloudSubscriber will invoke the onMessageArrived() method when new messages are received. Receiving connection state notifications If an application is interested in cloud connection status change events (connected, disconnected, etc), it can implement and attach a CloudConnectionListener to a CloudPublisher or CloudSubscriber instance. public class ExamplePublisher implements CloudConnectionListener , ... { ... public void setCloudPublisher ( CloudPublisher cloudPublisher ) { this . cloudPublisher = cloudPublisher ; this . cloudPublisher . registerCloudConnectionListener ( ExamplePublisher . this ); ... } public void unsetCloudPublisher ( CloudPublisher cloudPublisher ) { this . cloudPublisher . unregisterCloudConnectionListener ( ExamplePublisher . this ); ... this . cloudPublisher = null ; } public void setCloudSubscriber ( CloudSubscriber cloudSubscriber ) { this . cloudSubscriber = cloudSubscriber ; ... this . cloudSubscriber . registerCloudConnectionListener ( ExamplePublisher . this ); } public void unsetCloudSubscriber ( CloudSubscriber cloudSubscriber ) { ... this . cloudSubscriber . unregisterCloudConnectionListener ( ExamplePublisher . this ); this . cloudSubscriber = null ; } ... @Override public void onConnectionEstablished () { logger . info ( \"Connection established\" ); } @Override public void onConnectionLost () { logger . warn ( \"Connection lost!\" ); } @Override public void onDisconnected () { logger . warn ( \"On disconnected\" ); } ... } Receiving message delivery notifications If an application is interested in message confirmation events and the underlying cloud connection supports it, it can implement and attach a CloudDeliveryListener to a CloudPublisher instance. public class ExamplePublisher implements CloudDeliveryListener , ... { ... public void setCloudPublisher ( CloudPublisher cloudPublisher ) { this . cloudPublisher = cloudPublisher ; ... this . cloudPublisher . registerCloudDeliveryListener ( ExamplePublisher . this ); } public void unsetCloudPublisher ( CloudPublisher cloudPublisher ) { ... this . cloudPublisher . registerCloudDeliveryListener ( ExamplePublisher . this ); this . cloudPublisher = null ; } ... @Override public void onMessageConfirmed ( String messageId ) { logger . info ( \"Confirmed message with id: {}\" , messageId ); } ... } The CloudSubscriber will invoke the onMessageConfirmed() method when a published message is confirmed. In order to determine which message has been confirmed, the provided messageId can be compared with the id returned by the publish() call that published the message. Please note that if the underlying cloud connection is not able to provide message confirmation for the published message, the id returned by publish() will be null .","title":"Application developer guide"},{"location":"cloud-api/built-in-cloud/","text":"Built-in Cloud Services Eclipse Kura provides by default a set of services used to connect to a cloud platform. The following sections describe the services and how to configure them. The CloudService API is deprecated since Kura 4.0. The functionalities provided by CloudService are now provided by the CloudEndpoint and CloudConnectionManager service interfaces. See the section describing the Kura 4.0 cloud connection model for more details. The DataService and MqttDataTrasport APIs are not deprecated in Kura 4.0. CloudService The CloudService provides an easy-to-use API layer for the M2M application to communicate with a remote server. It operates as a decorator for the DataService, providing add-on features over the management of the transport layer. In addition to simple publish/subscribe, the CloudService API simplifies the implementation of more complex interaction flows like request/response or remote resource management. The CloudService abstracts the developers from the complexity of the transport protocol and payload format used in the communication. The CloudService allows a single connection to a remote server to be shared across more than one application in the gateway providing the necessary topic partitioning. Its functions include: Adds application topic prefixes to allow for a single remote server connection to be shared across applications. Defines a payload data model and provides default encoding/decoding serializers. Publishes life-cycle messages when the device and applications start and stop. To use this service, select the CloudServices option located in the System area and select the CloudService tab as shown in the screen capture below. The CloudService provides the following configuration parameters: device.display-name - defines the device display name given by the system. (Required field.) device.custom-name - defines the custom device display name if the device.display-name parameter is set to \"Custom\". topic.control-prefix - defines the topic prefix for system messages. encode.gzip - defines if the message payloads are sent compressed. republish.mqtt.birth.cert.on.gps.lock - when set to true, forces a republish of the MQTT Birth Certificate when a GPS correct position lock is received. The device is then registered with its real coordinates. (Required field.) republish.mqtt.birth.cert.on.modem.detect - when set to true, forces a republish of the MQTT Birth Certificate when the service receives a modem detection event. (Required field.) enable.default.subscriptions - when set to true, the gateway will not be remotely manageable. payload.encoding - Specify the message payload encoding. The possible options are Kura Protobuf and Simple JSON . The default CloudService implementations publishes the following lifecycle messages : BIRTH message : sent immediately when device is connected to the cloud platform. The BIRTH message is published with priority 0 and QoS 1; DISCONNECT message : sent immediately before device is disconnected from the cloud platform. The DISCONNECT message is published with priority 0 and QoS 0; delayed BIRTH message : sent when new cloud application handler becomes available, a DP is installed or removed, GPS position is locked (can be disabled), or when modem status changes (can be disabled). These messages are cached for 30 seconds before sending. If no other message of such type arrives the message is sent; otherwise the BIRTH is cached and the timeout restarts. This is to avoid sending multiple messages when the framework starts. The message is published with priority 0 and QoS 1; MqttDataTransport The MqttDataTransport service provides the ability to connect to a remote broker, publish messages, subscribe to topics, receive messages on the subscribed topics, and disconnect from the remote message broker. To use this service, select the MqttDataTransport option located in the System area and select the CloudService tab as shown in the screen capture below. The MqttDataTransport service provides the following configuration parameters: broker-url - defines the URL of the MQTT broker to connect to. (Required field.) topic.context.account-name - defines the name of the account to which the device belongs. username and password - define the username and password that have been assigned to the device by the account administrator (generally username is account-name_broker). (Required field.) client-id - defines the identifier of the MQTT client representing the device when connecting to the MQTT broker. If left empty, it is automatically determined by the client software as the MAC address of the main network interface (in general numbers and uppercase letters without ':'). This identifier has to be unique within your account. keep-alive - defines the \"keep alive\" interval measured in seconds. It specifies the maximum amount of time that should pass without communication between the client and the server. The client will ensure that at least one message travels across the network within each keep alive period. In the absence of a data-related message during this time period, the client will send a very small MQTT \"ping\" message that the server will acknowledge. The keep alive interval enables the client to detect when the server is no longer available without having to wait for the long TCP/IP timeout. (Required field.) timeout - sets the timeout used for all interactions with the MQTT broker. (Required field.) clean-session - controls the behavior of both the client and the server at the time of connect and disconnect. When this parameter is set to true, the state information is discarded at connect and disconnect; when set to false, the state information is maintained. (Required field.) lwt parameters - define the MQTT \"Last Will and Testament\" (LWT) settings for the client. In the event that the client unexpectedly loses its connection to the server, the server publishes the LWT message (lwt.payload) to the LWT topic on behalf of the client. This allows other clients (subscribed to the LWT topic) to be made aware that the client has disconnected. LWT parameters that may be configured include: lwt.topic lwt.payload lwt.qos lwt.retain in-flight.persistence - defines the storage type where in-flight messages are persisted across reconnections. They may be stored in memory, or in a file on the disk. (Required field.) protocol-version - defines the MQTT Protocol version to be used. This value may be 3.1 or 3.1.1. ssl parameters - defines the SSL configuration. SSL parameters that may be configured include: ssl.hostname.verification ssl.default.cipherSuites ssl.certificate.alias","title":"Built-in Cloud Services"},{"location":"cloud-api/built-in-cloud/#built-in-cloud-services","text":"Eclipse Kura provides by default a set of services used to connect to a cloud platform. The following sections describe the services and how to configure them. The CloudService API is deprecated since Kura 4.0. The functionalities provided by CloudService are now provided by the CloudEndpoint and CloudConnectionManager service interfaces. See the section describing the Kura 4.0 cloud connection model for more details. The DataService and MqttDataTrasport APIs are not deprecated in Kura 4.0.","title":"Built-in Cloud Services"},{"location":"cloud-api/built-in-cloud/#cloudservice","text":"The CloudService provides an easy-to-use API layer for the M2M application to communicate with a remote server. It operates as a decorator for the DataService, providing add-on features over the management of the transport layer. In addition to simple publish/subscribe, the CloudService API simplifies the implementation of more complex interaction flows like request/response or remote resource management. The CloudService abstracts the developers from the complexity of the transport protocol and payload format used in the communication. The CloudService allows a single connection to a remote server to be shared across more than one application in the gateway providing the necessary topic partitioning. Its functions include: Adds application topic prefixes to allow for a single remote server connection to be shared across applications. Defines a payload data model and provides default encoding/decoding serializers. Publishes life-cycle messages when the device and applications start and stop. To use this service, select the CloudServices option located in the System area and select the CloudService tab as shown in the screen capture below. The CloudService provides the following configuration parameters: device.display-name - defines the device display name given by the system. (Required field.) device.custom-name - defines the custom device display name if the device.display-name parameter is set to \"Custom\". topic.control-prefix - defines the topic prefix for system messages. encode.gzip - defines if the message payloads are sent compressed. republish.mqtt.birth.cert.on.gps.lock - when set to true, forces a republish of the MQTT Birth Certificate when a GPS correct position lock is received. The device is then registered with its real coordinates. (Required field.) republish.mqtt.birth.cert.on.modem.detect - when set to true, forces a republish of the MQTT Birth Certificate when the service receives a modem detection event. (Required field.) enable.default.subscriptions - when set to true, the gateway will not be remotely manageable. payload.encoding - Specify the message payload encoding. The possible options are Kura Protobuf and Simple JSON . The default CloudService implementations publishes the following lifecycle messages : BIRTH message : sent immediately when device is connected to the cloud platform. The BIRTH message is published with priority 0 and QoS 1; DISCONNECT message : sent immediately before device is disconnected from the cloud platform. The DISCONNECT message is published with priority 0 and QoS 0; delayed BIRTH message : sent when new cloud application handler becomes available, a DP is installed or removed, GPS position is locked (can be disabled), or when modem status changes (can be disabled). These messages are cached for 30 seconds before sending. If no other message of such type arrives the message is sent; otherwise the BIRTH is cached and the timeout restarts. This is to avoid sending multiple messages when the framework starts. The message is published with priority 0 and QoS 1;","title":"CloudService"},{"location":"cloud-api/built-in-cloud/#mqttdatatransport","text":"The MqttDataTransport service provides the ability to connect to a remote broker, publish messages, subscribe to topics, receive messages on the subscribed topics, and disconnect from the remote message broker. To use this service, select the MqttDataTransport option located in the System area and select the CloudService tab as shown in the screen capture below. The MqttDataTransport service provides the following configuration parameters: broker-url - defines the URL of the MQTT broker to connect to. (Required field.) topic.context.account-name - defines the name of the account to which the device belongs. username and password - define the username and password that have been assigned to the device by the account administrator (generally username is account-name_broker). (Required field.) client-id - defines the identifier of the MQTT client representing the device when connecting to the MQTT broker. If left empty, it is automatically determined by the client software as the MAC address of the main network interface (in general numbers and uppercase letters without ':'). This identifier has to be unique within your account. keep-alive - defines the \"keep alive\" interval measured in seconds. It specifies the maximum amount of time that should pass without communication between the client and the server. The client will ensure that at least one message travels across the network within each keep alive period. In the absence of a data-related message during this time period, the client will send a very small MQTT \"ping\" message that the server will acknowledge. The keep alive interval enables the client to detect when the server is no longer available without having to wait for the long TCP/IP timeout. (Required field.) timeout - sets the timeout used for all interactions with the MQTT broker. (Required field.) clean-session - controls the behavior of both the client and the server at the time of connect and disconnect. When this parameter is set to true, the state information is discarded at connect and disconnect; when set to false, the state information is maintained. (Required field.) lwt parameters - define the MQTT \"Last Will and Testament\" (LWT) settings for the client. In the event that the client unexpectedly loses its connection to the server, the server publishes the LWT message (lwt.payload) to the LWT topic on behalf of the client. This allows other clients (subscribed to the LWT topic) to be made aware that the client has disconnected. LWT parameters that may be configured include: lwt.topic lwt.payload lwt.qos lwt.retain in-flight.persistence - defines the storage type where in-flight messages are persisted across reconnections. They may be stored in memory, or in a file on the disk. (Required field.) protocol-version - defines the MQTT Protocol version to be used. This value may be 3.1 or 3.1.1. ssl parameters - defines the SSL configuration. SSL parameters that may be configured include: ssl.hostname.verification ssl.default.cipherSuites ssl.certificate.alias","title":"MqttDataTransport"},{"location":"cloud-api/cloud-conn-dev-guide/","text":"Cloud connection developer guide This guide will provide information on how a cloud connection developer can leverage the new Generic Cloud Services APIs. As reference, this guide will use the Eclipse IoT WG namespace implementation bundle available here Implement CloudEndpoint and CloudConnectionManager In order to leverage the new APIs, and be managed by the Kura Web UI, the Cloud Connection implementation bundle must implement CloudEndpont and, if log-lived connections are supported, the CloudConnectionManager interface must be implemented as well. The ending class should be something as follows: public class CloudConnectionManagerImpl implements CloudConnectionManager , CloudEndpoint , ... { @Override public boolean isConnected () { ... } @Override public void connect () throws KuraConnectException { ... } @Override public void disconnect () { ... } @Override public Map < String , String > getInfo () { ... } @Override public void registerCloudConnectionListener ( CloudConnectionListener cloudConnectionListener ) { ... } @Override public void unregisterCloudConnectionListener ( CloudConnectionListener cloudConnectionListener ) { ... } } A corresponding component definition should be provided in the OSGI-INF folder exposing the implementation of CloudEndpoint and CloudConnectionManager interfaces. In order to be fully compliant with the Web UI requirements, the CloudConnection component definition should provide two properties kura.ui.service.hide and kura.ui.factory.hide to hide the component from the left side part of the UI dedicated to display the services list. Implement the CloudConnectionFactory interface The CloudConnectionFactory is responsible to manage the cloud connection instance lifecycle by creating the CloudEndpoint instance and all the required services needed to publish or receive messages from the cloud platform. As a reference, please have a look at the CloudConnectionFactory defined for the Eclipse IoT WG namespace implementation. In particular, the getFactoryPid() method returns the PID of the CloudEndpoint factory. The createConfiguration() method receives a PID that will be used for the instantiation of the CloudEndpoint and for all the related services required to communicate with the cloud platform. In the example above, the factory creates the CloudEnpoint, and a DataService and MqttDataTransport instances internally needed to communicate with a remote cloud platform. As can be seen here , the CloudEndpoint instance configuration is enriched with the reference to the CloudConnectionFactory that generated it. This step is required by the Web UI in order to properly relate the instances with the corresponding factories. The deleteConfiguration() method deletes from the framework the CloudEndpoint instance identified by the PID passed as argument and all the related services. In the Eclipse IOT WG example, it not only deletes the CloudEndpoint instance but also the corresponding DataService and MqttDataTransport instances. The getStackComponentsPids() method return a List of String that represent the kura.service.pid of the configurable components that are part of a Cloud Connection instance. This method is used by the Web UI to get the list of configurable components that need to be displayed to the end user. The getManagedCloudConnectionPids() method will return the list of kura.service.pid of all the CloudEndpoints managed by the factory. The factory component definition should be defined as follows: createConfiguration In particular, it should expose in the service section the fact that the factory implements org.eclipse.kura.cloudconnection.factory.CloudConnectionFactory Important properties that need to be specified to have a better Web UI experience are the following: those allow to specify the form of the expected PID that the end user should provide when creating a new cloud connection. Provide a CloudPublisher implementation To provide a CloudPublisher implementation, other than implementing CloudPublisher API in a java class, the developer must provide a component definition in the OSGI-INF folder that should be like the following: As can be seen in the previous snippet, the Publisher exposes itself in the framework as a ConfigurableComponent and as a CloudPublisher . The component definition must contain the following well-known properties: cloud.connection.factory.pid : this property must be set to the kura.service.pid of the factory that created the cloud connection which the publisher belongs. It is used by the Web UI to enforce that the correct cloud publisher implementation is used in a specific cloud endpoint. kura.ui.service.hide : as specified before for the Cloud Endpoint kura.ui.factory.hide : as specified before for the Cloud Endpoint kura.ui.csf.pid.default : as specified before for the Cloud Factory. It is an optional property. kura.ui.csf.pid.regex : as specified before for the Cloud Factory. It is an optional property. The relation between the CloudPublisher instance and the CloudEndpoint is defined by a configuration property set by the Web UI at CloudPublisher creation. Provide a CloudSubscriber implementation The CloudSubscriber implementation and component definition is similar to the one described for the CloudPublisher. Implement RequestHandler support In order to support Command and Control, the cloud connection bundle should provide a service that registers itself as RequestHandlerRegistry. In this way all the RequestHandler instances could be able to discover the different Registry and subscribe for command and control messages received from the cloud platform. As an example, for the Eclipse IoT WG bundle, the CloudEndpoint registers itself also as RequestHandlerRegistry.","title":"Cloud Connection Developer Guide"},{"location":"cloud-api/cloud-conn-dev-guide/#cloud-connection-developer-guide","text":"This guide will provide information on how a cloud connection developer can leverage the new Generic Cloud Services APIs. As reference, this guide will use the Eclipse IoT WG namespace implementation bundle available here","title":"Cloud connection developer guide"},{"location":"cloud-api/cloud-conn-dev-guide/#implement-cloudendpoint-and-cloudconnectionmanager","text":"In order to leverage the new APIs, and be managed by the Kura Web UI, the Cloud Connection implementation bundle must implement CloudEndpont and, if log-lived connections are supported, the CloudConnectionManager interface must be implemented as well. The ending class should be something as follows: public class CloudConnectionManagerImpl implements CloudConnectionManager , CloudEndpoint , ... { @Override public boolean isConnected () { ... } @Override public void connect () throws KuraConnectException { ... } @Override public void disconnect () { ... } @Override public Map < String , String > getInfo () { ... } @Override public void registerCloudConnectionListener ( CloudConnectionListener cloudConnectionListener ) { ... } @Override public void unregisterCloudConnectionListener ( CloudConnectionListener cloudConnectionListener ) { ... } } A corresponding component definition should be provided in the OSGI-INF folder exposing the implementation of CloudEndpoint and CloudConnectionManager interfaces. In order to be fully compliant with the Web UI requirements, the CloudConnection component definition should provide two properties kura.ui.service.hide and kura.ui.factory.hide to hide the component from the left side part of the UI dedicated to display the services list.","title":"Implement CloudEndpoint and CloudConnectionManager"},{"location":"cloud-api/cloud-conn-dev-guide/#implement-the-cloudconnectionfactory-interface","text":"The CloudConnectionFactory is responsible to manage the cloud connection instance lifecycle by creating the CloudEndpoint instance and all the required services needed to publish or receive messages from the cloud platform. As a reference, please have a look at the CloudConnectionFactory defined for the Eclipse IoT WG namespace implementation. In particular, the getFactoryPid() method returns the PID of the CloudEndpoint factory. The createConfiguration() method receives a PID that will be used for the instantiation of the CloudEndpoint and for all the related services required to communicate with the cloud platform. In the example above, the factory creates the CloudEnpoint, and a DataService and MqttDataTransport instances internally needed to communicate with a remote cloud platform. As can be seen here , the CloudEndpoint instance configuration is enriched with the reference to the CloudConnectionFactory that generated it. This step is required by the Web UI in order to properly relate the instances with the corresponding factories. The deleteConfiguration() method deletes from the framework the CloudEndpoint instance identified by the PID passed as argument and all the related services. In the Eclipse IOT WG example, it not only deletes the CloudEndpoint instance but also the corresponding DataService and MqttDataTransport instances. The getStackComponentsPids() method return a List of String that represent the kura.service.pid of the configurable components that are part of a Cloud Connection instance. This method is used by the Web UI to get the list of configurable components that need to be displayed to the end user. The getManagedCloudConnectionPids() method will return the list of kura.service.pid of all the CloudEndpoints managed by the factory. The factory component definition should be defined as follows: createConfiguration In particular, it should expose in the service section the fact that the factory implements org.eclipse.kura.cloudconnection.factory.CloudConnectionFactory Important properties that need to be specified to have a better Web UI experience are the following: those allow to specify the form of the expected PID that the end user should provide when creating a new cloud connection.","title":"Implement the CloudConnectionFactory interface"},{"location":"cloud-api/cloud-conn-dev-guide/#provide-a-cloudpublisher-implementation","text":"To provide a CloudPublisher implementation, other than implementing CloudPublisher API in a java class, the developer must provide a component definition in the OSGI-INF folder that should be like the following: As can be seen in the previous snippet, the Publisher exposes itself in the framework as a ConfigurableComponent and as a CloudPublisher . The component definition must contain the following well-known properties: cloud.connection.factory.pid : this property must be set to the kura.service.pid of the factory that created the cloud connection which the publisher belongs. It is used by the Web UI to enforce that the correct cloud publisher implementation is used in a specific cloud endpoint. kura.ui.service.hide : as specified before for the Cloud Endpoint kura.ui.factory.hide : as specified before for the Cloud Endpoint kura.ui.csf.pid.default : as specified before for the Cloud Factory. It is an optional property. kura.ui.csf.pid.regex : as specified before for the Cloud Factory. It is an optional property. The relation between the CloudPublisher instance and the CloudEndpoint is defined by a configuration property set by the Web UI at CloudPublisher creation.","title":"Provide a CloudPublisher implementation"},{"location":"cloud-api/cloud-conn-dev-guide/#provide-a-cloudsubscriber-implementation","text":"The CloudSubscriber implementation and component definition is similar to the one described for the CloudPublisher.","title":"Provide a CloudSubscriber implementation"},{"location":"cloud-api/cloud-conn-dev-guide/#implement-requesthandler-support","text":"In order to support Command and Control, the cloud connection bundle should provide a service that registers itself as RequestHandlerRegistry. In this way all the RequestHandler instances could be able to discover the different Registry and subscribe for command and control messages received from the cloud platform. As an example, for the Eclipse IoT WG bundle, the CloudEndpoint registers itself also as RequestHandlerRegistry.","title":"Implement RequestHandler support"},{"location":"cloud-api/overview/","text":"Overview This section describes the new cloud related concepts and APIs introduced in Kura 4.0. Motivations Before Kura 4.0, Cloud APIs were quite tied to Kapua messaging conventions and to the MQTT protocol. Defining custom stacks that support other cloud platforms was possible, but the resulting implementations were affected by the following limitations: The legacy APIs assume that the underlying messaging protocol is MQTT. This assumption spans across all API layers, from the low level MQTTDataTrasport to the high level CloudClient . This makes quite difficult to implement cloud stacks that use other protocols like AMQP or HTTP. The CloudClient API, which was the recommended way for applications to interface with a cloud stack, enforce the following MQTT topic structure: #account-name/#device-id/#app-id/ This topic hierarchy, which is Kapua related, might be too restrictive or too loose for other cloud platforms, for example: The Eclipse IoT working group namespace allows authenticated devices to omit the accont-name and device-id parameters in the topic. Moreover, telemetry, alert and event message topics must start respectively the t/ , a/ and e/ prefixes. Adhering to this specification is not possible for a cloud stack that implements the legacy APIs. The AWS cloud platform allows publishing on virtually any topic, using a CloudClient would be quite restrictive in this case. A way for overcoming this limitation for an application might be using the DataService layer directly, adversely affecting portability. The Cumulocity cloud platform allows publishing only on a limited set of topics, and most of the application generated information is placed in the payload encoded in CSV. Using CloudClient in this case makes difficult for the cloud stack to enforce that the messages are published on the correct topics. Moreover, the cloud stack in this case must also convert from KuraPayload to CSV, this can be currently achieved only by introducing rigid conversion rules, that might not be enough to support all message formats. Applications that use the current APIs are not portable across cloud platforms. For example if an appliaction intends to publish on Cumulocity or AWS, it should be probably aware of the underlying cloud platform. Concepts The main interfaces of the new set of APIs and their interactions are depicted in the diagram below: As shown in the above diagram new APIs introduce the concept of Cloud Connection , a set of related services that allow to manage the communication to/from a remote cloud platform. The services that compose a Cloud Connection can implement the following cloud-specific interfaces: CloudEndpoint (required): Each Cloud Connection is identified by a single instance of CloudEndpoint that implements low level specificities for the communication with the remote cloud platform. CloudConnectionManager (optional): Exposes methods that allow to manage long-lived connections. The implementor of CloudEndpoint can implement this interface as well if the cloud platform support long-lived connections (for example by using the MQTT protocol). RequestHandlerRegistry (optional): Manages the command and control functionalities if supported by the cloud platform. CloudPublisher (optional): Allows applications to publish messages to the cloud platform in a portable way. CloudSubscriber (optional): Allows applications to receive messages from the cloud platform in a portable way. CloudConnectionFactory (required): Manages the lifecycle of Cloud Connections. A Cloud Connection can also include services that do not provide any of the interfaces above but compose the internal implementation. CloudEndpoint Every Cloud Connection must contain a single CloudEndpoint instance. The kura.service.pid of the CloudEndpoint identifies the whole Cloud Connection. The CloudEndpoint provides some low level methods that can be used to interact with the remote cloud platform. For example the interface provides the publish() and subscribe() methods that allow to publish or receive messages from the cloud platform in form of KuraMessage s. Those methods are designed for internal use and are not intended to be used by end-user applications. The format of the KuraMessage provided to/received from a CloudEndpoint is implementation specific: the CloudEndpoint expects some properties to be set in the KuraMessage to be able to correctly publish a message (e.g. MQTT topic). These properties are specified by the particular CloudEndpoint , and should be documented by the implementor. The recommended way for applications to publish and receive messages involves using the Publisher and Subscriber APIs described below. If an application directly uses the methods above, it will lose portability and will be tied to the specific Cloud Connection implementation. CloudConnectionManager If the messaging protocol implemented by a Cloud Connection supports long-lived connection, then its CloudEndpoint can also implement and provide the CloudConnectionManager interface. This interface exposes some methods that can be used to manage the connection like connect() , disconnect() and isConnected() ; it also supports monitoring connection state using the CloudConnectionListener interface. Publishers and Subscribers The limitations of the current model described above are addressed by the introduction of the CloudPublisher and CloudSubscriber APIs, that replace the CloudClient as the recommended interface between applications and cloud stacks. CloudPublisher and CloudSubscriber are service interfaces defined as follows: public interface CloudPublisher { public String publish ( KuraMessage message ) throws KuraException ; public void registerCloudConnectionListener ( CloudConnectionListener cloudConnectionListener ); public void unregisterCloudConnectionListener ( CloudConnectionListener cloudConnectionListener ); public void registerCloudDeliveryListener ( CloudDeliveryListener cloudDeliveryListener ); public void unregisterCloudDeliveryListener ( CloudDeliveryListener cloudDeliveryListener ); } public interface CloudSubscriber { public void registerCloudSubscriberListener ( CloudSubscriberListener listener ); public void unregisterCloudSubscriberListener ( CloudSubscriberListener listener ); public void registerCloudConnectionListener ( CloudConnectionListener cloudConnectionListener ); public void unregisterCloudConnectionListener ( CloudConnectionListener cloudConnectionListener ); } CloudPublisher The CloudPublisher interface should be used by applications for publishing messages using the single publish() method. This method accepts a KuraMessage which is basically a KuraPayload that can be enriched with metadata. The main difference with the CloudClient APIs is that the publish() method does not require the application to specify any information related to message destinations. This allows to write portable applications that are unaware of the low level details of the destination cloud platform, such as the message format and the transport protocol. CloudSubscriber An application designed to receive messages from the cloud must now attach a listener ( CloudSubscriberListener ) to a CloudSubscriber instance. In this case, the message source cannot be specified by the application but is defined by the subscriber instance, in the same way as the CloudPublisher defines destination for published messages. The low level details necessary for message delivery and reception (e.g. the MQTT topic and the conversion between KuraMessage and the message format used on the wire) are managed by the publisher/subscriber, typically these details are stored in the service configuration. While in the previous model an application was responsible to actively obtain a CloudClient instance from a CloudService , now the relation between the application and a CloudPublisher or CloudSubscriber instance is represented as an OSGi service reference. Applications should allow the user to modify this reference in configuration, making it easy to switch between different cloud publisher/subscriber instances and different cloud platforms. Publisher/subscriber instances are now typically instantiated and configured by the end user using the Web UI. Publisher/subscriber instances are related to a CloudEnpoint instance using an OSGi service reference encoded in well known configuration property specified in the APIs ( CloudConnectionConstants.CLOUD_ENDPOINT_SERVICE_PID_PROP_NAME ). This allows the user to create those instances in a dedicated section of the Web UI. Command and control Another field in which the current Kura cloud related APIs can be generalized is related to command and control. In the previous model this aspect was covered by the Cloudlet APIs that are now replaced by RequestHandler APIs Legacy Cloudlet implementations are defined by extending a base class, Cloudlet , which takes care of handling the invocation of the doGet() , doPut() , doPost() ... methods, and of correlating request and response messages. Messages were sent and received through a CloudClient . More explicitly, Cloudlet only works with control topics whose structure is $EDC///// and also expects the identifier of the sender and the correlation identifier in the KuraPayload . In the previous model, there is no way for a cloud stack implementor to customize the aspects above, which are hardcoded in the Cloudlet base class. The new model delegates these aspects to some component of the cloud stack, and requires applications that want to support command and control to register themselves as RequestHandler to a RequestHandlerRegistry instance. In order to ease porting old applications to the new model, some of the concepts of the old Cloudlet APIs are still present, this can be seen by looking at the RequestHandler interface definition: public interface RequestHandler { public KuraMessage doGet ( RequestHandlerContext context , KuraMessage reqMessage ) throws KuraException ; public KuraMessage doPut ( RequestHandlerContext context , KuraMessage reqMessage ) throws KuraException ; public KuraMessage doPost ( RequestHandlerContext context , KuraMessage reqMessage ) throws KuraException ; public KuraMessage doDel ( RequestHandlerContext context , KuraMessage reqMessage ) throws KuraException ; public KuraMessage doExec ( RequestHandlerContext context , KuraMessage reqMessage ) throws KuraException ; } A RequestHandler invocation involves the following parameters: Request parameters: method : (GET, PUT, POST, DEL, EXEC) that identifies the RequestHandler method to be called request message : A set of key-value pairs and/or binary body contained in the KuraPayload wrapped inside the KuraMessage . resources : A List of positional parameters available under the well known args key in the provided KuraMessage properties. Response parameters: response message : A set of key-value pairs and/or binary body contained in the KuraPayload wrapped inside the returned KuraMessage . status : A numeric code reporting operation completion state, determined as follows: 200, if RequestHandler methods returns without throwing exceptions. 400, if RequestHandler methods throws a KuraException with KuraErrorCode == BAD_REQUEST 404, if RequestHandler methods throws a KuraException with KuraErrorCode == NOT_FOUND 500, if RequestHandler methods throws a KuraException with other error codes. exception message : The message of the KuraException thrown by the RequestHandler methods, if any. exception stack trace : The stack trace of the KuraException thrown by the RequestHandler methods, if any. The parameters above are the same involved in current Cloudlet calls. The request id and requester client id parameters are no longer part of the API, because are related to the to the way Kapua correlates requests and response. In the new API, request and response identifiers are not specified and not forwarded to the Cloudlet, this allows the CloudletService implementation to adopt the platform specific conventions for message correlation. The Cloudlet parameters must be present in the request and response messages encoded in some format. A user that intends to call a Kura Cloudlet, for example through platform-specific REST APIs must be aware of these parameters. The user must supply request parameters in request message and must be able to extract response data from received message. The actual encoding of these parameters inside the messages depends on the particular platform. The fact that set of Cloudlet parameters are roughly the same involved in current Cloudlet calls allows existing Cloudlet based applications to continue to work without changes to the protocol. Cloud Connection lifecycle CloudEndpoint instance lifecycle is managed by a CloudConnectionFactory instance. A cloud connection implementor must register a CloudConnectionFactory instance in the framework that is responsible of creating and destroying the CloudEndpoint instances. The CloudConnectionFactory will be typically invoked by the Web UI, and is defined as follows: public interface CloudConnectionFactory { public static final String KURA_CLOUD_CONNECTION_FACTORY_PID = \"kura.cloud.connection.factory.pid\" ; public String getFactoryPid (); public void createConfiguration ( String pid ) throws KuraException ; public List < String > getStackComponentsPids ( String pid ) throws KuraException ; public void deleteConfiguration ( String pid ) throws KuraException ; public Set < String > getManagedCloudConnectionPids () throws KuraException ; } The createConfiguration() and deleteConfiguration() methods are responsible of creating/destroying a CloudEndpoint instance, specified by the provided kura.service.pid , and all the related services. The getManagedCloudConnectionPids() returns the set of kura.service.pid managed by the factory. The getStackComponentsPids(String pid) returns the list of the kura.service.pid s of the ConfigurableComponent s that are associated with the CloudEndpoint with the specified pid. The Web Ui will render the configuration of those components in separated tabs, in the dedicated CloudConnections section. Backwards compatibility In order to ease the transition to the new model, legacy APIs like CloudService and CloudClient are still supported in Kura 4.0.0, even if deprecated. The default Kapua oriented CloudService implementation is still available and can be used by legacy applications without changes. The default CloudService instance in Kura 4.0 also implements the new CloudEndpoint and CloudConnectionManager interfaces.","title":"Overview"},{"location":"cloud-api/overview/#overview","text":"This section describes the new cloud related concepts and APIs introduced in Kura 4.0.","title":"Overview"},{"location":"cloud-api/overview/#motivations","text":"Before Kura 4.0, Cloud APIs were quite tied to Kapua messaging conventions and to the MQTT protocol. Defining custom stacks that support other cloud platforms was possible, but the resulting implementations were affected by the following limitations: The legacy APIs assume that the underlying messaging protocol is MQTT. This assumption spans across all API layers, from the low level MQTTDataTrasport to the high level CloudClient . This makes quite difficult to implement cloud stacks that use other protocols like AMQP or HTTP. The CloudClient API, which was the recommended way for applications to interface with a cloud stack, enforce the following MQTT topic structure: #account-name/#device-id/#app-id/ This topic hierarchy, which is Kapua related, might be too restrictive or too loose for other cloud platforms, for example: The Eclipse IoT working group namespace allows authenticated devices to omit the accont-name and device-id parameters in the topic. Moreover, telemetry, alert and event message topics must start respectively the t/ , a/ and e/ prefixes. Adhering to this specification is not possible for a cloud stack that implements the legacy APIs. The AWS cloud platform allows publishing on virtually any topic, using a CloudClient would be quite restrictive in this case. A way for overcoming this limitation for an application might be using the DataService layer directly, adversely affecting portability. The Cumulocity cloud platform allows publishing only on a limited set of topics, and most of the application generated information is placed in the payload encoded in CSV. Using CloudClient in this case makes difficult for the cloud stack to enforce that the messages are published on the correct topics. Moreover, the cloud stack in this case must also convert from KuraPayload to CSV, this can be currently achieved only by introducing rigid conversion rules, that might not be enough to support all message formats. Applications that use the current APIs are not portable across cloud platforms. For example if an appliaction intends to publish on Cumulocity or AWS, it should be probably aware of the underlying cloud platform.","title":"Motivations"},{"location":"cloud-api/overview/#concepts","text":"The main interfaces of the new set of APIs and their interactions are depicted in the diagram below: As shown in the above diagram new APIs introduce the concept of Cloud Connection , a set of related services that allow to manage the communication to/from a remote cloud platform. The services that compose a Cloud Connection can implement the following cloud-specific interfaces: CloudEndpoint (required): Each Cloud Connection is identified by a single instance of CloudEndpoint that implements low level specificities for the communication with the remote cloud platform. CloudConnectionManager (optional): Exposes methods that allow to manage long-lived connections. The implementor of CloudEndpoint can implement this interface as well if the cloud platform support long-lived connections (for example by using the MQTT protocol). RequestHandlerRegistry (optional): Manages the command and control functionalities if supported by the cloud platform. CloudPublisher (optional): Allows applications to publish messages to the cloud platform in a portable way. CloudSubscriber (optional): Allows applications to receive messages from the cloud platform in a portable way. CloudConnectionFactory (required): Manages the lifecycle of Cloud Connections. A Cloud Connection can also include services that do not provide any of the interfaces above but compose the internal implementation.","title":"Concepts"},{"location":"cloud-api/overview/#cloudendpoint","text":"Every Cloud Connection must contain a single CloudEndpoint instance. The kura.service.pid of the CloudEndpoint identifies the whole Cloud Connection. The CloudEndpoint provides some low level methods that can be used to interact with the remote cloud platform. For example the interface provides the publish() and subscribe() methods that allow to publish or receive messages from the cloud platform in form of KuraMessage s. Those methods are designed for internal use and are not intended to be used by end-user applications. The format of the KuraMessage provided to/received from a CloudEndpoint is implementation specific: the CloudEndpoint expects some properties to be set in the KuraMessage to be able to correctly publish a message (e.g. MQTT topic). These properties are specified by the particular CloudEndpoint , and should be documented by the implementor. The recommended way for applications to publish and receive messages involves using the Publisher and Subscriber APIs described below. If an application directly uses the methods above, it will lose portability and will be tied to the specific Cloud Connection implementation.","title":"CloudEndpoint"},{"location":"cloud-api/overview/#cloudconnectionmanager","text":"If the messaging protocol implemented by a Cloud Connection supports long-lived connection, then its CloudEndpoint can also implement and provide the CloudConnectionManager interface. This interface exposes some methods that can be used to manage the connection like connect() , disconnect() and isConnected() ; it also supports monitoring connection state using the CloudConnectionListener interface.","title":"CloudConnectionManager"},{"location":"cloud-api/overview/#publishers-and-subscribers","text":"The limitations of the current model described above are addressed by the introduction of the CloudPublisher and CloudSubscriber APIs, that replace the CloudClient as the recommended interface between applications and cloud stacks. CloudPublisher and CloudSubscriber are service interfaces defined as follows: public interface CloudPublisher { public String publish ( KuraMessage message ) throws KuraException ; public void registerCloudConnectionListener ( CloudConnectionListener cloudConnectionListener ); public void unregisterCloudConnectionListener ( CloudConnectionListener cloudConnectionListener ); public void registerCloudDeliveryListener ( CloudDeliveryListener cloudDeliveryListener ); public void unregisterCloudDeliveryListener ( CloudDeliveryListener cloudDeliveryListener ); } public interface CloudSubscriber { public void registerCloudSubscriberListener ( CloudSubscriberListener listener ); public void unregisterCloudSubscriberListener ( CloudSubscriberListener listener ); public void registerCloudConnectionListener ( CloudConnectionListener cloudConnectionListener ); public void unregisterCloudConnectionListener ( CloudConnectionListener cloudConnectionListener ); }","title":"Publishers and Subscribers"},{"location":"cloud-api/overview/#cloudpublisher","text":"The CloudPublisher interface should be used by applications for publishing messages using the single publish() method. This method accepts a KuraMessage which is basically a KuraPayload that can be enriched with metadata. The main difference with the CloudClient APIs is that the publish() method does not require the application to specify any information related to message destinations. This allows to write portable applications that are unaware of the low level details of the destination cloud platform, such as the message format and the transport protocol.","title":"CloudPublisher"},{"location":"cloud-api/overview/#cloudsubscriber","text":"An application designed to receive messages from the cloud must now attach a listener ( CloudSubscriberListener ) to a CloudSubscriber instance. In this case, the message source cannot be specified by the application but is defined by the subscriber instance, in the same way as the CloudPublisher defines destination for published messages. The low level details necessary for message delivery and reception (e.g. the MQTT topic and the conversion between KuraMessage and the message format used on the wire) are managed by the publisher/subscriber, typically these details are stored in the service configuration. While in the previous model an application was responsible to actively obtain a CloudClient instance from a CloudService , now the relation between the application and a CloudPublisher or CloudSubscriber instance is represented as an OSGi service reference. Applications should allow the user to modify this reference in configuration, making it easy to switch between different cloud publisher/subscriber instances and different cloud platforms. Publisher/subscriber instances are now typically instantiated and configured by the end user using the Web UI. Publisher/subscriber instances are related to a CloudEnpoint instance using an OSGi service reference encoded in well known configuration property specified in the APIs ( CloudConnectionConstants.CLOUD_ENDPOINT_SERVICE_PID_PROP_NAME ). This allows the user to create those instances in a dedicated section of the Web UI.","title":"CloudSubscriber"},{"location":"cloud-api/overview/#command-and-control","text":"Another field in which the current Kura cloud related APIs can be generalized is related to command and control. In the previous model this aspect was covered by the Cloudlet APIs that are now replaced by RequestHandler APIs Legacy Cloudlet implementations are defined by extending a base class, Cloudlet , which takes care of handling the invocation of the doGet() , doPut() , doPost() ... methods, and of correlating request and response messages. Messages were sent and received through a CloudClient . More explicitly, Cloudlet only works with control topics whose structure is $EDC///// and also expects the identifier of the sender and the correlation identifier in the KuraPayload . In the previous model, there is no way for a cloud stack implementor to customize the aspects above, which are hardcoded in the Cloudlet base class. The new model delegates these aspects to some component of the cloud stack, and requires applications that want to support command and control to register themselves as RequestHandler to a RequestHandlerRegistry instance. In order to ease porting old applications to the new model, some of the concepts of the old Cloudlet APIs are still present, this can be seen by looking at the RequestHandler interface definition: public interface RequestHandler { public KuraMessage doGet ( RequestHandlerContext context , KuraMessage reqMessage ) throws KuraException ; public KuraMessage doPut ( RequestHandlerContext context , KuraMessage reqMessage ) throws KuraException ; public KuraMessage doPost ( RequestHandlerContext context , KuraMessage reqMessage ) throws KuraException ; public KuraMessage doDel ( RequestHandlerContext context , KuraMessage reqMessage ) throws KuraException ; public KuraMessage doExec ( RequestHandlerContext context , KuraMessage reqMessage ) throws KuraException ; } A RequestHandler invocation involves the following parameters: Request parameters: method : (GET, PUT, POST, DEL, EXEC) that identifies the RequestHandler method to be called request message : A set of key-value pairs and/or binary body contained in the KuraPayload wrapped inside the KuraMessage . resources : A List of positional parameters available under the well known args key in the provided KuraMessage properties. Response parameters: response message : A set of key-value pairs and/or binary body contained in the KuraPayload wrapped inside the returned KuraMessage . status : A numeric code reporting operation completion state, determined as follows: 200, if RequestHandler methods returns without throwing exceptions. 400, if RequestHandler methods throws a KuraException with KuraErrorCode == BAD_REQUEST 404, if RequestHandler methods throws a KuraException with KuraErrorCode == NOT_FOUND 500, if RequestHandler methods throws a KuraException with other error codes. exception message : The message of the KuraException thrown by the RequestHandler methods, if any. exception stack trace : The stack trace of the KuraException thrown by the RequestHandler methods, if any. The parameters above are the same involved in current Cloudlet calls. The request id and requester client id parameters are no longer part of the API, because are related to the to the way Kapua correlates requests and response. In the new API, request and response identifiers are not specified and not forwarded to the Cloudlet, this allows the CloudletService implementation to adopt the platform specific conventions for message correlation. The Cloudlet parameters must be present in the request and response messages encoded in some format. A user that intends to call a Kura Cloudlet, for example through platform-specific REST APIs must be aware of these parameters. The user must supply request parameters in request message and must be able to extract response data from received message. The actual encoding of these parameters inside the messages depends on the particular platform. The fact that set of Cloudlet parameters are roughly the same involved in current Cloudlet calls allows existing Cloudlet based applications to continue to work without changes to the protocol.","title":"Command and control"},{"location":"cloud-api/overview/#cloud-connection-lifecycle","text":"CloudEndpoint instance lifecycle is managed by a CloudConnectionFactory instance. A cloud connection implementor must register a CloudConnectionFactory instance in the framework that is responsible of creating and destroying the CloudEndpoint instances. The CloudConnectionFactory will be typically invoked by the Web UI, and is defined as follows: public interface CloudConnectionFactory { public static final String KURA_CLOUD_CONNECTION_FACTORY_PID = \"kura.cloud.connection.factory.pid\" ; public String getFactoryPid (); public void createConfiguration ( String pid ) throws KuraException ; public List < String > getStackComponentsPids ( String pid ) throws KuraException ; public void deleteConfiguration ( String pid ) throws KuraException ; public Set < String > getManagedCloudConnectionPids () throws KuraException ; } The createConfiguration() and deleteConfiguration() methods are responsible of creating/destroying a CloudEndpoint instance, specified by the provided kura.service.pid , and all the related services. The getManagedCloudConnectionPids() returns the set of kura.service.pid managed by the factory. The getStackComponentsPids(String pid) returns the list of the kura.service.pid s of the ConfigurableComponent s that are associated with the CloudEndpoint with the specified pid. The Web Ui will render the configuration of those components in separated tabs, in the dedicated CloudConnections section.","title":"Cloud Connection lifecycle"},{"location":"cloud-api/overview/#backwards-compatibility","text":"In order to ease the transition to the new model, legacy APIs like CloudService and CloudClient are still supported in Kura 4.0.0, even if deprecated. The default Kapua oriented CloudService implementation is still available and can be used by legacy applications without changes. The default CloudService instance in Kura 4.0 also implements the new CloudEndpoint and CloudConnectionManager interfaces.","title":"Backwards compatibility"},{"location":"cloud-api/user-guide/","text":"User guide This guide will illustrate the steps required for configuring an application that uses the new Cloud Connection APIs to publish messages to the Kapua platform. The involved steps are the following Instantiation and configuration of the Cloud Connection . Instantiation and configuration of a Publisher . Binding an application to the Publisher . Creating a new Cloud Connection Open the Cloud Connections section of the Web UI: Create a new Cloud Connection Click on the New Connection button Enter a new unique identifier in the Cloud Connection Service PID field. The identifier must be a valid kura.service.pid and, in case of a Kapua Cloud Connection, it must start with the org.eclipse.kura.cloud.CloudService- prefix. A valid identifier can be org.eclipse.kura.cloud.CloudService-KAPUA . As an alternative it is possible to reconfigure the existing org.eclipse.kura.cloud.CloudService Cloud Connection. Configure the MQTTDataTrasport service. Click on the MQTTDataTrasport-KAPUA tab and fill the parameters required for establishing the MQTT connection: Broker-url Topic Context Account-Name Username Password Configure the DataService-KAPUA service. In order to enable automatic connection, set the Connect Auto-on-startup parameter to true Creating and configuring a new Publisher Select to the connection to be used from the list. Click on the New Pub/Sub button. Select the type of component to be created, from the Available Publisher/Subscriber factories drop down list, in order to create a Publisher select the org.eclipse.kura.cloud.publisher.CloudPublisher entry. Enter an unique kura.service.pid identifier in the New Publisher/Subscriber PID field. Click Apply , you should see the publisher configuration Select and configure the newly created publisher instance, and then click Apply Binding an application to a publisher Select the application instance configuration Find the configuration entry that represents a Publisher reference. Click on the Select available targets link and select the desired Publisher instance to bind to. Click on Apply","title":"User Guide"},{"location":"cloud-api/user-guide/#user-guide","text":"This guide will illustrate the steps required for configuring an application that uses the new Cloud Connection APIs to publish messages to the Kapua platform. The involved steps are the following Instantiation and configuration of the Cloud Connection . Instantiation and configuration of a Publisher . Binding an application to the Publisher .","title":"User guide"},{"location":"cloud-api/user-guide/#creating-a-new-cloud-connection","text":"Open the Cloud Connections section of the Web UI: Create a new Cloud Connection Click on the New Connection button Enter a new unique identifier in the Cloud Connection Service PID field. The identifier must be a valid kura.service.pid and, in case of a Kapua Cloud Connection, it must start with the org.eclipse.kura.cloud.CloudService- prefix. A valid identifier can be org.eclipse.kura.cloud.CloudService-KAPUA . As an alternative it is possible to reconfigure the existing org.eclipse.kura.cloud.CloudService Cloud Connection. Configure the MQTTDataTrasport service. Click on the MQTTDataTrasport-KAPUA tab and fill the parameters required for establishing the MQTT connection: Broker-url Topic Context Account-Name Username Password Configure the DataService-KAPUA service. In order to enable automatic connection, set the Connect Auto-on-startup parameter to true","title":"Creating a new Cloud Connection"},{"location":"cloud-api/user-guide/#creating-and-configuring-a-new-publisher","text":"Select to the connection to be used from the list. Click on the New Pub/Sub button. Select the type of component to be created, from the Available Publisher/Subscriber factories drop down list, in order to create a Publisher select the org.eclipse.kura.cloud.publisher.CloudPublisher entry. Enter an unique kura.service.pid identifier in the New Publisher/Subscriber PID field. Click Apply , you should see the publisher configuration Select and configure the newly created publisher instance, and then click Apply","title":"Creating and configuring a new Publisher"},{"location":"cloud-api/user-guide/#binding-an-application-to-a-publisher","text":"Select the application instance configuration Find the configuration entry that represents a Publisher reference. Click on the Select available targets link and select the desired Publisher instance to bind to. Click on Apply","title":"Binding an application to a publisher"},{"location":"cloud-platform/kura-aws-cloud/","text":"Amazon AWS IoT\u2122 platform Overview This section provides a guide on connecting an Eclipse Kura\u2122 device to the Amazon AWS IoT platform. Prerequisites In order to connect a device to Amazon AWS IoT Kura version 1.3 or greater is required. An Amazon AWS account is also needed. Device registration The first step involves the registration of the new device on AWS, this operation can be done using the AWS Web Console or with the AWS CLI command line tool, in this guide the Web based console will be used. 1. Access the AWS IoT management console. This can be done by logging in the AWS console and selecting IoT Core from the services list, in the Internet of Things section. 2. Create a default policy for the device. This step involves creating a default policy for the new device, skip if an existing policy is already available. Access the main screen of the console and select Secure -> Policies from the left side menu and then press the Create button, in the top right area of the screen. Fill the form as follows and then press the Create button: Action -> iot:Connect, iot:Publish, iot:Subscribe, iot:Receive, iot:UpdateThingShadow, iot:GetThingShadow, iot:DeleteThingShadow Resource ARN -> * Effect -> Allow This will create a policy that allows a device to connect to the platform, publish/subscribe on any topic and manage its thing shadow . 3. Register a new device. Devices on the AWS IoT platform are called things , in order to register a new thing select Manage -> Things from the left side menu and then press the Create button, in the top right section of the screen. Select Create a single thing . Enter a name for the new device and then press the Next button, from now on kura-gateway will be used as the device name. 4. Create a new certificate for the device. The AWS IoT platform uses SSL mutual authentication, for this reason it is necessary to download a public/private key pair for the device and a server certificate. Click on Create certificate to quickly generate a new certificate for the new device. Certificates can be managed later on by clicking on Secure -> Certificates , in the left part of the console. 5. Download the device SSL keys. You should see a screen like the following: Download the 3 files listed in the table and store them in a safe place, they will be needed later, also copy the link to the root CA for AWS IoT in order to be able to retrieve it later from the device. Press the Activate button, and then on Attach a policy . 6. Assign the default policy to the device. Select the desired policy and then click on Register thing . A policy can also be attached to a certificate later on perforiming the following steps: Enter the device configuration section, by clicking on Manage -> Things and then clicking on the newly created device. Click on Security on the left panel and then click on the certificate entry (it is identified by an hex code), select Policies in the left menu, you should see this screen: Click on Actions in the top left section of the page and then click on Attach policy , select the default policy previously created and then press the Attach button. Device configuration The following steps should be performed on the device, this guide is based on Kura 3.1.0 version and has been tested on a Raspberry PI 3. 7. Create a Java keystore on the device. The first step for using the device keys obtained at the previous step is to create a new Java keystore containing the Root Certificate used by the Amazon IoT platform, this can be done executing the following commands on the device: sudo mkdir /opt/eclipse/kura/security cd /opt/eclipse/kura/security curl https://www.amazontrust.com/repository/AmazonRootCA1.pem > /tmp/root-CA.pem sudo keytool -import -trustcacerts -alias aws -file /tmp/root-CA.pem -keystore cacerts.ks -storepass changeit If the last command reports that the certificate already exist in the system-wide store type yes to proceed. The code above will generate a new keystore with changeit as password, change it if needed. 8. Configure the SSL parameters using the Kura Web UI. Open the Kura Web Console and enter select the Settings entry in the left side menu and then click on SSL Configuration , you should see this screen: Change the Keystore path parameter to /opt/eclipse/kura/security/cacerts.ks if needed. Change the settings in the form to match the screen above, set Default protocol to TLSv1.2 , enter changeit as Keystore Password (or the password defined at step 7). Warning Steps from 8.2 to 8.6 will not work on Kura 3.2.0 due to a known issue . On this version, private key and device certificate need to be manually added to the keystore using the command line. If you are running Kura 3.2.0, proceed with step 8.7. Open the Kura Web Console and enter select the Settings entry in the left side menu and then click on Device SSL Certificate , you should see this screen: Enter aws-ssl in the Storage Alias field. The private key needs to be converted to the PKCS8 format, this step can be performed executing the following command on a Linux or OSX based machine: openssl pkcs8 -topk8 -inform PEM -outform PEM -in xxxxxxxxxx-private.pem.key -out outKey.pem -nocrypt where xxxxxxxxxx-private.pem.key is the file containing the private key downloaded at step 4. Paste the contents of the obtained outKey.pem in the \"Private Key\" field. Paste the contents of xxxxxxxxxx-certificate.pem.crt in the Certificate field. You should see a screen like this Click the Apply button to confirm. Kura 3.2.0 only - manually import device certificate and private key into keystore. On the host machine, open a terminal window in the folder containing the files downloaded at step 5 and execute the following command: openssl pkcs12 -export -in xxxxxxxxxx-certificate.pem.crt -inkey xxxxxxxxxx-private.pem.key -name aws-ssl -out aws-ssl.p12 where xxxxxxxxxx-certificate.pem.crt is the original certificate downloaded from AWS and xxxxxxxxxx-private.pem.key is the private key. The command will ask for a password, define a new password. Copy the obtained aws-ssl.p12 file to the device into the /tmp folder using scp: scp ./aws-ssl.p12 pi@:/tmp Replacing with the hostname or ip address of the device. Open a ssh connection to the device and enter the following command: sudo keytool -importkeystore -deststorepass changeit -destkeystore /opt/eclipse/kura/security/cacerts.ks -srckeystore /tmp/aws-ssl.p12 -srcstoretype PKCS12 The command will ask for a password, enter the password defined when creating the aws-ssl.p12 file. Restart Kura to reload the keystore. 9. Setup a new cloud connection Click on Cloud Connections in the left panel, and setup a new cloud connection Click on the New Connection button at the top of the page and set the following parameters in the dialog: Cloud Connection Factory PID -> org.eclipse.kura.cloud.CloudService Cloud Connection Service PID -> org.eclipse.kura.cloud.CloudService-AWS Press the Create button to confirm and then select the newly created CloudService instance from the list. Set the broker URL in the MqttDataTransport-AWS tab, it can be obtained from the AWS IoT Web Console clicking on the Settings entry in the bottom left section of the page, the URL will look like the following: a1rm1xxxxxxxxx.iot.us-east-1.amazonaws.com The mqtts protocol must be used, the value for the broker-url field derived from the URL above is the following: mqtts://a1rm1xxxxxxxxx.iot.us-east-1.amazonaws.com:8883/ Clear the value of the username and password fields. Set a value for the topic.context.account-name and client-id . Assign an arbitrary account name to topic.context.account-name (for example aws-test ), this will be used by the CloudClient instances for building the topic structure. Enter the thing name in the client-id field (in this example kura-gateway ). In order for the previously added keys to be used for the SSL connection with the broker enter the Storage Alias defined in step 8.2 (e.g aws-ssl ) as value for the ssl.certificate.alias field. The setting lwt.topic under MqttDataTransport-AWS needs to be updated as well by entering a value not containing the $ character. This is required because of the fact that AWS IoT does not support topic names starting with $ (except for the $aws/ hierarchy). Press the Apply button in the top left section to commit the changes to the MqttDataTransport-AWS . Enter a name without the $ character for the topic.control-prefix setting in the CloudService-AWS tab, for example aws-control . The Kura CloudService uses some well-known topics to allow remote device management and to report device state information, this features are not supported by default by AWS IoT, the following settings can be applied in the CloudService-AWS tab in order to avoid sending unnecessary messages: republish.mqtt.birth.cert.on.gps.lock -> false republish.mqtt.birth.cert.on.modem.detect -> false enable.default.subscriptions -> false Click the Apply button to save the changes. 10. Connect to the cloud platform Make sure the AWS CloudService instance is selected from the list in the top section of the page and click on the Connect button, if the connection to AWS IoT platform succeeds the Status of the instance will be reported as Connected .","title":"Amazon AWS IoT™ platform"},{"location":"cloud-platform/kura-aws-cloud/#amazon-aws-iot-platform","text":"","title":"Amazon AWS IoT™ platform"},{"location":"cloud-platform/kura-aws-cloud/#overview","text":"This section provides a guide on connecting an Eclipse Kura\u2122 device to the Amazon AWS IoT platform.","title":"Overview"},{"location":"cloud-platform/kura-aws-cloud/#prerequisites","text":"In order to connect a device to Amazon AWS IoT Kura version 1.3 or greater is required. An Amazon AWS account is also needed.","title":"Prerequisites"},{"location":"cloud-platform/kura-aws-cloud/#device-registration","text":"The first step involves the registration of the new device on AWS, this operation can be done using the AWS Web Console or with the AWS CLI command line tool, in this guide the Web based console will be used.","title":"Device registration"},{"location":"cloud-platform/kura-aws-cloud/#1-access-the-aws-iot-management-console","text":"This can be done by logging in the AWS console and selecting IoT Core from the services list, in the Internet of Things section.","title":"1. Access the AWS IoT management console."},{"location":"cloud-platform/kura-aws-cloud/#2-create-a-default-policy-for-the-device","text":"This step involves creating a default policy for the new device, skip if an existing policy is already available. Access the main screen of the console and select Secure -> Policies from the left side menu and then press the Create button, in the top right area of the screen. Fill the form as follows and then press the Create button: Action -> iot:Connect, iot:Publish, iot:Subscribe, iot:Receive, iot:UpdateThingShadow, iot:GetThingShadow, iot:DeleteThingShadow Resource ARN -> * Effect -> Allow This will create a policy that allows a device to connect to the platform, publish/subscribe on any topic and manage its thing shadow .","title":"2. Create a default policy for the device."},{"location":"cloud-platform/kura-aws-cloud/#3-register-a-new-device","text":"Devices on the AWS IoT platform are called things , in order to register a new thing select Manage -> Things from the left side menu and then press the Create button, in the top right section of the screen. Select Create a single thing . Enter a name for the new device and then press the Next button, from now on kura-gateway will be used as the device name.","title":"3. Register a new device."},{"location":"cloud-platform/kura-aws-cloud/#4-create-a-new-certificate-for-the-device","text":"The AWS IoT platform uses SSL mutual authentication, for this reason it is necessary to download a public/private key pair for the device and a server certificate. Click on Create certificate to quickly generate a new certificate for the new device. Certificates can be managed later on by clicking on Secure -> Certificates , in the left part of the console.","title":"4. Create a new certificate for the device."},{"location":"cloud-platform/kura-aws-cloud/#5-download-the-device-ssl-keys","text":"You should see a screen like the following: Download the 3 files listed in the table and store them in a safe place, they will be needed later, also copy the link to the root CA for AWS IoT in order to be able to retrieve it later from the device. Press the Activate button, and then on Attach a policy .","title":"5. Download the device SSL keys."},{"location":"cloud-platform/kura-aws-cloud/#6-assign-the-default-policy-to-the-device","text":"Select the desired policy and then click on Register thing . A policy can also be attached to a certificate later on perforiming the following steps: Enter the device configuration section, by clicking on Manage -> Things and then clicking on the newly created device. Click on Security on the left panel and then click on the certificate entry (it is identified by an hex code), select Policies in the left menu, you should see this screen: Click on Actions in the top left section of the page and then click on Attach policy , select the default policy previously created and then press the Attach button.","title":"6. Assign the default policy to the device."},{"location":"cloud-platform/kura-aws-cloud/#device-configuration","text":"The following steps should be performed on the device, this guide is based on Kura 3.1.0 version and has been tested on a Raspberry PI 3.","title":"Device configuration"},{"location":"cloud-platform/kura-aws-cloud/#7-create-a-java-keystore-on-the-device","text":"The first step for using the device keys obtained at the previous step is to create a new Java keystore containing the Root Certificate used by the Amazon IoT platform, this can be done executing the following commands on the device: sudo mkdir /opt/eclipse/kura/security cd /opt/eclipse/kura/security curl https://www.amazontrust.com/repository/AmazonRootCA1.pem > /tmp/root-CA.pem sudo keytool -import -trustcacerts -alias aws -file /tmp/root-CA.pem -keystore cacerts.ks -storepass changeit If the last command reports that the certificate already exist in the system-wide store type yes to proceed. The code above will generate a new keystore with changeit as password, change it if needed.","title":"7. Create a Java keystore on the device."},{"location":"cloud-platform/kura-aws-cloud/#8-configure-the-ssl-parameters-using-the-kura-web-ui","text":"Open the Kura Web Console and enter select the Settings entry in the left side menu and then click on SSL Configuration , you should see this screen: Change the Keystore path parameter to /opt/eclipse/kura/security/cacerts.ks if needed. Change the settings in the form to match the screen above, set Default protocol to TLSv1.2 , enter changeit as Keystore Password (or the password defined at step 7). Warning Steps from 8.2 to 8.6 will not work on Kura 3.2.0 due to a known issue . On this version, private key and device certificate need to be manually added to the keystore using the command line. If you are running Kura 3.2.0, proceed with step 8.7. Open the Kura Web Console and enter select the Settings entry in the left side menu and then click on Device SSL Certificate , you should see this screen: Enter aws-ssl in the Storage Alias field. The private key needs to be converted to the PKCS8 format, this step can be performed executing the following command on a Linux or OSX based machine: openssl pkcs8 -topk8 -inform PEM -outform PEM -in xxxxxxxxxx-private.pem.key -out outKey.pem -nocrypt where xxxxxxxxxx-private.pem.key is the file containing the private key downloaded at step 4. Paste the contents of the obtained outKey.pem in the \"Private Key\" field. Paste the contents of xxxxxxxxxx-certificate.pem.crt in the Certificate field. You should see a screen like this Click the Apply button to confirm. Kura 3.2.0 only - manually import device certificate and private key into keystore. On the host machine, open a terminal window in the folder containing the files downloaded at step 5 and execute the following command: openssl pkcs12 -export -in xxxxxxxxxx-certificate.pem.crt -inkey xxxxxxxxxx-private.pem.key -name aws-ssl -out aws-ssl.p12 where xxxxxxxxxx-certificate.pem.crt is the original certificate downloaded from AWS and xxxxxxxxxx-private.pem.key is the private key. The command will ask for a password, define a new password. Copy the obtained aws-ssl.p12 file to the device into the /tmp folder using scp: scp ./aws-ssl.p12 pi@:/tmp Replacing with the hostname or ip address of the device. Open a ssh connection to the device and enter the following command: sudo keytool -importkeystore -deststorepass changeit -destkeystore /opt/eclipse/kura/security/cacerts.ks -srckeystore /tmp/aws-ssl.p12 -srcstoretype PKCS12 The command will ask for a password, enter the password defined when creating the aws-ssl.p12 file. Restart Kura to reload the keystore.","title":"8. Configure the SSL parameters using the Kura Web UI."},{"location":"cloud-platform/kura-aws-cloud/#9-setup-a-new-cloud-connection","text":"Click on Cloud Connections in the left panel, and setup a new cloud connection Click on the New Connection button at the top of the page and set the following parameters in the dialog: Cloud Connection Factory PID -> org.eclipse.kura.cloud.CloudService Cloud Connection Service PID -> org.eclipse.kura.cloud.CloudService-AWS Press the Create button to confirm and then select the newly created CloudService instance from the list. Set the broker URL in the MqttDataTransport-AWS tab, it can be obtained from the AWS IoT Web Console clicking on the Settings entry in the bottom left section of the page, the URL will look like the following: a1rm1xxxxxxxxx.iot.us-east-1.amazonaws.com The mqtts protocol must be used, the value for the broker-url field derived from the URL above is the following: mqtts://a1rm1xxxxxxxxx.iot.us-east-1.amazonaws.com:8883/ Clear the value of the username and password fields. Set a value for the topic.context.account-name and client-id . Assign an arbitrary account name to topic.context.account-name (for example aws-test ), this will be used by the CloudClient instances for building the topic structure. Enter the thing name in the client-id field (in this example kura-gateway ). In order for the previously added keys to be used for the SSL connection with the broker enter the Storage Alias defined in step 8.2 (e.g aws-ssl ) as value for the ssl.certificate.alias field. The setting lwt.topic under MqttDataTransport-AWS needs to be updated as well by entering a value not containing the $ character. This is required because of the fact that AWS IoT does not support topic names starting with $ (except for the $aws/ hierarchy). Press the Apply button in the top left section to commit the changes to the MqttDataTransport-AWS . Enter a name without the $ character for the topic.control-prefix setting in the CloudService-AWS tab, for example aws-control . The Kura CloudService uses some well-known topics to allow remote device management and to report device state information, this features are not supported by default by AWS IoT, the following settings can be applied in the CloudService-AWS tab in order to avoid sending unnecessary messages: republish.mqtt.birth.cert.on.gps.lock -> false republish.mqtt.birth.cert.on.modem.detect -> false enable.default.subscriptions -> false Click the Apply button to save the changes.","title":"9. Setup a new cloud connection"},{"location":"cloud-platform/kura-aws-cloud/#10-connect-to-the-cloud-platform","text":"Make sure the AWS CloudService instance is selected from the list in the top section of the page and click on the Connect button, if the connection to AWS IoT platform succeeds the Status of the instance will be reported as Connected .","title":"10. Connect to the cloud platform"},{"location":"cloud-platform/kura-azure/","text":"Azure IoT Hub\u2122 platform Starting from release 3.0, Eclipse Kura can connect to the Azure IoT Hub using the MQTT protocol. When doing so, Kura applications can send device-to-cloud messages. More information on the Azure IoT Hub and its support for the MQTT protocol can be found here . This document outlines how to configure and connect a Kura application to the Azure IoT Hub. Get Azure IoT Hub information In order to properly configure Kura to connect to IoT Hub, some information are needed. You will need the hostname of the Azure IoT Hub, referred below as {iothubhostname} , the Id and the SAS Token of the device, referred as {device_id} and {device_SAS_token} . The hostname is listed on the \"Overview\" tab on the IoT Hub main page, while the device ID is shown on the \"Device Explorer\" tab. Finally, the SAS token can be generated using the iothub-explorer application that can be found here . To install the application, type on a shell: npm install -g iothub-explorer Then start a new session on your IoT Hub instance (it will expire in 1 hour): iothub-explorer login \"{your-connection-string}\" where {your-connection-string} is the connection string of your IoT Hub instance. It can be found on the \"Shared access policies\" tab under \"Settings\". Select the \"iothubowner\" policy and a tab will appear with the \"Connection string\u2014primary key\" option. Then list your devices: iothub-explorer list and get the SAS token for the {device-name} device: iothub-explorer sas-token { device-name } Be aware that the SAS token will expire in 1 hour by default, but using \"-d\" option it is possible to set a custom expiration time. SSL certificates In order to connect to your IoT Hub instance, Kura should trust the remote broker through a SSL certificate. The simpler way to get the IotHub certificate is to run the following command on a shell: openssl s_client -showcerts -tls1 -connect { iothubhostname } :8883 The result is the SSL certificate chain. Copy all the certificates in the format: -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- and paste them in to the \"Server SSL Certificate\" tab under \"Settings\" in Kura. Then click the Apply button and restart Kura to update the keystore. Configuring a Kura Cloud Stack for Azure IoT Hub The Kura Gateway Administrative Console exposes all services necessary to configure a connection to the Azure IoT Hub. You can follow the steps outlined below to configure the connection to the Azure IoT Hub. The first step is to create a new Kura Cloud stack. From the Kura Gateway Administrative Console: Select Cloud Connections in the navigation on the left and click New Connection to create a new Cloud connection In the dialog, select org.eclipse.kura.cloud.CloudService as the Cloud Connection Factory PID Enter a Cloud Connection Service PID name like org.eclipse.kura.cloud.CloudService-Azure Press the Create button to create the new Cloud stack Now review and update the configuration of each Kura Cloud stack component as outline below. MqttDataTransport DataService CloudService MqttDataTransport Modify the service configuration parameters as follows: broker-url - defines the URL of the Azure IoT MQTT broker. The URL value should be set as mqtts://{iothubhostname}:8883/ Note An SSL connection (mqtts on port 8883) is required to connect to Azure IoT Hub\u2122. topic.context.account-name - insert devices as the MQTT topic prefix for the device-to-cloud and cloud-to-device messages username - insert {iothubhostname}/{device_id} as username for the MQTT connection password - insert {device_SAS_token} as password for the MQTT connection Note The format of the SAS Token is like: SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI} client-id - insert {device_id} as Client ID for the MQTT connection clean-session - make sure it is set to true lwt.topic - set the Will Topic to something #account-name/#client-id/messages/events/LWT You can keep the default values of the remaining parameters, so save your changes by clicking the Apply button. A screen capture of the MqttDataTransport configuration is shown below. DataService The majority of default settings in the DataService can be left unchanged. A screen capture of the DataService configuration is shown below. In order for Kura to connect to Azure IoT Hub on startup, the connect.auto-on-startup option must be set to true. If this value is changed from false to true, Kura will immediately begin the connection process. It is recommended that the CloudService and MqttDataTransport are configured before setting the connect.auto-on-startup option to true. Note Changing the value of connect.auto-on-startup from true to false will not disconnect the client from the broker. This setting simply implies that Kura will not automatically connect on the next start of Kura. CloudService The default settings for the CloudService should be modified as follow to allow a connection to Azure IoT Hub . topic.control-prefix - insert devices as the MQTT topic prefix for the device-to-cloud and cloud-to-device messages encode.gzip - should be set false to avoid compression of the message payloads republish.mqtt.birth.cert.on.gps.lock - should be set false to avoid sending additional messages on GPS position lock republish.mqtt.birth.cert.on.modem.detect - should be set false to avoid sending additional messages on cellular modem update enable.default.subscriptions - should be set false to avoid subscriptions on Kura control topics for cloud-to-device payload.encoding - should be set to Simple JSON The screen capture shown below displays the default settings for the CloudService. How to connect and disconnect from the cloud platform The status panel can be used to manually connect or disconnect the client while Kura is running. The main button toolbar has a connect and disconnect button that may be used to control connectivity. Note Connecting or disconnecting the client via the status panel has no impact on Kura automatically connecting at startup. This capability is only controlled via the connect.auto-on-startup DataService setting. Kura Application Connecting to Azure IoT Hub The Kura example publisher can be used to publish to the IoT Hub. The example configuration should be modified as follows. cloud.service.pid - insert the name of the new Kura Cloud stack, org.eclipse.kura.cloud.CloudService-Azure in this tutorial app.id - insert messages as application id publish.appTopic - insert events/ as publish topic This configuration allows the publication on the default messages/events endpoint on the IoT Hub\u2122.","title":"Azure IoT Hub™ platform"},{"location":"cloud-platform/kura-azure/#azure-iot-hub-platform","text":"Starting from release 3.0, Eclipse Kura can connect to the Azure IoT Hub using the MQTT protocol. When doing so, Kura applications can send device-to-cloud messages. More information on the Azure IoT Hub and its support for the MQTT protocol can be found here . This document outlines how to configure and connect a Kura application to the Azure IoT Hub.","title":"Azure IoT Hub™ platform"},{"location":"cloud-platform/kura-azure/#get-azure-iot-hub-information","text":"In order to properly configure Kura to connect to IoT Hub, some information are needed. You will need the hostname of the Azure IoT Hub, referred below as {iothubhostname} , the Id and the SAS Token of the device, referred as {device_id} and {device_SAS_token} . The hostname is listed on the \"Overview\" tab on the IoT Hub main page, while the device ID is shown on the \"Device Explorer\" tab. Finally, the SAS token can be generated using the iothub-explorer application that can be found here . To install the application, type on a shell: npm install -g iothub-explorer Then start a new session on your IoT Hub instance (it will expire in 1 hour): iothub-explorer login \"{your-connection-string}\" where {your-connection-string} is the connection string of your IoT Hub instance. It can be found on the \"Shared access policies\" tab under \"Settings\". Select the \"iothubowner\" policy and a tab will appear with the \"Connection string\u2014primary key\" option. Then list your devices: iothub-explorer list and get the SAS token for the {device-name} device: iothub-explorer sas-token { device-name } Be aware that the SAS token will expire in 1 hour by default, but using \"-d\" option it is possible to set a custom expiration time.","title":"Get Azure IoT Hub information"},{"location":"cloud-platform/kura-azure/#ssl-certificates","text":"In order to connect to your IoT Hub instance, Kura should trust the remote broker through a SSL certificate. The simpler way to get the IotHub certificate is to run the following command on a shell: openssl s_client -showcerts -tls1 -connect { iothubhostname } :8883 The result is the SSL certificate chain. Copy all the certificates in the format: -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- and paste them in to the \"Server SSL Certificate\" tab under \"Settings\" in Kura. Then click the Apply button and restart Kura to update the keystore.","title":"SSL certificates"},{"location":"cloud-platform/kura-azure/#configuring-a-kura-cloud-stack-for-azure-iot-hub","text":"The Kura Gateway Administrative Console exposes all services necessary to configure a connection to the Azure IoT Hub. You can follow the steps outlined below to configure the connection to the Azure IoT Hub. The first step is to create a new Kura Cloud stack. From the Kura Gateway Administrative Console: Select Cloud Connections in the navigation on the left and click New Connection to create a new Cloud connection In the dialog, select org.eclipse.kura.cloud.CloudService as the Cloud Connection Factory PID Enter a Cloud Connection Service PID name like org.eclipse.kura.cloud.CloudService-Azure Press the Create button to create the new Cloud stack Now review and update the configuration of each Kura Cloud stack component as outline below. MqttDataTransport DataService CloudService","title":"Configuring a Kura Cloud Stack for Azure IoT Hub"},{"location":"cloud-platform/kura-azure/#mqttdatatransport","text":"Modify the service configuration parameters as follows: broker-url - defines the URL of the Azure IoT MQTT broker. The URL value should be set as mqtts://{iothubhostname}:8883/ Note An SSL connection (mqtts on port 8883) is required to connect to Azure IoT Hub\u2122. topic.context.account-name - insert devices as the MQTT topic prefix for the device-to-cloud and cloud-to-device messages username - insert {iothubhostname}/{device_id} as username for the MQTT connection password - insert {device_SAS_token} as password for the MQTT connection Note The format of the SAS Token is like: SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI} client-id - insert {device_id} as Client ID for the MQTT connection clean-session - make sure it is set to true lwt.topic - set the Will Topic to something #account-name/#client-id/messages/events/LWT You can keep the default values of the remaining parameters, so save your changes by clicking the Apply button. A screen capture of the MqttDataTransport configuration is shown below.","title":"MqttDataTransport"},{"location":"cloud-platform/kura-azure/#dataservice","text":"The majority of default settings in the DataService can be left unchanged. A screen capture of the DataService configuration is shown below. In order for Kura to connect to Azure IoT Hub on startup, the connect.auto-on-startup option must be set to true. If this value is changed from false to true, Kura will immediately begin the connection process. It is recommended that the CloudService and MqttDataTransport are configured before setting the connect.auto-on-startup option to true. Note Changing the value of connect.auto-on-startup from true to false will not disconnect the client from the broker. This setting simply implies that Kura will not automatically connect on the next start of Kura.","title":"DataService"},{"location":"cloud-platform/kura-azure/#cloudservice","text":"The default settings for the CloudService should be modified as follow to allow a connection to Azure IoT Hub . topic.control-prefix - insert devices as the MQTT topic prefix for the device-to-cloud and cloud-to-device messages encode.gzip - should be set false to avoid compression of the message payloads republish.mqtt.birth.cert.on.gps.lock - should be set false to avoid sending additional messages on GPS position lock republish.mqtt.birth.cert.on.modem.detect - should be set false to avoid sending additional messages on cellular modem update enable.default.subscriptions - should be set false to avoid subscriptions on Kura control topics for cloud-to-device payload.encoding - should be set to Simple JSON The screen capture shown below displays the default settings for the CloudService.","title":"CloudService"},{"location":"cloud-platform/kura-azure/#how-to-connect-and-disconnect-from-the-cloud-platform","text":"The status panel can be used to manually connect or disconnect the client while Kura is running. The main button toolbar has a connect and disconnect button that may be used to control connectivity. Note Connecting or disconnecting the client via the status panel has no impact on Kura automatically connecting at startup. This capability is only controlled via the connect.auto-on-startup DataService setting.","title":"How to connect and disconnect from the cloud platform"},{"location":"cloud-platform/kura-azure/#kura-application-connecting-to-azure-iot-hub","text":"The Kura example publisher can be used to publish to the IoT Hub. The example configuration should be modified as follows. cloud.service.pid - insert the name of the new Kura Cloud stack, org.eclipse.kura.cloud.CloudService-Azure in this tutorial app.id - insert messages as application id publish.appTopic - insert events/ as publish topic This configuration allows the publication on the default messages/events endpoint on the IoT Hub\u2122.","title":"Kura Application Connecting to Azure IoT Hub"},{"location":"cloud-platform/kura-ec-cloud/","text":"Eurotech Everyware Cloud\u2122 platform Everyware Cloud provides an easy mechanism for connecting cloud-ready devices to IT systems and/or applications; therefore, connecting to Everyware Cloud is an important step in creating and maintaining a complete M2M application. Information on Everyware Cloud and its features can be found here . This document outlines how to connect to Everyware Cloud using the Kura Gateway Administrative Console. Using the Kura Gateway Administrative Console The Kura Gateway Administrative Console exposes all services necessary for connecting to Everyware Cloud. The reference links listed below outline each service involved in the Everyware Cloud connection. It is recommended that each section be reviewed. CloudService DataService MqttDataTransport CloudService The default settings for the CloudService are typically adequate for connecting to Everyware Cloud. The screen capture shown below displays the default settings for the CloudService. For details about each setting, please refer to CloudService . Warning The \" Simple JSON \" payload encoding is not supported by Everyware Cloud. Use the default \" Kura Protobuf \" encoding instead. DataService The majority of default settings in the DataService can be left unchanged. A screen capture of the DataService configuration is shown below. For complete details about the DataService configuration parameters, please refer to DataService . In order for Kura to connect to Everyware Cloud on startup, the connect.auto-on-startup option must be set to true . If this value is changed from false to true , Kura will immediately begin the connection process. It is recommended that the CloudService and MqttDataTransport are configured before setting the connect.auto-on-startup option to true . Note Changing the value of connect.auto-on-startup from true to false will not disconnect the client from the broker. This setting simply implies that Kura will not automatically connect on the next start of Kura. MqttDataTransport While the majority of default settings in the MqttDataTransport can be left unchanged, the following parameters must be modified: broker-url - defines the MQTT broker URL that was provided when the Eurotech Everyware Cloud account was established. Information on how to obtain the broker URL can be found here . In the MqttDataTransport configuration screen capture shown below, the broker-url is mqtt://broker-sbx.everyware.io:1883 topic.context.account-name - defines the account name of the account to which the device is attempting to connect. In the MqttDataTransport configuration screen capture shown below, the account name is account-name username - identifies the user to be used when creating the connection. In the MqttDataTransport configuration screen capture shown below, the username is username . Note When connecting to Everyware Cloud, the username must have proper permissions. Information on users and permissions can be found here . For complete details about the MqttDataTransport configuration parameters, please refer to MqttDataTransport . Connect/Disconnect The status panel can be used to manually connect or disconnect the client while Kura is running. The main button toolbar has a connect and disconnect button that may be used to control connectivity. Note Connecting or disconnecting the client via the status panel has no impact on Kura automatically connecting at startup. This capability is only controlled via the connect.auto-on-startup DataService setting.","title":"Eurotech Everyware Cloud™ platform"},{"location":"cloud-platform/kura-ec-cloud/#eurotech-everyware-cloud-platform","text":"Everyware Cloud provides an easy mechanism for connecting cloud-ready devices to IT systems and/or applications; therefore, connecting to Everyware Cloud is an important step in creating and maintaining a complete M2M application. Information on Everyware Cloud and its features can be found here . This document outlines how to connect to Everyware Cloud using the Kura Gateway Administrative Console.","title":"Eurotech Everyware Cloud™ platform"},{"location":"cloud-platform/kura-ec-cloud/#using-the-kura-gateway-administrative-console","text":"The Kura Gateway Administrative Console exposes all services necessary for connecting to Everyware Cloud. The reference links listed below outline each service involved in the Everyware Cloud connection. It is recommended that each section be reviewed. CloudService DataService MqttDataTransport","title":"Using the Kura Gateway Administrative Console"},{"location":"cloud-platform/kura-ec-cloud/#cloudservice","text":"The default settings for the CloudService are typically adequate for connecting to Everyware Cloud. The screen capture shown below displays the default settings for the CloudService. For details about each setting, please refer to CloudService . Warning The \" Simple JSON \" payload encoding is not supported by Everyware Cloud. Use the default \" Kura Protobuf \" encoding instead.","title":"CloudService"},{"location":"cloud-platform/kura-ec-cloud/#dataservice","text":"The majority of default settings in the DataService can be left unchanged. A screen capture of the DataService configuration is shown below. For complete details about the DataService configuration parameters, please refer to DataService . In order for Kura to connect to Everyware Cloud on startup, the connect.auto-on-startup option must be set to true . If this value is changed from false to true , Kura will immediately begin the connection process. It is recommended that the CloudService and MqttDataTransport are configured before setting the connect.auto-on-startup option to true . Note Changing the value of connect.auto-on-startup from true to false will not disconnect the client from the broker. This setting simply implies that Kura will not automatically connect on the next start of Kura.","title":"DataService"},{"location":"cloud-platform/kura-ec-cloud/#mqttdatatransport","text":"While the majority of default settings in the MqttDataTransport can be left unchanged, the following parameters must be modified: broker-url - defines the MQTT broker URL that was provided when the Eurotech Everyware Cloud account was established. Information on how to obtain the broker URL can be found here . In the MqttDataTransport configuration screen capture shown below, the broker-url is mqtt://broker-sbx.everyware.io:1883 topic.context.account-name - defines the account name of the account to which the device is attempting to connect. In the MqttDataTransport configuration screen capture shown below, the account name is account-name username - identifies the user to be used when creating the connection. In the MqttDataTransport configuration screen capture shown below, the username is username . Note When connecting to Everyware Cloud, the username must have proper permissions. Information on users and permissions can be found here . For complete details about the MqttDataTransport configuration parameters, please refer to MqttDataTransport .","title":"MqttDataTransport"},{"location":"cloud-platform/kura-ec-cloud/#connectdisconnect","text":"The status panel can be used to manually connect or disconnect the client while Kura is running. The main button toolbar has a connect and disconnect button that may be used to control connectivity. Note Connecting or disconnecting the client via the status panel has no impact on Kura automatically connecting at startup. This capability is only controlled via the connect.auto-on-startup DataService setting.","title":"Connect/Disconnect"},{"location":"cloud-platform/kura-hono/","text":"Eclipse Hono\u2122 platform Eclipse Hono\u2122 provides remote service interfaces for connecting large numbers of IoT devices to a back end and interacting with them in a uniform way regardless of the device communication protocol. More information can be found here . This document outlines how to connect to Eclipse Hono using the Kura Gateway Administrative Console. Using the Kura Gateway Administrative Console The Kura Gateway Administrative Console exposes all services necessary for connecting to Eclipse Hono. First of all, in the Cloud Connections section, a new Hono-enabled connection needs to be setup. From the Cloud Connections section, the user needs to create a new connection: by specifying a valid PID: The result should be like the one depicted in the following image: The reference links listed below outline each service involved in the cloud connection. It is recommended that each section be reviewed. CloudService DataService MqttDataTransport CloudService The default settings for the CloudService are typically adequate for connecting to a Hono instance. The screen capture shown below displays the default settings for the CloudService. For details about each setting, please refer to CloudService . DataService The majority of default settings in the DataService can be left unchanged. A screen capture of the DataService configuration is shown below. For complete details about the DataService configuration parameters, please refer to DataService . In order for Kura to connect to Eclipse Hono on startup, the connect.auto-on-startup option must be set to true . If this value is changed from false to true , Kura will immediately begin the connection process. It is recommended that the CloudService and MqttDataTransport are configured before setting the connect.auto-on-startup option to true . Note Changing the value of connect.auto-on-startup from true to false will not disconnect the client from the broker. This setting simply implies that Kura will not automatically connect on the next start of Kura. MqttDataTransport While the majority of default settings in the MqttDataTransport can be left unchanged, the following parameters must be modified: broker-url - defines the MQTT broker URL that was provided when the Eurotech Everyware Cloud account was established. In the MqttDataTransport configuration screen capture shown below, the broker-url is mqtt://broker-url:1883 topic.context.account-name - defines the account name of the account to which the device is attempting to connect. In the MqttDataTransport configuration screen capture shown below, the account name is account-name username - identifies the user to be used when creating the connection. In the MqttDataTransport configuration screen capture shown below, the username is username . For complete details about the MqttDataTransport configuration parameters, please refer to MqttDataTransport . Connect/Disconnect The status panel can be used to manually connect or disconnect the client while Kura is running. The main button toolbar has a connect and disconnect button that may be used to control connectivity. Note Connecting or disconnecting the client via the status panel has no impact on Kura automatically connecting at startup. This capability is only controlled via the connect.auto-on-startup DataService setting.","title":"Eclipse Hono™ platform"},{"location":"cloud-platform/kura-hono/#eclipse-hono-platform","text":"Eclipse Hono\u2122 provides remote service interfaces for connecting large numbers of IoT devices to a back end and interacting with them in a uniform way regardless of the device communication protocol. More information can be found here . This document outlines how to connect to Eclipse Hono using the Kura Gateway Administrative Console.","title":"Eclipse Hono™ platform"},{"location":"cloud-platform/kura-hono/#using-the-kura-gateway-administrative-console","text":"The Kura Gateway Administrative Console exposes all services necessary for connecting to Eclipse Hono. First of all, in the Cloud Connections section, a new Hono-enabled connection needs to be setup. From the Cloud Connections section, the user needs to create a new connection: by specifying a valid PID: The result should be like the one depicted in the following image: The reference links listed below outline each service involved in the cloud connection. It is recommended that each section be reviewed. CloudService DataService MqttDataTransport","title":"Using the Kura Gateway Administrative Console"},{"location":"cloud-platform/kura-hono/#cloudservice","text":"The default settings for the CloudService are typically adequate for connecting to a Hono instance. The screen capture shown below displays the default settings for the CloudService. For details about each setting, please refer to CloudService .","title":"CloudService"},{"location":"cloud-platform/kura-hono/#dataservice","text":"The majority of default settings in the DataService can be left unchanged. A screen capture of the DataService configuration is shown below. For complete details about the DataService configuration parameters, please refer to DataService . In order for Kura to connect to Eclipse Hono on startup, the connect.auto-on-startup option must be set to true . If this value is changed from false to true , Kura will immediately begin the connection process. It is recommended that the CloudService and MqttDataTransport are configured before setting the connect.auto-on-startup option to true . Note Changing the value of connect.auto-on-startup from true to false will not disconnect the client from the broker. This setting simply implies that Kura will not automatically connect on the next start of Kura.","title":"DataService"},{"location":"cloud-platform/kura-hono/#mqttdatatransport","text":"While the majority of default settings in the MqttDataTransport can be left unchanged, the following parameters must be modified: broker-url - defines the MQTT broker URL that was provided when the Eurotech Everyware Cloud account was established. In the MqttDataTransport configuration screen capture shown below, the broker-url is mqtt://broker-url:1883 topic.context.account-name - defines the account name of the account to which the device is attempting to connect. In the MqttDataTransport configuration screen capture shown below, the account name is account-name username - identifies the user to be used when creating the connection. In the MqttDataTransport configuration screen capture shown below, the username is username . For complete details about the MqttDataTransport configuration parameters, please refer to MqttDataTransport .","title":"MqttDataTransport"},{"location":"cloud-platform/kura-hono/#connectdisconnect","text":"The status panel can be used to manually connect or disconnect the client while Kura is running. The main button toolbar has a connect and disconnect button that may be used to control connectivity. Note Connecting or disconnecting the client via the status panel has no impact on Kura automatically connecting at startup. This capability is only controlled via the connect.auto-on-startup DataService setting.","title":"Connect/Disconnect"},{"location":"cloud-platform/kura-kapua/","text":"Eclipse Kapua\u2122 platform Eclipse Kapua\u2122 is a modular platform providing the services required to manage IoT gateways and smart edge devices. Kapua provides a core integration framework and an initial set of core IoT services including a device registry, device management services, messaging services, data management, and application enablement. More information can be found here . This document outlines how to connect to Eclipse Kapua using the Kura Gateway Administrative Console. Using the Kura Gateway Administrative Console The Kura Gateway Administrative Console exposes all services necessary for connecting to Eclipse Kapua. The reference links listed below outline each service involved in the cloud connection. It is recommended that each section be reviewed. CloudService DataService MqttDataTransport CloudService The default settings for the CloudService are typically adequate for connecting to a Kapua instance. The screen capture shown below displays the default settings for the CloudService. For details about each setting, please refer to CloudService . Warning The \" Simple JSON \" payload encoding is not supported by Kapua. Use the default \" Kura Protobuf \" encoding instead. DataService The majority of default settings in the DataService can be left unchanged. A screen capture of the DataService configuration is shown below. For complete details about the DataService configuration parameters, please refer to DataService . In order for Kura to connect to Eclipse Kapua on startup, the connect.auto-on-startup option must be set to true . If this value is changed from false to true , Kura will immediately begin the connection process. It is recommended that the CloudService and MqttDataTransport are configured before setting the connect.auto-on-startup option to true . Note Changing the value of connect.auto-on-startup from true to false will not disconnect the client from the broker. This setting simply implies that Kura will not automatically connect on the next start of Kura. MqttDataTransport While the majority of default settings in the MqttDataTransport can be left unchanged, the following parameters must be modified: broker-url - defines the MQTT broker URL that was provided when the Kapua account was established. topic.context.account-name - defines the account name of the account to which the device is attempting to connect. In the MqttDataTransport configuration screen capture shown below, the account name is account-name username - identifies the user to be used when creating the connection. In the MqttDataTransport configuration screen capture shown below, the username is username . For complete details about the MqttDataTransport configuration parameters, please refer to MqttDataTransport . Connect/Disconnect The status panel can be used to manually connect or disconnect the client while Kura is running. The main button toolbar has a connect and disconnect button that may be used to control connectivity. Note Connecting or disconnecting the client via the status panel has no impact on Kura automatically connecting at startup. This capability is only controlled via the connect.auto-on-startup DataService setting.","title":"Eclipse Kapua™ platform"},{"location":"cloud-platform/kura-kapua/#eclipse-kapua-platform","text":"Eclipse Kapua\u2122 is a modular platform providing the services required to manage IoT gateways and smart edge devices. Kapua provides a core integration framework and an initial set of core IoT services including a device registry, device management services, messaging services, data management, and application enablement. More information can be found here . This document outlines how to connect to Eclipse Kapua using the Kura Gateway Administrative Console.","title":"Eclipse Kapua™ platform"},{"location":"cloud-platform/kura-kapua/#using-the-kura-gateway-administrative-console","text":"The Kura Gateway Administrative Console exposes all services necessary for connecting to Eclipse Kapua. The reference links listed below outline each service involved in the cloud connection. It is recommended that each section be reviewed. CloudService DataService MqttDataTransport","title":"Using the Kura Gateway Administrative Console"},{"location":"cloud-platform/kura-kapua/#cloudservice","text":"The default settings for the CloudService are typically adequate for connecting to a Kapua instance. The screen capture shown below displays the default settings for the CloudService. For details about each setting, please refer to CloudService . Warning The \" Simple JSON \" payload encoding is not supported by Kapua. Use the default \" Kura Protobuf \" encoding instead.","title":"CloudService"},{"location":"cloud-platform/kura-kapua/#dataservice","text":"The majority of default settings in the DataService can be left unchanged. A screen capture of the DataService configuration is shown below. For complete details about the DataService configuration parameters, please refer to DataService . In order for Kura to connect to Eclipse Kapua on startup, the connect.auto-on-startup option must be set to true . If this value is changed from false to true , Kura will immediately begin the connection process. It is recommended that the CloudService and MqttDataTransport are configured before setting the connect.auto-on-startup option to true . Note Changing the value of connect.auto-on-startup from true to false will not disconnect the client from the broker. This setting simply implies that Kura will not automatically connect on the next start of Kura.","title":"DataService"},{"location":"cloud-platform/kura-kapua/#mqttdatatransport","text":"While the majority of default settings in the MqttDataTransport can be left unchanged, the following parameters must be modified: broker-url - defines the MQTT broker URL that was provided when the Kapua account was established. topic.context.account-name - defines the account name of the account to which the device is attempting to connect. In the MqttDataTransport configuration screen capture shown below, the account name is account-name username - identifies the user to be used when creating the connection. In the MqttDataTransport configuration screen capture shown below, the username is username . For complete details about the MqttDataTransport configuration parameters, please refer to MqttDataTransport .","title":"MqttDataTransport"},{"location":"cloud-platform/kura-kapua/#connectdisconnect","text":"The status panel can be used to manually connect or disconnect the client while Kura is running. The main button toolbar has a connect and disconnect button that may be used to control connectivity. Note Connecting or disconnecting the client via the status panel has no impact on Kura automatically connecting at startup. This capability is only controlled via the connect.auto-on-startup DataService setting.","title":"Connect/Disconnect"},{"location":"cloud-platform/apache-camel-integration/kura-camel-app/","text":"Apache Camel\u2122 as a Kura application As of 2.1.0 Kura provides a set of different ways to implement an application backed by Camel: Simple XML route configuration Custom XML route configuration Custom Java DSL definition Kura cloud endpoint Kura provides a special \"Kura cloud endpoint\" which allows to publish or subscribe to the Kura Cloud API. The default component name for this component is kura-cloud but it may be overridden in the following use cases. The default component will only be registered once the default Kura Cloud API is registered with OSGi. This instance is registered with the OSGi property kura.service.pid=org.eclipse.kura.cloud.CloudService . If you want to publish to a different cloud service instance you can either manually register a new instance of this endpoint, or e.g. use a functionality like the Simple XML router provides: also see selecting a cloud service . Endpoint URI The URI syntax of the endpoint is (assuming the default component name): kura-cloud:appid/topic . Where appid is the application ID registered with the Cloud API and topic is the topic to use. The following URI parameters are supported by the endpoint: Name Type Default Description applicationId String From URI path The application ID used with the Cloud API topic String From URI path The default topic name to publish/subscribe to when no header value is specified qos Integer 0 The QoS value when publishing to MQTT retain Boolean false The default retain flag when publishing to MQTT priority Integer 5 The default priority value control Boolean false Whether to publish/subscribe on the control or data topic hierarchy deviceId String empty The default device ID when publishing/subscribing to control topics The following header fields are supported. If a value is not set when publishing it is taken from the endpoint configuration: Name Type Description CamelKuraCloudService.topic String The name of the topic to publish to or from which the message was received CamelKuraCloudService.qos Integer The QoS to use when publishing to MQTT CamelKuraCloudService.retain Boolean The value of the retain flag when publishing to MQTT CamelKuraCloudService.control Boolean Whether to publish/subscribe on the control or data topic hierarchy CamelKuraCloudService.deviceId String The device ID when publishing to control topics Cloud to cloud messaging As already described, header values override the endpoint settings. This allows for a finer grained control with Camel messaging. However this can cause unexpected behavior when two Cloud API endpoints are bridged. Camel can received from a Cloud endpoint but also publish to it. Now it is possible to write Camel routes with exchange messages, receiving from one Cloud API, pushing to another. ------------------- ------------------- | Cloud Service A | <---> | Cloud Service B | ------------------- ------------------- Which could result in a Camel route XML like: However the Consumer (from) would set the topic header value with the topic name it received the message from. And the Producer (to) would get its topic from the URI overriden by that header value. In order to fix this behavior the header field has to be cleared before publishing: Simple XML routes Eclipse Kura 2.1.0 introduces a new \"out-of-the-box\" component which allows to configure a set of XML based routes. The component is called \"Camel XML router\" and can be configured with a simple set of XML routes. The following example logs all messages received on the topic foo/bar to a logger named MESSAGE_FROM_CLOUD : But it is also possible to generate data and push to upstream to the cloud service: This example to run a timer named \"foo\" every second. It uses the \"Payload Factory\" bean, which is pre-registered, to create a new payload structure and then append a second element to it. The output is first sent to a logger and then to the cloud source. Defining dependencies on components It is possible to use the Web UI to define a list of Camel components which must be present in order for this configuration to work. For example if the routes make use of the \"milo-server\" adapter for providing OPC UA support then \"milo-server\" can be added and the setup will wait for this component to be registered with OSGi before the Camel context gets started. The field contains a list of comma separated component names: e.g. milo-server, timer, log Selecting a cloud service It is also possible to define a map of cloud services which will be available for upstream connectivity. This makes use of Kura's \"multi cloud client\" feature. CloudService instances will get mapped from either a Kura Service PID ( kura.service.pid , as shown in the Web UI) or a full OSGi filter. The string is a comma seperated, key=value string, where the key is the name of the Camel cloud the instance will be registered as and the value is the Kura service PID or the OSGi filter string. For example: cloud=org.eclipse.kura.cloud.CloudService, cloud-2=foobar Custom Camel routers If a standard XML route configuration is not enough then it is possible to use XML routes in combination with a custom OSGi bundle or a Java DSL based Camel approach. For this to work a Kura development setup is required, please see Getting started for more information. The implementation of such Camel components follow the standard Kura guides for developing components, like, for example, the ConfigurableComponent pattern. This section only describes the Camel specifics. Of course it is also possible to follow a very simple approach and directly use the Camel OSGi functionalities like org.apache.camel.core.osgi.OsgiDefaultCamelContext . Note Kura currently doesn't support the OSGi Blueprint approach Kura support for Camel is split up in two layers. There is a more basic support, which helps in running a raw Camel router. This is CamelRunner which is located in the package org.eclipse.kura.camel.router . And then there are a few abstract basic components in the package org.eclipse.kura.camel.component which help in creating Kura components based on Camel. Camel components The base classes in org.eclipse.kura.camel.component are intended to help creating new OSGi DS components base on Camel. XML based component For an XML based approach which can be configured through the Kura ConfigurationService the base class AbstractXmlCamelComponent can be used. The constructor expectes the name of a property which will contain the Camel XML router information when it gets configured through the configuration service. It will automatically parse and apply the Camel routes. The method void beforeStart(CamelContext camelContext) may be used in order to configure the Camel context before it gets started. Every time the routes get updated using the modified(Map) method, the route XML will be re-parsed and routes will be added, removed or updated according to the new XML. Java DSL based component In order to create a Java DSL based router setup the base class AbstractJavaCamelComponent may be used, which implements and RouteBuilder class, a simple setup might look like: import org.eclipse.kura.camel.component.AbstractJavaCamelComponent ; class MyRouter extends AbstractJavaCamelComponent { public void configure () throws Exception { from ( \"direct:test\" ) . to ( \"mock:test\" ); } } Using the CamelRunner The CamelRunner class is not derived from any OSGi or Kura base class and can be used in scenarios where more flexibility is required. It allows to define a set of pre-requisites for the Camel context. It is for example possible to define a dependency on a Kura cloud service instance and a Camel component provider. Once the runner is started it will listen for OSGi services resolving those dependencies and then starting up the Camel context. The following example shows how to set up a Camel context using the CamelRunner : // create a new camel Builder Builder builder = new CamelRunner . Builder (); // add service dependency builder . cloudService ( \"kura.service.pid\" , \"my.cloud.service.pid\" ); // add Camel component dependency to 'milo-server' builder . requireComponent ( \"milo-server\" ); CamelRunner runner = builder . build (); // set routes runner . setRoutes ( new RouteBuilder () { public void configure () throws Exception { from ( \"direct:test\" ) . to ( \"mock:test\" ); } } ); // set routes runner . start (); It is also possible to later update routes with a call to setRoutes : // maybe update routes at a later time runner . setRoutes ( /* different routes */ ); Examples The following examples can help in getting started. Kura Camel example publisher The Camel example publisher ( org.eclipse.kura.example.camel.publisher ) can be used as an reference for starting. The final OSGi bundle can be dropped into a Kura application an be started. It allows to configure dynamically during runtime and is capable of switching CloudService instances dynamically. Kura Camel quickstart The Camel quickstart project ( org.eclipse.kura.example.camel.quickstart ) shows two components, Java and XML based, working together. The bundle can also be dropped into Kura for testing. Kura Camel aggregation The Camel quickstart project ( org.eclipse.kura.example.camel.aggregation ) shows a simple data aggregation pattern with Camel by processing data and publishing the result.","title":"Apache Camel™ as application"},{"location":"cloud-platform/apache-camel-integration/kura-camel-app/#apache-camel-as-a-kura-application","text":"As of 2.1.0 Kura provides a set of different ways to implement an application backed by Camel: Simple XML route configuration Custom XML route configuration Custom Java DSL definition","title":"Apache Camel™ as a Kura application"},{"location":"cloud-platform/apache-camel-integration/kura-camel-app/#kura-cloud-endpoint","text":"Kura provides a special \"Kura cloud endpoint\" which allows to publish or subscribe to the Kura Cloud API. The default component name for this component is kura-cloud but it may be overridden in the following use cases. The default component will only be registered once the default Kura Cloud API is registered with OSGi. This instance is registered with the OSGi property kura.service.pid=org.eclipse.kura.cloud.CloudService . If you want to publish to a different cloud service instance you can either manually register a new instance of this endpoint, or e.g. use a functionality like the Simple XML router provides: also see selecting a cloud service .","title":"Kura cloud endpoint"},{"location":"cloud-platform/apache-camel-integration/kura-camel-app/#endpoint-uri","text":"The URI syntax of the endpoint is (assuming the default component name): kura-cloud:appid/topic . Where appid is the application ID registered with the Cloud API and topic is the topic to use. The following URI parameters are supported by the endpoint: Name Type Default Description applicationId String From URI path The application ID used with the Cloud API topic String From URI path The default topic name to publish/subscribe to when no header value is specified qos Integer 0 The QoS value when publishing to MQTT retain Boolean false The default retain flag when publishing to MQTT priority Integer 5 The default priority value control Boolean false Whether to publish/subscribe on the control or data topic hierarchy deviceId String empty The default device ID when publishing/subscribing to control topics The following header fields are supported. If a value is not set when publishing it is taken from the endpoint configuration: Name Type Description CamelKuraCloudService.topic String The name of the topic to publish to or from which the message was received CamelKuraCloudService.qos Integer The QoS to use when publishing to MQTT CamelKuraCloudService.retain Boolean The value of the retain flag when publishing to MQTT CamelKuraCloudService.control Boolean Whether to publish/subscribe on the control or data topic hierarchy CamelKuraCloudService.deviceId String The device ID when publishing to control topics","title":"Endpoint URI"},{"location":"cloud-platform/apache-camel-integration/kura-camel-app/#cloud-to-cloud-messaging","text":"As already described, header values override the endpoint settings. This allows for a finer grained control with Camel messaging. However this can cause unexpected behavior when two Cloud API endpoints are bridged. Camel can received from a Cloud endpoint but also publish to it. Now it is possible to write Camel routes with exchange messages, receiving from one Cloud API, pushing to another. ------------------- ------------------- | Cloud Service A | <---> | Cloud Service B | ------------------- ------------------- Which could result in a Camel route XML like: However the Consumer (from) would set the topic header value with the topic name it received the message from. And the Producer (to) would get its topic from the URI overriden by that header value. In order to fix this behavior the header field has to be cleared before publishing: ","title":"Cloud to cloud messaging"},{"location":"cloud-platform/apache-camel-integration/kura-camel-app/#simple-xml-routes","text":"Eclipse Kura 2.1.0 introduces a new \"out-of-the-box\" component which allows to configure a set of XML based routes. The component is called \"Camel XML router\" and can be configured with a simple set of XML routes. The following example logs all messages received on the topic foo/bar to a logger named MESSAGE_FROM_CLOUD : But it is also possible to generate data and push to upstream to the cloud service: This example to run a timer named \"foo\" every second. It uses the \"Payload Factory\" bean, which is pre-registered, to create a new payload structure and then append a second element to it. The output is first sent to a logger and then to the cloud source.","title":"Simple XML routes"},{"location":"cloud-platform/apache-camel-integration/kura-camel-app/#defining-dependencies-on-components","text":"It is possible to use the Web UI to define a list of Camel components which must be present in order for this configuration to work. For example if the routes make use of the \"milo-server\" adapter for providing OPC UA support then \"milo-server\" can be added and the setup will wait for this component to be registered with OSGi before the Camel context gets started. The field contains a list of comma separated component names: e.g. milo-server, timer, log","title":"Defining dependencies on components"},{"location":"cloud-platform/apache-camel-integration/kura-camel-app/#selecting-a-cloud-service","text":"It is also possible to define a map of cloud services which will be available for upstream connectivity. This makes use of Kura's \"multi cloud client\" feature. CloudService instances will get mapped from either a Kura Service PID ( kura.service.pid , as shown in the Web UI) or a full OSGi filter. The string is a comma seperated, key=value string, where the key is the name of the Camel cloud the instance will be registered as and the value is the Kura service PID or the OSGi filter string. For example: cloud=org.eclipse.kura.cloud.CloudService, cloud-2=foobar","title":"Selecting a cloud service"},{"location":"cloud-platform/apache-camel-integration/kura-camel-app/#custom-camel-routers","text":"If a standard XML route configuration is not enough then it is possible to use XML routes in combination with a custom OSGi bundle or a Java DSL based Camel approach. For this to work a Kura development setup is required, please see Getting started for more information. The implementation of such Camel components follow the standard Kura guides for developing components, like, for example, the ConfigurableComponent pattern. This section only describes the Camel specifics. Of course it is also possible to follow a very simple approach and directly use the Camel OSGi functionalities like org.apache.camel.core.osgi.OsgiDefaultCamelContext . Note Kura currently doesn't support the OSGi Blueprint approach Kura support for Camel is split up in two layers. There is a more basic support, which helps in running a raw Camel router. This is CamelRunner which is located in the package org.eclipse.kura.camel.router . And then there are a few abstract basic components in the package org.eclipse.kura.camel.component which help in creating Kura components based on Camel.","title":"Custom Camel routers"},{"location":"cloud-platform/apache-camel-integration/kura-camel-app/#camel-components","text":"The base classes in org.eclipse.kura.camel.component are intended to help creating new OSGi DS components base on Camel.","title":"Camel components"},{"location":"cloud-platform/apache-camel-integration/kura-camel-app/#xml-based-component","text":"For an XML based approach which can be configured through the Kura ConfigurationService the base class AbstractXmlCamelComponent can be used. The constructor expectes the name of a property which will contain the Camel XML router information when it gets configured through the configuration service. It will automatically parse and apply the Camel routes. The method void beforeStart(CamelContext camelContext) may be used in order to configure the Camel context before it gets started. Every time the routes get updated using the modified(Map) method, the route XML will be re-parsed and routes will be added, removed or updated according to the new XML.","title":"XML based component"},{"location":"cloud-platform/apache-camel-integration/kura-camel-app/#java-dsl-based-component","text":"In order to create a Java DSL based router setup the base class AbstractJavaCamelComponent may be used, which implements and RouteBuilder class, a simple setup might look like: import org.eclipse.kura.camel.component.AbstractJavaCamelComponent ; class MyRouter extends AbstractJavaCamelComponent { public void configure () throws Exception { from ( \"direct:test\" ) . to ( \"mock:test\" ); } }","title":"Java DSL based component"},{"location":"cloud-platform/apache-camel-integration/kura-camel-app/#using-the-camelrunner","text":"The CamelRunner class is not derived from any OSGi or Kura base class and can be used in scenarios where more flexibility is required. It allows to define a set of pre-requisites for the Camel context. It is for example possible to define a dependency on a Kura cloud service instance and a Camel component provider. Once the runner is started it will listen for OSGi services resolving those dependencies and then starting up the Camel context. The following example shows how to set up a Camel context using the CamelRunner : // create a new camel Builder Builder builder = new CamelRunner . Builder (); // add service dependency builder . cloudService ( \"kura.service.pid\" , \"my.cloud.service.pid\" ); // add Camel component dependency to 'milo-server' builder . requireComponent ( \"milo-server\" ); CamelRunner runner = builder . build (); // set routes runner . setRoutes ( new RouteBuilder () { public void configure () throws Exception { from ( \"direct:test\" ) . to ( \"mock:test\" ); } } ); // set routes runner . start (); It is also possible to later update routes with a call to setRoutes : // maybe update routes at a later time runner . setRoutes ( /* different routes */ );","title":"Using the CamelRunner"},{"location":"cloud-platform/apache-camel-integration/kura-camel-app/#examples","text":"The following examples can help in getting started.","title":"Examples"},{"location":"cloud-platform/apache-camel-integration/kura-camel-app/#kura-camel-example-publisher","text":"The Camel example publisher ( org.eclipse.kura.example.camel.publisher ) can be used as an reference for starting. The final OSGi bundle can be dropped into a Kura application an be started. It allows to configure dynamically during runtime and is capable of switching CloudService instances dynamically.","title":"Kura Camel example publisher"},{"location":"cloud-platform/apache-camel-integration/kura-camel-app/#kura-camel-quickstart","text":"The Camel quickstart project ( org.eclipse.kura.example.camel.quickstart ) shows two components, Java and XML based, working together. The bundle can also be dropped into Kura for testing.","title":"Kura Camel quickstart"},{"location":"cloud-platform/apache-camel-integration/kura-camel-app/#kura-camel-aggregation","text":"The Camel quickstart project ( org.eclipse.kura.example.camel.aggregation ) shows a simple data aggregation pattern with Camel by processing data and publishing the result.","title":"Kura Camel aggregation"},{"location":"cloud-platform/apache-camel-integration/kura-camel-cloud/","text":"Apache Camel\u2122 as a Kura cloud service The default way to create a new cloud service instance backed by Camel is to use the new Web UI for cloud services. A new cloud service instance of the type org.eclipse.kura.camel.cloud.factory.CamelFactory has to be created. In addition to that a set of Camel routes have to be provided. The interface with the Kura application is the Camel vm component. Information set \"upstream\" from the Kura application can be received by the Camel cloud service instance of the following endpoint vm:camel:example . Where camel is the application id and example is the topic. The following code snippet writes out all of the Kura payload structure received on this topic to the logger system: ${body.metrics().entrySet()} ${body.key()} ${body.value()} The snippet splits up the incoming KuraPayload structure and creates a logger called kura.data. for each metric and writes out the actual value to it. The output in the log file should look like: 2016-11-14 16:14:34,539 [Camel (camel-10) thread #18 - vm://camel:example] INFO k.d.intValue - Exchange[ExchangePattern: InOnly, BodyType: Long, Body: 19] 2016-11-14 16:14:34,566 [Camel (camel-10) thread #18 - vm://camel:example] INFO k.d.doubleValue - Exchange[ExchangePattern: InOnly, BodyType: Double, Body: 10.226808617581144] 2016-11-14 16:14:35,575 [Camel (camel-10) thread #18 - vm://camel:example] INFO k.d.intValue - Exchange[ExchangePattern: InOnly, BodyType: Long, Body: 19] 2016-11-14 16:14:35,602 [Camel (camel-10) thread #18 - vm://camel:example] INFO k.d.doubleValue - Exchange[ExchangePattern: InOnly, BodyType: Double, Body: 10.27218775669447] 2016-11-14 16:14:36,539 [Camel (camel-10) thread #18 - vm://camel:example] INFO k.d.intValue - Exchange[ExchangePattern: InOnly, BodyType: Long, Body: 19] 2016-11-14 16:14:36,567 [Camel (camel-10) thread #18 - vm://camel:example] INFO k.d.doubleValue - Exchange[ExchangePattern: InOnly, BodyType: Double, Body: 10.314456684208022]","title":"Apache Camel™ Cloud Service"},{"location":"cloud-platform/apache-camel-integration/kura-camel-cloud/#apache-camel-as-a-kura-cloud-service","text":"The default way to create a new cloud service instance backed by Camel is to use the new Web UI for cloud services. A new cloud service instance of the type org.eclipse.kura.camel.cloud.factory.CamelFactory has to be created. In addition to that a set of Camel routes have to be provided. The interface with the Kura application is the Camel vm component. Information set \"upstream\" from the Kura application can be received by the Camel cloud service instance of the following endpoint vm:camel:example . Where camel is the application id and example is the topic. The following code snippet writes out all of the Kura payload structure received on this topic to the logger system: ${body.metrics().entrySet()} ${body.key()} ${body.value()} The snippet splits up the incoming KuraPayload structure and creates a logger called kura.data. for each metric and writes out the actual value to it. The output in the log file should look like: 2016-11-14 16:14:34,539 [Camel (camel-10) thread #18 - vm://camel:example] INFO k.d.intValue - Exchange[ExchangePattern: InOnly, BodyType: Long, Body: 19] 2016-11-14 16:14:34,566 [Camel (camel-10) thread #18 - vm://camel:example] INFO k.d.doubleValue - Exchange[ExchangePattern: InOnly, BodyType: Double, Body: 10.226808617581144] 2016-11-14 16:14:35,575 [Camel (camel-10) thread #18 - vm://camel:example] INFO k.d.intValue - Exchange[ExchangePattern: InOnly, BodyType: Long, Body: 19] 2016-11-14 16:14:35,602 [Camel (camel-10) thread #18 - vm://camel:example] INFO k.d.doubleValue - Exchange[ExchangePattern: InOnly, BodyType: Double, Body: 10.27218775669447] 2016-11-14 16:14:36,539 [Camel (camel-10) thread #18 - vm://camel:example] INFO k.d.intValue - Exchange[ExchangePattern: InOnly, BodyType: Long, Body: 19] 2016-11-14 16:14:36,567 [Camel (camel-10) thread #18 - vm://camel:example] INFO k.d.doubleValue - Exchange[ExchangePattern: InOnly, BodyType: Double, Body: 10.314456684208022]","title":"Apache Camel™ as a Kura cloud service"},{"location":"cloud-platform/apache-camel-integration/kura-camel/","text":"Apache Camel\u2122 integration overview Note This document describes the Camel integration for Kura 2.1.0 Kura provides two main integration points for Camel: Camel as a Kura application Camel as a Kura cloud service The first allows one to configure Camel to provide data and receive commands from any CloudService instance which is configured in Kura. For example the default CloudService instance which is backed by MQTT. The second approach allows one to create a custom CloudService implementation and route data coming from other Kura applications with the routes provided by this Camel context. Deploying additional Camel components Kura comes with the following Camel components pre-installed: camel-core camel-core-osgi camel-stream If additional Camel components are required, they can be installed using deployment packages (DP), as common with Kura. There are pre-packaged DPs available for e.g. AMQP, OPC UA, MQTT and other Camel components outside of the Kura project.","title":"Apache Camel™ integration"},{"location":"cloud-platform/apache-camel-integration/kura-camel/#apache-camel-integration-overview","text":"Note This document describes the Camel integration for Kura 2.1.0 Kura provides two main integration points for Camel: Camel as a Kura application Camel as a Kura cloud service The first allows one to configure Camel to provide data and receive commands from any CloudService instance which is configured in Kura. For example the default CloudService instance which is backed by MQTT. The second approach allows one to create a custom CloudService implementation and route data coming from other Kura applications with the routes provided by this Camel context.","title":"Apache Camel™ integration overview"},{"location":"cloud-platform/apache-camel-integration/kura-camel/#deploying-additional-camel-components","text":"Kura comes with the following Camel components pre-installed: camel-core camel-core-osgi camel-stream If additional Camel components are required, they can be installed using deployment packages (DP), as common with Kura. There are pre-packaged DPs available for e.g. AMQP, OPC UA, MQTT and other Camel components outside of the Kura project.","title":"Deploying additional Camel components"},{"location":"connect-field-devices/IO-apis/","text":"I/O APIs The full Eclipse Kura API reference is available here . In this page, the developer can find a synthetic grouping of the I/O APIs added starting from Kura 3.1.0. Drivers ChannelDescriptor ChannelListener ChannelRecord ConnectionException Assets AssetConfiguration Channel","title":"I/O APIs"},{"location":"connect-field-devices/IO-apis/#io-apis","text":"The full Eclipse Kura API reference is available here . In this page, the developer can find a synthetic grouping of the I/O APIs added starting from Kura 3.1.0. Drivers ChannelDescriptor ChannelListener ChannelRecord ConnectionException Assets AssetConfiguration Channel","title":"I/O APIs"},{"location":"connect-field-devices/asset-implemetation/","text":"Asset implementation An Asset is a logical representation of a field device, described by a list of Channels . The Asset uses a specific Driver instance to communicate with the underlying device and it models a generic device resource as a Channel . A register in a PLC or a GATT Characteristic in a Bluetooth device are examples of Channels. In this way, each Asset has multiple Channels for reading and writing data from/to an Industrial Device. Assets can be used as Wire Components to access the resources referenced by the defined channels inside a Wire Graph, see the Assets as Wire Components guide for more details. Channel Example To further describe the concept of Channel and Asset, the following table shows a set of PLC register addresses as provided in a typical PLC documentation. Name Entity Address LED1 COILS 2049 LED2 COILS 2050 LED3 COILS 2051 LED4 RED COILS 2052 LED4 GREEN COILS 2053 LED4 BLUE COILS 2054 Counter 3 INPUT REGISTERS 515 Quad Counter INPUT REGISTERS 520 Toggle 4 DISCRETE INPUTS 2052 Toggle 5 DISCRETE INPUTS 2053 Toggle 6 DISCRETE INPUTS 2054 Reset Counter 3 COILS 3075 Reset Quad Counter COILS 3084 The corresponding Channels definition in the Asset is as follows: As shown in the previous image, the Channel definition in an Asset results easily mappable to what available in a generic PLC documentation. Once defined the Channels in an Asset, a simple Java application that leverages the Asset API can easily communicate with the Field device by simply referring to the specific Channel of interest. Channel Definition enabled : each channel can be separately enabled using this flag. name : unique user-friendly name for a channel type : represents the type of operation supported. Possible values are: READ , WRITE , READ/WRITE value.type : represents the data type that will be used when creating the Wire Envelope for the connected components. scale : an optional scaling factor to be applied only to the numeric values retrieved from the field. It is represented as a double and if the value.type is, for example, an integer, the scaling factor multiplier will be casted to integer before multiplying it to the retrieved value. offset : an optional offset value that will be added only to the numeric values retrieved from the field. It is a double in the asset definition, and will be casted to the value.type of the retrieved value before being applied. unit : an optional string value that will be added to the asset channel read to represent the unit of measure associated to that specific channel. listen : if supported by the associated driver, allows to receive notifications by the driver on events. This flag currently has effect only inside Kura Wires. Driver specific parameters The parameters that are not included in list of driver independent parameters above are driver specific. These parameters are used to identify the resource addressed by the channel. Driver specific parameters are described in the driver documentation. Other Asset Configurations asset.desc : a user friendly description of the asset emit.all.channels : specifies whether the values of all READ or READ_WRITE channels should be emitted in case of a channel event. If set to true, the values for all channels will be read and emitted, if set to false, only the value for the channel related to the event will be emitted. timestamp.mode : if set to PER_CHANNEL, the component will emit a driver-generated timestamp per channel property. If set to SINGLE_ASSET_GENERATED, the component will emit a single timestamp per request, generated by the Asset itself before emitting the envelope. If set to SINGLE_DRIVER_GENERATED_MAX or SINGLE_DRIVER_GENERATED_MIN, the component will emit a single driver generated timestamp being respectively the max (most recent) or min (oldest) among the timestamps of the channels. emit.errors : Specifies whether errors should be included or not in the emitted envelope. Default is false. emit.on.change : If set to true, this component will include a channel value in the output emitted in Kura Wires only if it is different than the one from the previous read operation or event. Channel errors will always be emitted if emit.errors is set to true. emit.empty.envelopes : If set to false, this component will not emit empty envelopes. This property can be useful if combined with emit.on.change . Channels download The creation of the channels is a process that could be very time and effort consuming. For this reason, once the user has created the desired channels, it is possible to download the entire list from the web UI, by clicking the Download Channels button: The list is downloaded in csv format and is represented in the form of a table, whose columns represent the entries for the options in the channel definition, while each row is equivalent to a specific channel. For example, the resulting csv file retrieved from downloading the list of channels in the image above is: The resulting table is composed by some static, pre-defined options (the ones mentioned in Channel Definition section above, from enabled to listen ) that are the same for each component and the ones introduced by the specific bundle under analisys. In this case, the modbus driver introduces these driver-specific options: unit.id primary.table memory.address data.order data.type array.data.length The download tool is extremely useful in all those situations where the user wants to quickly load a long list of channels at once: for example, it can easily clone the same list in multiple assets, export it to another device, or simply save it locally to always have a copy of the channels ready. CSV upload The Upload Channels button allows the user to load a local csv file to create the channel list in one shot: the uploading file must implement the same table-structure described in the \"Channels download\" section above, so with each rows representing a channels, and each column one entry of the channel's options. Once the user clicks on the button, will be shown a pop-up in which there are a button to locate the file in the user's filesystem and two checkboxes to allow the uploading phase customization. After clicking on Upload , if the process is succesful, the new channels list will be shown, and the user is just asked to click on the Apply button to save the asset variation. Force import empty string policy The Force import empty string policy checkbox forces the parsing of all empty values present in the csv as empty strings, for all those channel's options that are typed to String and \"not required\" by the metatype. So, this box must be checked when the user wants that all empty values from the csv are considered as empty strings ( \"\" ) when parsed to driver-specific channel option, defined by the metatype as String type and not required . So, those values that are null in the csv, will be set as \"\" in the channel options. The user must be cautious, because the framework supposes that it's consciously leaving empty values in the csv. Otherwise, if the box is unchecked, all the csv empty values will be considered as null strings and parsed to the default value set in the metatype of the driver. If, for example, the user downloads the channels list following the steps described in the precious section, it could upload the same csv file into an other asset, or another device, to get the exactly same asset configuration. Replace current channels The Replace current channels must be checked when the user wants to replace all the channels currently present in the asset, with the ones that will be created by the csv uploading.","title":"Asset implementation"},{"location":"connect-field-devices/asset-implemetation/#asset-implementation","text":"An Asset is a logical representation of a field device, described by a list of Channels . The Asset uses a specific Driver instance to communicate with the underlying device and it models a generic device resource as a Channel . A register in a PLC or a GATT Characteristic in a Bluetooth device are examples of Channels. In this way, each Asset has multiple Channels for reading and writing data from/to an Industrial Device. Assets can be used as Wire Components to access the resources referenced by the defined channels inside a Wire Graph, see the Assets as Wire Components guide for more details.","title":"Asset implementation"},{"location":"connect-field-devices/asset-implemetation/#channel-example","text":"To further describe the concept of Channel and Asset, the following table shows a set of PLC register addresses as provided in a typical PLC documentation. Name Entity Address LED1 COILS 2049 LED2 COILS 2050 LED3 COILS 2051 LED4 RED COILS 2052 LED4 GREEN COILS 2053 LED4 BLUE COILS 2054 Counter 3 INPUT REGISTERS 515 Quad Counter INPUT REGISTERS 520 Toggle 4 DISCRETE INPUTS 2052 Toggle 5 DISCRETE INPUTS 2053 Toggle 6 DISCRETE INPUTS 2054 Reset Counter 3 COILS 3075 Reset Quad Counter COILS 3084 The corresponding Channels definition in the Asset is as follows: As shown in the previous image, the Channel definition in an Asset results easily mappable to what available in a generic PLC documentation. Once defined the Channels in an Asset, a simple Java application that leverages the Asset API can easily communicate with the Field device by simply referring to the specific Channel of interest.","title":"Channel Example"},{"location":"connect-field-devices/asset-implemetation/#channel-definition","text":"enabled : each channel can be separately enabled using this flag. name : unique user-friendly name for a channel type : represents the type of operation supported. Possible values are: READ , WRITE , READ/WRITE value.type : represents the data type that will be used when creating the Wire Envelope for the connected components. scale : an optional scaling factor to be applied only to the numeric values retrieved from the field. It is represented as a double and if the value.type is, for example, an integer, the scaling factor multiplier will be casted to integer before multiplying it to the retrieved value. offset : an optional offset value that will be added only to the numeric values retrieved from the field. It is a double in the asset definition, and will be casted to the value.type of the retrieved value before being applied. unit : an optional string value that will be added to the asset channel read to represent the unit of measure associated to that specific channel. listen : if supported by the associated driver, allows to receive notifications by the driver on events. This flag currently has effect only inside Kura Wires.","title":"Channel Definition"},{"location":"connect-field-devices/asset-implemetation/#driver-specific-parameters","text":"The parameters that are not included in list of driver independent parameters above are driver specific. These parameters are used to identify the resource addressed by the channel. Driver specific parameters are described in the driver documentation.","title":"Driver specific parameters"},{"location":"connect-field-devices/asset-implemetation/#other-asset-configurations","text":"asset.desc : a user friendly description of the asset emit.all.channels : specifies whether the values of all READ or READ_WRITE channels should be emitted in case of a channel event. If set to true, the values for all channels will be read and emitted, if set to false, only the value for the channel related to the event will be emitted. timestamp.mode : if set to PER_CHANNEL, the component will emit a driver-generated timestamp per channel property. If set to SINGLE_ASSET_GENERATED, the component will emit a single timestamp per request, generated by the Asset itself before emitting the envelope. If set to SINGLE_DRIVER_GENERATED_MAX or SINGLE_DRIVER_GENERATED_MIN, the component will emit a single driver generated timestamp being respectively the max (most recent) or min (oldest) among the timestamps of the channels. emit.errors : Specifies whether errors should be included or not in the emitted envelope. Default is false. emit.on.change : If set to true, this component will include a channel value in the output emitted in Kura Wires only if it is different than the one from the previous read operation or event. Channel errors will always be emitted if emit.errors is set to true. emit.empty.envelopes : If set to false, this component will not emit empty envelopes. This property can be useful if combined with emit.on.change .","title":"Other Asset Configurations"},{"location":"connect-field-devices/asset-implemetation/#channels-download","text":"The creation of the channels is a process that could be very time and effort consuming. For this reason, once the user has created the desired channels, it is possible to download the entire list from the web UI, by clicking the Download Channels button: The list is downloaded in csv format and is represented in the form of a table, whose columns represent the entries for the options in the channel definition, while each row is equivalent to a specific channel. For example, the resulting csv file retrieved from downloading the list of channels in the image above is: The resulting table is composed by some static, pre-defined options (the ones mentioned in Channel Definition section above, from enabled to listen ) that are the same for each component and the ones introduced by the specific bundle under analisys. In this case, the modbus driver introduces these driver-specific options: unit.id primary.table memory.address data.order data.type array.data.length The download tool is extremely useful in all those situations where the user wants to quickly load a long list of channels at once: for example, it can easily clone the same list in multiple assets, export it to another device, or simply save it locally to always have a copy of the channels ready.","title":"Channels download"},{"location":"connect-field-devices/asset-implemetation/#csv-upload","text":"The Upload Channels button allows the user to load a local csv file to create the channel list in one shot: the uploading file must implement the same table-structure described in the \"Channels download\" section above, so with each rows representing a channels, and each column one entry of the channel's options. Once the user clicks on the button, will be shown a pop-up in which there are a button to locate the file in the user's filesystem and two checkboxes to allow the uploading phase customization. After clicking on Upload , if the process is succesful, the new channels list will be shown, and the user is just asked to click on the Apply button to save the asset variation.","title":"CSV upload"},{"location":"connect-field-devices/asset-implemetation/#force-import-empty-string-policy","text":"The Force import empty string policy checkbox forces the parsing of all empty values present in the csv as empty strings, for all those channel's options that are typed to String and \"not required\" by the metatype. So, this box must be checked when the user wants that all empty values from the csv are considered as empty strings ( \"\" ) when parsed to driver-specific channel option, defined by the metatype as String type and not required . So, those values that are null in the csv, will be set as \"\" in the channel options. The user must be cautious, because the framework supposes that it's consciously leaving empty values in the csv. Otherwise, if the box is unchecked, all the csv empty values will be considered as null strings and parsed to the default value set in the metatype of the driver. If, for example, the user downloads the channels list following the steps described in the precious section, it could upload the same csv file into an other asset, or another device, to get the exactly same asset configuration.","title":"Force import empty string policy"},{"location":"connect-field-devices/asset-implemetation/#replace-current-channels","text":"The Replace current channels must be checked when the user wants to replace all the channels currently present in the asset, with the ones that will be created by the csv uploading.","title":"Replace current channels"},{"location":"connect-field-devices/asset-v1-mqtt-namespace/","text":"ASSET-V1 MQTT Namespace The ASSET-V1 namespace allows to perform remote operations on the assets defined in an Kura-powered device. The requests and responses are represented as JSON arrays placed in the body of the MQTT payload. The namespace includes the following topics. GET/assets This topic is used to retrieve metadata describing the assets defined on a specific device and their channel configuration. Request format The request can contain JSON array containing a list of asset names for which the metadata needs to be returned. The request JSON must have the following structure: [ { \"name\" : \"asset1\" }, { \"name\" : \"otherAsset\" } ] The request JSON is an array with all elements of the type object . The array object has the following properties: name (string, required): the name of the Asset for which the metadata needs to be returned. If the provided array is empty or the request payload is empty, the metadata describing all assets present on the device will be returned. Response format The response payload contains a JSON array with the following structure: [ { \"name\" : \"asset1\" , \"channels\" : [ { \"name\" : \"first_channel\" , \"type\" : \"INTEGER\" , \"mode\" : \"READ\" }, { \"name\" : \"second_channel\" , \"type\" : \"BOOLEAN\" , \"mode\" : \"READ_WRITE\" }, { \"name\" : \"other_channel\" , \"type\" : \"STRING\" , \"mode\" : \"WRITE\" } ] }, { \"name\" : \"otherAsset\" , \"channels\" : [] }, { \"name\" : \"nonExistingAsset\" , \"error\" : \"Asset not found\" } ] All elements of the array are of the type object . The array object has the following properties: name (string, required): the name of the asset error (string): this property is present only if the metadata for a not existing asset was explicitly requested, it contains an error message. channels (array): the list of channels defined on the asset, it can be empty if no channels are defined. This property and the error property are mutually exclusive. This object is an array with all elements of the type object and they have the following properties: name (string, required): the name of the channel. mode (string, required): the mode of the channel. The possible values are READ , WRITE or READ_WRITE . type (string, required): the value type of the channel. The possible values are BOOLEAN , BYTE_ARRAY , DOUBLE , INTEGER , LONG , FLOAT , STRING . EXEC/read This topic is used to perform a read operation on a specified set of assets and channels. Request format The request can contain a JSON array with the following structure: [ { \"name\" : \"asset1\" , \"channels\" : [ { \"name\" : \"channel1\" }, { \"name\" : \"channel2\" }, { \"name\" : \"otherChannel\" } ] }, { \"name\" : \"otherAsset\" } ] The request JSON is an array with all elements of the type object . If the list is empty or if the request payload is empty all channels of all assets will be read. The array object has the following properties: name (string, required): the name of the asset involved in the read operation channels (array): the list of the names of the channels to be read, if this property is not present or if its value is an empty array, all channels for the specified asset will be read. The object is an array with all elements of the type object . The array object has the following properties: name (string, required): the name of the channel to be read Response Format The response is returned as a JSON array placed in the body of the response: [ { \"name\" : \"asset1\" , \"channels\" : [ { \"name\" : \"first_channel\" , \"type\" : \"INTEGER\" , \"value\" : \"432\" , \"timestamp\" : 1234550 }, { \"name\" : \"second_channel\" , \"type\" : \"BOOLEAN\" , \"value\" : \"true\" , \"timestamp\" : 1234550 }, { \"name\" : \"other_channel\" , \"error\" : \"Read failed\" , \"timestamp\" : 1234550 }, { \"name\" : \"binary_channel\" , \"type\" : \"BYTE_ARRAY\" , \"value\" : \"dGVzdCBzdHJpbmcK\" , \"timestamp\" : 1234550 } ] }, { \"name\" : \"nonExistingAsset\" , \"error\" : \"Asset not found\" } ] The response JSON is an array with all elements of the type object . The array object has the following properties: name (string, required): the name of the asset. error (string): an error message. This property is present only if a read operation for a not existing asset was explicitly requested. channels (array): the object is an array with all elements of the type object . The array object has the following properties: name (string, required): the name of the channel. timestamp (integer, required): the device timestamp associated with the result in milliseconds since the Unix Epoch. type (string): the type of the result. This property is present only if the operation succeeded. The possible values are BOOLEAN , BYTE_ARRAY , DOUBLE , INTEGER , LONG , FLOAT , STRING . value (string): the result value of the read request encoded as a String. This property is present only if the operation succeeded. If the channel type is BYTE_ARRAY , the result will be represented using the base64 encoding. error (string): an error message. This property is present only if the operation failed. EXEC/write Performs a write operation on a specified set of channels and assets. Request format The request must contain a JSON array with the following structure: [ { \"name\" : \"asset1\" , \"channels\" : [ { \"name\" : \"first_channel\" , \"type\" : \"INTEGER\" , \"value\" : \"432\" , }, { \"name\" : \"second_channel\" , \"type\" : \"BOOLEAN\" , \"value\" : \"true\" , }, { \"name\" : \"binary_channel\" , \"type\" : \"BYTE_ARRAY\" , \"value\" : \"dGVzdCBzdHJpbmcK\" , } ] } ] The array object has the following properties: name (string, required): the name of the asset. channels (array, required): the list of channel names and values to be written. The object is an array with all elements of the type object . The array object has the following properties: name (string, required): the name of the channel. type (string, required): the type of the value to be written. The allowed values are BOOLEAN , BYTE_ARRAY , DOUBLE , INTEGER , LONG , FLOAT , STRING . value (string, required): the value to be written encoded as a String. If the channel type is BYTE_ARRAY , the base64 encoding must be used. Response format The response uses the same format as the EXEC/read request, in case of success the type and value properties in the response will report the same values specified in the request.","title":"ASSET-V1 MQTT Namespace"},{"location":"connect-field-devices/asset-v1-mqtt-namespace/#asset-v1-mqtt-namespace","text":"The ASSET-V1 namespace allows to perform remote operations on the assets defined in an Kura-powered device. The requests and responses are represented as JSON arrays placed in the body of the MQTT payload. The namespace includes the following topics.","title":"ASSET-V1 MQTT Namespace"},{"location":"connect-field-devices/asset-v1-mqtt-namespace/#getassets","text":"This topic is used to retrieve metadata describing the assets defined on a specific device and their channel configuration.","title":"GET/assets"},{"location":"connect-field-devices/asset-v1-mqtt-namespace/#request-format","text":"The request can contain JSON array containing a list of asset names for which the metadata needs to be returned. The request JSON must have the following structure: [ { \"name\" : \"asset1\" }, { \"name\" : \"otherAsset\" } ] The request JSON is an array with all elements of the type object . The array object has the following properties: name (string, required): the name of the Asset for which the metadata needs to be returned. If the provided array is empty or the request payload is empty, the metadata describing all assets present on the device will be returned.","title":"Request format"},{"location":"connect-field-devices/asset-v1-mqtt-namespace/#response-format","text":"The response payload contains a JSON array with the following structure: [ { \"name\" : \"asset1\" , \"channels\" : [ { \"name\" : \"first_channel\" , \"type\" : \"INTEGER\" , \"mode\" : \"READ\" }, { \"name\" : \"second_channel\" , \"type\" : \"BOOLEAN\" , \"mode\" : \"READ_WRITE\" }, { \"name\" : \"other_channel\" , \"type\" : \"STRING\" , \"mode\" : \"WRITE\" } ] }, { \"name\" : \"otherAsset\" , \"channels\" : [] }, { \"name\" : \"nonExistingAsset\" , \"error\" : \"Asset not found\" } ] All elements of the array are of the type object . The array object has the following properties: name (string, required): the name of the asset error (string): this property is present only if the metadata for a not existing asset was explicitly requested, it contains an error message. channels (array): the list of channels defined on the asset, it can be empty if no channels are defined. This property and the error property are mutually exclusive. This object is an array with all elements of the type object and they have the following properties: name (string, required): the name of the channel. mode (string, required): the mode of the channel. The possible values are READ , WRITE or READ_WRITE . type (string, required): the value type of the channel. The possible values are BOOLEAN , BYTE_ARRAY , DOUBLE , INTEGER , LONG , FLOAT , STRING .","title":"Response format"},{"location":"connect-field-devices/asset-v1-mqtt-namespace/#execread","text":"This topic is used to perform a read operation on a specified set of assets and channels.","title":"EXEC/read"},{"location":"connect-field-devices/asset-v1-mqtt-namespace/#request-format_1","text":"The request can contain a JSON array with the following structure: [ { \"name\" : \"asset1\" , \"channels\" : [ { \"name\" : \"channel1\" }, { \"name\" : \"channel2\" }, { \"name\" : \"otherChannel\" } ] }, { \"name\" : \"otherAsset\" } ] The request JSON is an array with all elements of the type object . If the list is empty or if the request payload is empty all channels of all assets will be read. The array object has the following properties: name (string, required): the name of the asset involved in the read operation channels (array): the list of the names of the channels to be read, if this property is not present or if its value is an empty array, all channels for the specified asset will be read. The object is an array with all elements of the type object . The array object has the following properties: name (string, required): the name of the channel to be read","title":"Request format"},{"location":"connect-field-devices/asset-v1-mqtt-namespace/#response-format_1","text":"The response is returned as a JSON array placed in the body of the response: [ { \"name\" : \"asset1\" , \"channels\" : [ { \"name\" : \"first_channel\" , \"type\" : \"INTEGER\" , \"value\" : \"432\" , \"timestamp\" : 1234550 }, { \"name\" : \"second_channel\" , \"type\" : \"BOOLEAN\" , \"value\" : \"true\" , \"timestamp\" : 1234550 }, { \"name\" : \"other_channel\" , \"error\" : \"Read failed\" , \"timestamp\" : 1234550 }, { \"name\" : \"binary_channel\" , \"type\" : \"BYTE_ARRAY\" , \"value\" : \"dGVzdCBzdHJpbmcK\" , \"timestamp\" : 1234550 } ] }, { \"name\" : \"nonExistingAsset\" , \"error\" : \"Asset not found\" } ] The response JSON is an array with all elements of the type object . The array object has the following properties: name (string, required): the name of the asset. error (string): an error message. This property is present only if a read operation for a not existing asset was explicitly requested. channels (array): the object is an array with all elements of the type object . The array object has the following properties: name (string, required): the name of the channel. timestamp (integer, required): the device timestamp associated with the result in milliseconds since the Unix Epoch. type (string): the type of the result. This property is present only if the operation succeeded. The possible values are BOOLEAN , BYTE_ARRAY , DOUBLE , INTEGER , LONG , FLOAT , STRING . value (string): the result value of the read request encoded as a String. This property is present only if the operation succeeded. If the channel type is BYTE_ARRAY , the result will be represented using the base64 encoding. error (string): an error message. This property is present only if the operation failed.","title":"Response Format"},{"location":"connect-field-devices/asset-v1-mqtt-namespace/#execwrite","text":"Performs a write operation on a specified set of channels and assets.","title":"EXEC/write"},{"location":"connect-field-devices/asset-v1-mqtt-namespace/#request-format_2","text":"The request must contain a JSON array with the following structure: [ { \"name\" : \"asset1\" , \"channels\" : [ { \"name\" : \"first_channel\" , \"type\" : \"INTEGER\" , \"value\" : \"432\" , }, { \"name\" : \"second_channel\" , \"type\" : \"BOOLEAN\" , \"value\" : \"true\" , }, { \"name\" : \"binary_channel\" , \"type\" : \"BYTE_ARRAY\" , \"value\" : \"dGVzdCBzdHJpbmcK\" , } ] } ] The array object has the following properties: name (string, required): the name of the asset. channels (array, required): the list of channel names and values to be written. The object is an array with all elements of the type object . The array object has the following properties: name (string, required): the name of the channel. type (string, required): the type of the value to be written. The allowed values are BOOLEAN , BYTE_ARRAY , DOUBLE , INTEGER , LONG , FLOAT , STRING . value (string, required): the value to be written encoded as a String. If the channel type is BYTE_ARRAY , the base64 encoding must be used.","title":"Request format"},{"location":"connect-field-devices/asset-v1-mqtt-namespace/#response-format_2","text":"The response uses the same format as the EXEC/read request, in case of success the type and value properties in the response will report the same values specified in the request.","title":"Response format"},{"location":"connect-field-devices/driver-and-assets/","text":"Drivers, Assets and Channels Eclipse Kura introduces a model based on the concepts of Drivers and Assets to simplify the communication with the field devices attached to a gateway. A Driver encapsulates the communication protocol and its configuration parameters, dealing with the low-level characteristics of the field protocol. It opens, closes and performs the communication with the end field device. It also exposes field protocol specific information that can be used by upper levels of abstraction to simplify the interaction with the end devices. An Asset is a logical representation of a field device, described by a list of Channels . The Asset uses a specific Driver instance to communicate with the underlying device and it models a generic device resource as a Channel . A register in a PLC or a GATT Characteristic in a Bluetooth device are examples of Channels. In this way, each Asset has multiple Channels for reading and writing data from/to an Industrial Device. Channel Example To further describe the concept of Channel and Asset, the following table shows a set of PLC register addresses as provided in a typical PLC documentation. Name Entity Address LED1 COILS 2049 LED2 COILS 2050 LED3 COILS 2051 LED4 RED COILS 2052 LED4 GREEN COILS 2053 LED4 BLUE COILS 2054 Counter 3 INPUT REGISTERS 515 Quad Counter INPUT REGISTERS 520 Toggle 4 DISCRETE INPUTS 2052 Toggle 5 DISCRETE INPUTS 2053 Toggle 6 DISCRETE INPUTS 2054 Reset Counter 3 COILS 3075 Reset Quad Counter COILS 3084 The corresponding Channels definition in the Asset is as follows: As shown in the previous image, the Channel definition in an Asset results easily mappable to what available in a generic PLC documentation. Once defined the Channels in an Asset, a simple Java application that leverages the Asset API can easily communicate with the Field device by simply referring to the specific Channel of interest. Drivers and Assets in Kura Administrative UI Kura provides a specific section of the UI to allow users to manage the different instances of Drivers and Assets. Using the Kura Web UI the user can instantiate and manage Drivers but also can manage Assets instances based on existing drivers. The user interface allows also to perform specific reads on the configured Assets' channels clicking on the Data tab for the selected Asset.","title":"Drivers, Assets and Channels"},{"location":"connect-field-devices/driver-and-assets/#drivers-assets-and-channels","text":"Eclipse Kura introduces a model based on the concepts of Drivers and Assets to simplify the communication with the field devices attached to a gateway. A Driver encapsulates the communication protocol and its configuration parameters, dealing with the low-level characteristics of the field protocol. It opens, closes and performs the communication with the end field device. It also exposes field protocol specific information that can be used by upper levels of abstraction to simplify the interaction with the end devices. An Asset is a logical representation of a field device, described by a list of Channels . The Asset uses a specific Driver instance to communicate with the underlying device and it models a generic device resource as a Channel . A register in a PLC or a GATT Characteristic in a Bluetooth device are examples of Channels. In this way, each Asset has multiple Channels for reading and writing data from/to an Industrial Device.","title":"Drivers, Assets and Channels"},{"location":"connect-field-devices/driver-and-assets/#channel-example","text":"To further describe the concept of Channel and Asset, the following table shows a set of PLC register addresses as provided in a typical PLC documentation. Name Entity Address LED1 COILS 2049 LED2 COILS 2050 LED3 COILS 2051 LED4 RED COILS 2052 LED4 GREEN COILS 2053 LED4 BLUE COILS 2054 Counter 3 INPUT REGISTERS 515 Quad Counter INPUT REGISTERS 520 Toggle 4 DISCRETE INPUTS 2052 Toggle 5 DISCRETE INPUTS 2053 Toggle 6 DISCRETE INPUTS 2054 Reset Counter 3 COILS 3075 Reset Quad Counter COILS 3084 The corresponding Channels definition in the Asset is as follows: As shown in the previous image, the Channel definition in an Asset results easily mappable to what available in a generic PLC documentation. Once defined the Channels in an Asset, a simple Java application that leverages the Asset API can easily communicate with the Field device by simply referring to the specific Channel of interest.","title":"Channel Example"},{"location":"connect-field-devices/driver-and-assets/#drivers-and-assets-in-kura-administrative-ui","text":"Kura provides a specific section of the UI to allow users to manage the different instances of Drivers and Assets. Using the Kura Web UI the user can instantiate and manage Drivers but also can manage Assets instances based on existing drivers. The user interface allows also to perform specific reads on the configured Assets' channels clicking on the Data tab for the selected Asset.","title":"Drivers and Assets in Kura Administrative UI"},{"location":"connect-field-devices/driver-implemetation/","text":"Driver implementation A Driver encapsulates the communication protocol and its configuration parameters. The Driver API abstracts the specificities of the end Fieldbus protocols providing a clean and easy to use set of calls that can be used to develop end-applications. Using the Driver APIs, an application can simply use the connect and disconnect methods to open or close the connection with the Field device. Furthermore, the read and write methods allow exchanging data with the Field device. A Driver instance can be associated with an Asset to abstract even more the low-level specificities and allow an easy and portable development of the Java applications that need to interact with sensors, actuators, and PLCs. The Asset will use the Driver's protocol-specific channel descriptor to compose the Asset Channel description. Driver Configuration Generally, a Driver instance is a configurable component which parameters can be updated in the Drivers and Assets section of the Kura Administrative User Interface. Supported Field Protocols and Availability Drivers will be provided as add-ons available in the Eclipse IoT Marketplace . Please see here for a complete list. Driver-Specific Optimizations The Driver API provides a simple method to read a list of Channel Records : public void read(List records) throws ConnectionException; Typically, since the records to read do not change until the Asset configuration is changed by the user, a Driver can perform some optimisations to efficiently read the requested records at once. For example, a Modbus driver can read a range of holding registers using a single request. Since these operations are costly, the Kura API adds methods to ask the driver to prepare reading a given list of records and execute the prepared read: public PreparedRead prepareRead(List records); Invocation of the preparedRead method will result in a PreparedRead instance returned. On a PreparedRead, the execute method will perform the optimized read request.","title":"Driver implementation"},{"location":"connect-field-devices/driver-implemetation/#driver-implementation","text":"A Driver encapsulates the communication protocol and its configuration parameters. The Driver API abstracts the specificities of the end Fieldbus protocols providing a clean and easy to use set of calls that can be used to develop end-applications. Using the Driver APIs, an application can simply use the connect and disconnect methods to open or close the connection with the Field device. Furthermore, the read and write methods allow exchanging data with the Field device. A Driver instance can be associated with an Asset to abstract even more the low-level specificities and allow an easy and portable development of the Java applications that need to interact with sensors, actuators, and PLCs. The Asset will use the Driver's protocol-specific channel descriptor to compose the Asset Channel description.","title":"Driver implementation"},{"location":"connect-field-devices/driver-implemetation/#driver-configuration","text":"Generally, a Driver instance is a configurable component which parameters can be updated in the Drivers and Assets section of the Kura Administrative User Interface.","title":"Driver Configuration"},{"location":"connect-field-devices/driver-implemetation/#supported-field-protocols-and-availability","text":"Drivers will be provided as add-ons available in the Eclipse IoT Marketplace . Please see here for a complete list.","title":"Supported Field Protocols and Availability"},{"location":"connect-field-devices/driver-implemetation/#driver-specific-optimizations","text":"The Driver API provides a simple method to read a list of Channel Records : public void read(List records) throws ConnectionException; Typically, since the records to read do not change until the Asset configuration is changed by the user, a Driver can perform some optimisations to efficiently read the requested records at once. For example, a Modbus driver can read a range of holding registers using a single request. Since these operations are costly, the Kura API adds methods to ask the driver to prepare reading a given list of records and execute the prepared read: public PreparedRead prepareRead(List records); Invocation of the preparedRead method will result in a PreparedRead instance returned. On a PreparedRead, the execute method will perform the optimized read request.","title":"Driver-Specific Optimizations"},{"location":"connect-field-devices/eddystone-driver/","text":"Eddystone\u2122 Driver Eclipse Kura offers support for Eddystone\u2122 protocol via a specific driver. The driver is available only for gateways that support the new Bluetooth LE APIs. It can be used into the Wires framework, the Asset model or directly using the Driver itself. Features The Eddystone\u2122 driver is designed to listen for incoming beacon packets and to recognise the specific protocol. Of course it's not possible to write data to the beacons, since this is outside the protocol specification. The frame format to be filtered can be chosen from the channel definition. For more information about Eddystone\u2122 frame format, see here . Installation As the others Drivers supported by Eclipse Kura, it is distributed as a deployment package on the Eclipse Marketplace here . It can be installed following the instructions provided here . Instance creation A new Eddystone Driver instance can be created either by clicking the New Driver button in the dedicated Drivers and Assets Web UI section or by clicking on the + button under Services . In both cases, the org.eclipse.kura.driver.eddsytone factory must be selected and a unique name must be provided for the new instance. Once instantiated, the Driver has to be configured setting the Bluetooth interface name (i.e. hci0 ) that will be used to connect to the device. Channel configuration The Eddystone Driver channel can be configured with the following parameters: enabled : it allows to enable/disable the channel. If it isn't selected the channel will be ignored. name : the channel name. type : the channel type, ( READ , WRITE , or READ_WRITE ). value.type : the Java type of the channel value. The value read by the Driver will be converted to the value.type . listen : when selected, a listener will be attached to this channel. Any event on the channel will be reported using a callback and the value will be emitted. eddystone.type : the type of the frame. Currently only UID and URL typed are supported.","title":"Eddystone™ Driver"},{"location":"connect-field-devices/eddystone-driver/#eddystone-driver","text":"Eclipse Kura offers support for Eddystone\u2122 protocol via a specific driver. The driver is available only for gateways that support the new Bluetooth LE APIs. It can be used into the Wires framework, the Asset model or directly using the Driver itself.","title":"Eddystone™ Driver"},{"location":"connect-field-devices/eddystone-driver/#features","text":"The Eddystone\u2122 driver is designed to listen for incoming beacon packets and to recognise the specific protocol. Of course it's not possible to write data to the beacons, since this is outside the protocol specification. The frame format to be filtered can be chosen from the channel definition. For more information about Eddystone\u2122 frame format, see here .","title":"Features"},{"location":"connect-field-devices/eddystone-driver/#installation","text":"As the others Drivers supported by Eclipse Kura, it is distributed as a deployment package on the Eclipse Marketplace here . It can be installed following the instructions provided here .","title":"Installation"},{"location":"connect-field-devices/eddystone-driver/#instance-creation","text":"A new Eddystone Driver instance can be created either by clicking the New Driver button in the dedicated Drivers and Assets Web UI section or by clicking on the + button under Services . In both cases, the org.eclipse.kura.driver.eddsytone factory must be selected and a unique name must be provided for the new instance. Once instantiated, the Driver has to be configured setting the Bluetooth interface name (i.e. hci0 ) that will be used to connect to the device.","title":"Instance creation"},{"location":"connect-field-devices/eddystone-driver/#channel-configuration","text":"The Eddystone Driver channel can be configured with the following parameters: enabled : it allows to enable/disable the channel. If it isn't selected the channel will be ignored. name : the channel name. type : the channel type, ( READ , WRITE , or READ_WRITE ). value.type : the Java type of the channel value. The value read by the Driver will be converted to the value.type . listen : when selected, a listener will be attached to this channel. Any event on the channel will be reported using a callback and the value will be emitted. eddystone.type : the type of the frame. Currently only UID and URL typed are supported.","title":"Channel configuration"},{"location":"connect-field-devices/field-protocols/","text":"Field Protocols Eclipse Kura provides support for field protocol implementations as add-ons deployable directly from the Eclipse Marketplace for IoT site. Moreover, several devices are supported using the Kura Driver model. Currently, the following field protocols and devices are supported and downloadable from the Eclipse Marketplace in form of Kura Drivers: Protocol/Device Kura 3.x Kura 4.x Kura 5.x OPC-UA link link link S7 link link link iBeacon N.A. link link Eddystone N.A. link link TiSensorTag link link link GPIO link link link SenseHat link link link","title":"Field Protocols"},{"location":"connect-field-devices/field-protocols/#field-protocols","text":"Eclipse Kura provides support for field protocol implementations as add-ons deployable directly from the Eclipse Marketplace for IoT site. Moreover, several devices are supported using the Kura Driver model. Currently, the following field protocols and devices are supported and downloadable from the Eclipse Marketplace in form of Kura Drivers: Protocol/Device Kura 3.x Kura 4.x Kura 5.x OPC-UA link link link S7 link link link iBeacon N.A. link link Eddystone N.A. link link TiSensorTag link link link GPIO link link link SenseHat link link link","title":"Field Protocols"},{"location":"connect-field-devices/gpio-driver/","text":"GPIO Driver The GPIO Driver manages the General Purpose IOs on a gateway using the Driver model. Based on the GPIO Service, the driver can be used in the Wires framework, the Asset model or directly using the Driver itself. Features The GPIO Driver includes the following features: support for digital input and output support for unsolicited inputs the trigger event can be configured directly through the Driver Installation As the other Drivers supported by Eclipse Kura, it is distributed as a deployment package on the Eclipse Marketplace for Kura 3.x and 4.x/5.x . It can be installed following the instructions provided here . Instance creation A new GPIO Driver instance can be created either by clicking the New Driver button in the dedicated Drivers and Assets Web UI section or by clicking on the + button under Services . In both cases, the org.eclipse.kura.driver.gpio factory must be selected and a unique name must be provided for the new instance. Once instantiated, the GPIO Driver is ready to use and no configuration is needed. Channel configuration The GPIO Driver channel can be configured with the following parameters: enabled : it allows to enable/disable the channel. If it isn't selected the channel will be ignored. name : the channel name. type : the channel type, ( READ , WRITE , or READ_WRITE ). value.type : the Java type of the channel value. The value read by the Driver will be converted to the value.type . Conversely, in write operations the Driver will accept value of this kind. listen : when selected, a listener will be attached to this channel. Any event on the channel will be reported using a callback and the value will be emitted. resource.name : the name of the GPIO resource as reported by the GPIO Service. The #select resource selection has no effect on the channel. resource.direction : the direction of the GPIO. Possible values are INPUT and OUTPUT . The #select direction selection has no effect on the channel. resource.trigger : the type of event that triggers the listener, if selected. Possible values are: NONE : no event will trigger the listener. RISING_EDGE , FALLING_EDGE , BOTH_EDGES : the listeners will be triggered respectively by a low-high transition, a high-low transition or both. HIGH_LEVEL , LOW_LEVEL , BOTH_LEVELS : the listeners will be triggered respectively by the detection of a high, low or both levels. Please note that these options aren't supported by all the devices. Drive a LED using the GPIO Driver In this section a simple example on the GPIO Driver using a RaspberryPi will be presented. Before configuring the Driver, arrange a setup as shown in the following picture, using a breadboard, a led, a 120-ohm resistor and some wires. Connect the yellow wire to a ground pin on the RasperryPi connector (i.e. pin 6) and the red one to pin 40 (a.k.a. gpio21). From the Drivers and Assets tab, create a new GPIO Driver, call it GPIODriver and add an Asset as shown in the following picture. The asset is configured to manage a gpio, called LED , as an output and drives it writing a boolean value. The LED channel is attached to the gpio21 on the RaspberryPi. In the Data tab, fill the Value form with true and press Apply : the green led will switch on. Writing a false will switch off the led.","title":"GPIO Driver"},{"location":"connect-field-devices/gpio-driver/#gpio-driver","text":"The GPIO Driver manages the General Purpose IOs on a gateway using the Driver model. Based on the GPIO Service, the driver can be used in the Wires framework, the Asset model or directly using the Driver itself.","title":"GPIO Driver"},{"location":"connect-field-devices/gpio-driver/#features","text":"The GPIO Driver includes the following features: support for digital input and output support for unsolicited inputs the trigger event can be configured directly through the Driver","title":"Features"},{"location":"connect-field-devices/gpio-driver/#installation","text":"As the other Drivers supported by Eclipse Kura, it is distributed as a deployment package on the Eclipse Marketplace for Kura 3.x and 4.x/5.x . It can be installed following the instructions provided here .","title":"Installation"},{"location":"connect-field-devices/gpio-driver/#instance-creation","text":"A new GPIO Driver instance can be created either by clicking the New Driver button in the dedicated Drivers and Assets Web UI section or by clicking on the + button under Services . In both cases, the org.eclipse.kura.driver.gpio factory must be selected and a unique name must be provided for the new instance. Once instantiated, the GPIO Driver is ready to use and no configuration is needed.","title":"Instance creation"},{"location":"connect-field-devices/gpio-driver/#channel-configuration","text":"The GPIO Driver channel can be configured with the following parameters: enabled : it allows to enable/disable the channel. If it isn't selected the channel will be ignored. name : the channel name. type : the channel type, ( READ , WRITE , or READ_WRITE ). value.type : the Java type of the channel value. The value read by the Driver will be converted to the value.type . Conversely, in write operations the Driver will accept value of this kind. listen : when selected, a listener will be attached to this channel. Any event on the channel will be reported using a callback and the value will be emitted. resource.name : the name of the GPIO resource as reported by the GPIO Service. The #select resource selection has no effect on the channel. resource.direction : the direction of the GPIO. Possible values are INPUT and OUTPUT . The #select direction selection has no effect on the channel. resource.trigger : the type of event that triggers the listener, if selected. Possible values are: NONE : no event will trigger the listener. RISING_EDGE , FALLING_EDGE , BOTH_EDGES : the listeners will be triggered respectively by a low-high transition, a high-low transition or both. HIGH_LEVEL , LOW_LEVEL , BOTH_LEVELS : the listeners will be triggered respectively by the detection of a high, low or both levels. Please note that these options aren't supported by all the devices.","title":"Channel configuration"},{"location":"connect-field-devices/gpio-driver/#drive-a-led-using-the-gpio-driver","text":"In this section a simple example on the GPIO Driver using a RaspberryPi will be presented. Before configuring the Driver, arrange a setup as shown in the following picture, using a breadboard, a led, a 120-ohm resistor and some wires. Connect the yellow wire to a ground pin on the RasperryPi connector (i.e. pin 6) and the red one to pin 40 (a.k.a. gpio21). From the Drivers and Assets tab, create a new GPIO Driver, call it GPIODriver and add an Asset as shown in the following picture. The asset is configured to manage a gpio, called LED , as an output and drives it writing a boolean value. The LED channel is attached to the gpio21 on the RaspberryPi. In the Data tab, fill the Value form with true and press Apply : the green led will switch on. Writing a false will switch off the led.","title":"Drive a LED using the GPIO Driver"},{"location":"connect-field-devices/ibeacon-driver/","text":"iBeacon\u2122 Driver Eclipse Kura provides a driver specifically developed to manage iBeacon\u2122 protocol. The driver is available only for gateways that support the new Bluetooth LE APIs. They can be used into the Wires framework, the Asset model or directly using the Driver itself. Features The iBeacon\u2122 driver is designed to listen for incoming beacon packets and to recognise the specific protocol. Of course it's not possible to write data to the beacons, since this is outside the protocol specification. Installation As the others Drivers supported by Eclipse Kura, it is distributed as a deployment package on the Eclipse Marketplace here . It can be installed following the instructions provided here . Instance creation A new iBeacon instance can be created either by clicking the New Driver button in the dedicated Drivers and Assets Web UI section or by clicking on the + button under Services . In both cases, the org.eclipse.kura.driver.ibeacon factory must be selected and a unique name must be provided for the new instance. Once instantiated, the Driver has to be configured setting the Bluetooth interface name (i.e. hci0 ) that will be used to connect to the device. Channel configuration The iBeacon Driver channel can be configured with the following parameters: enabled : it allows to enable/disable the channel. If it isn't selected the channel will be ignored. name : the channel name. type : the channel type, ( READ , WRITE , or READ_WRITE ). value.type : the Java type of the channel value. The value read by the Driver will be converted to the value.type . listen : when selected, a listener will be attached to this channel. Any event on the channel will be reported using a callback and the value will be emitted.","title":"iBeacon™ Driver"},{"location":"connect-field-devices/ibeacon-driver/#ibeacon-driver","text":"Eclipse Kura provides a driver specifically developed to manage iBeacon\u2122 protocol. The driver is available only for gateways that support the new Bluetooth LE APIs. They can be used into the Wires framework, the Asset model or directly using the Driver itself.","title":"iBeacon™ Driver"},{"location":"connect-field-devices/ibeacon-driver/#features","text":"The iBeacon\u2122 driver is designed to listen for incoming beacon packets and to recognise the specific protocol. Of course it's not possible to write data to the beacons, since this is outside the protocol specification.","title":"Features"},{"location":"connect-field-devices/ibeacon-driver/#installation","text":"As the others Drivers supported by Eclipse Kura, it is distributed as a deployment package on the Eclipse Marketplace here . It can be installed following the instructions provided here .","title":"Installation"},{"location":"connect-field-devices/ibeacon-driver/#instance-creation","text":"A new iBeacon instance can be created either by clicking the New Driver button in the dedicated Drivers and Assets Web UI section or by clicking on the + button under Services . In both cases, the org.eclipse.kura.driver.ibeacon factory must be selected and a unique name must be provided for the new instance. Once instantiated, the Driver has to be configured setting the Bluetooth interface name (i.e. hci0 ) that will be used to connect to the device.","title":"Instance creation"},{"location":"connect-field-devices/ibeacon-driver/#channel-configuration","text":"The iBeacon Driver channel can be configured with the following parameters: enabled : it allows to enable/disable the channel. If it isn't selected the channel will be ignored. name : the channel name. type : the channel type, ( READ , WRITE , or READ_WRITE ). value.type : the Java type of the channel value. The value read by the Driver will be converted to the value.type . listen : when selected, a listener will be attached to this channel. Any event on the channel will be reported using a callback and the value will be emitted.","title":"Channel configuration"},{"location":"connect-field-devices/opcua-driver/","text":"OPC UA Driver This Driver implements the client side of the OPC UA protocol using the Driver model. The Driver can be used to interact as a client with OPC UA servers using different abstractions, such as the Wires framework, the Asset model or by directly using the Driver itself. The Driver is distributed as a deployment package on Eclipse Marketplace for Kura 3.x and 4.x/5.x . It can be installed following the instructions provided here . Features The OPC UA Driver features include: Support for the OPC UA protocol over TCP. Support for reading and writing OPC UA variable nodes by node ID. Instance creation A new OPC UA instance can be created either by clicking the New Driver button in the dedicated Drivers and Assets Web UI section or by clicking on the + button under Services . In both cases, the org.eclipse.kura.driver.opcua factory must be selected and a unique name must be provided for the new instance. Channel configuration The OPC UA Driver channel configuration is composed of the following parameters: name : the channel name. type : the channel type, ( READ , WRITE , or READ_WRITE ). value type : the Java type of the channel value. node.id : The node id of the variable node to be used, the format of the node id depends on the value of the node.id.type property. node.namespace.index : The namespace index of the variable node to be used. opcua.type : The OPC-UA built-in type of the attribute to be read/written. If set to DEFINED_BY_JAVA_TYPE (default), the driver will attempt to determine the OPC-UA type basing on the value type parameter value. If the read/write operation fails, it may be necessary to use one of the other values of this configuration parameter to explicitly select the type. This parameter also lists the OPC-UA types currently supported by the driver. Not all value type and opcua.type combinations are valid, the allowed ones are the following: opcua.type Allowed value.type s Recommended value.type BOOLEAN BOOLEAN BOOLEAN SBYTE INTEGER, LONG, FLOAT, DOUBLE, STRING INTEGER INT16 INTEGER, LONG, FLOAT, DOUBLE, STRING INTEGER INT32 INTEGER, LONG, FLOAT, DOUBLE, STRING INTEGER INT64 INTEGER, LONG, FLOAT, DOUBLE, STRING LONG BYTE INTEGER, LONG, FLOAT, DOUBLE, STRING INTEGER UINT16 INTEGER, LONG, FLOAT, DOUBLE, STRING INTEGER UINT32 INTEGER, LONG, FLOAT, DOUBLE, STRING LONG UINT64 INTEGER, LONG, FLOAT, DOUBLE, STRING STRING FLOAT FLOAT, STRING FLOAT DOUBLE DOUBLE, STRING DOUBLE STRING STRING STRING BYTE_STRING BYTE_ARRAY BYTE_ARRAY BYTE_ARRAY BYTE_ARRAY BYTE_ARRAY SBYTE_ARRAY BYTE_ARRAY BYTE_ARRAY Using a non allowed value.type will result in read/write operation failures. It should be noted that there is not a one to one match between the opcua.type and Java value.type . It is recommended to compare the allowed ranges for numeric types specified in OPC-UA Reference and Java reference for selecting the best match. node.id.type : The type of the node id (see the Node Id types section) attribute : The attribute of the referenced variable node. If the listen flag is enabled for an OPC-UA channel, the driver will request the server to send notifications if it detects changes in the referenced attribute value. In order to enable this, the driver will create a global subscription (one per Driver instance), and a monitored item for each channel. See [ 1 ] for more details. The Subscription publish interval global configuration parameter can be used to tune the subscription publishing interval . listen.sampling.interval : The sampling interval for the monitored item . See the Sampling interval section of [ 1 ] for more details. listen.queue.size : The queue size for the monitored item . See the Queue parameters section of [ 1 ] for more details. listen.discard.oldest : The value of the discardOldest flag for the monitored item . See the Queue parameters section of [ 1 ] for more details. The listen.subscribe.to.children parameter can be used to enable the Subtree Subscription feature. [1] MonitoredItem model Node ID types The Driver supports the following node id types: Node ID Type Format of node.id NUMERIC node.id must be parseable into an integer STRING node.id can be any string OPAQUE Opaque node ids are represented by raw byte arrays. In this case node.id must be the base64 encoding of the node id. GUID node.id must be a string conforming to the format described in the documentation of the java.util.UUID.toString() method. Certificate setup In order to use settings for Security Policy different than None , the OPCUA driver must be configured to trust the server certificate and a new client certificate - private key pair must be generated for the driver. These items can be placed in a Java keystore that can be referenced from driver configuration. The keystore does not exist by default and without it connections that use Security Policy different than None will fail. The following steps can be used to generate the keystore: Download the certificate used by the server, usually this can be done from server management UI. Copy the downloaded certificate to the gateway using SSH. Copy the following example script to the device using SSH, it can be used to import the server certificate and generate the client key pair. It can be modified if needed: #!/bin/bash # the alias for the imported server certificate SERVER_ALIAS = \"server-cert\" # the file name of the generated keystore KEYSTORE_FILE_NAME = \"opcua-keystore.ks\" # the password of the generated keystore and private keys, it is recommended to change it KEYSTORE_PASSWORD = \"changeit\" # server certificate to be imported is expected as first argument SERVER_CERTIFICATE_FILE = \" $1 \" # import existing certificate keytool -import \\ -alias \" ${ SERVER_ALIAS } \" \\ -file \" ${ SERVER_CERTIFICATE_FILE } \" \\ -keystore \" ${ KEYSTORE_FILE_NAME } \" \\ -noprompt \\ -storepass \" ${ KEYSTORE_PASSWORD } \" # alias for client certificate CLIENT_ALIAS = \"client-cert\" # client certificate distinguished name, it is recommended to change it CLIENT_DN = \"CN=MyCn, OU=MyOu, O=MyOrganization, L=Amaro, S=UD, C=IT\" # the application id, must match the corresponding parameter in driver configuration APPLICATION_ID = \"urn:kura:opcua:client\" # generate the client private key and certificate keytool -genkey \\ -alias \" ${ CLIENT_ALIAS } \" \\ -keyalg RSA \\ -keysize 4096 \\ -keystore \" ${ KEYSTORE_FILE_NAME } \" \\ -dname \" ${ CLIENT_DN } \" \\ -ext ku = digitalSignature,nonRepudiation,keyEncipherment,dataEncipherment \\ -ext eku = clientAuth \\ -ext \"san=uri: ${ APPLICATION_ID } \" \\ -validity 1000 \\ -noprompt \\ -storepass ${ KEYSTORE_PASSWORD } \\ -keypass ${ KEYSTORE_PASSWORD } Update the following parameters in driver configuration: Keystore Path : Set the absolute path of the opcua-keystore.ks file created at step 3. **Security Policy ** -> Set the desired option Client Certificate Alias -> Set the value of the CLIENT_ALIAS script variable (the default is client-cert ) Enable Server Authentication -> true Keystore type -> JKS Keystore Password -> Set the value of the KEYSTORE_PASSWORD script variable (the default value is changeit ) Application URI -> Set the value of the APPLICATION_ID script variable (default value should be already ok). Configurare the server to trust the client certificate generated at step 3. The steps required to do this vary depending on the server. Usually the following steps are needed: Make a connection attempt using OPC-UA driver, this will likely fail because the server does not trust client certificate. After the failed connection attempt, the server should display the certificate used by the driver in the administration UI. The server UI should allow to set it as trusted. Make another connection attempt once the certificate has been set to trusted, this connection attempt should succeed. Substree Subscription The driver can be configured to recursively visit the children of a folder node and create a Monitored Item for the value of each discovered variable node with a single channel in Asset configuration. Warning: This feature should be used with care since it can cause high load on both the gateway and the server if the referenced folder contains a large number of nodes and/or the notification rate is high. Channel configuration In order to configure the driver to perform the discovery operation, a single channel can be defined with the following configuration: type : READ value.type : STRING (see below) listen : true node.id : the node id of the root of the subtree to visit node.namespace.index : the namespace index of the root of the subtree to visit node.id.type the node id type of the root of the subtree to visit listen.subscribe.to.children ( NEW ): true The rest of the configuration parameters can be specified in the same way as for the single node subscription use case. The listen.sampling.interval , listen.queue.size and listen.discard.oldest parameters of the root will be used for all subscriptions on the subtree. Discovery procedure The driver will consider as folders to visit all nodes that whose type definition is FolderType , or more precisely all nodes with the following reference: HasTypeDefinition : * namespace index: 0 * node id: 61 (numeric) * URN: http://opcfoundation.org/UA/ The driver will subscribe to all the variable nodes found. Event reporting If the Driver is used by a Wire Asset, it will emit on the wire a single message per received event. All emitted events will contain a single property. Depending on the value of the Subtree subscription events channel name format global configuration parameter, the name of this property is the node id or the browsed path of the source OPCUA node relative to the root folder defined in the channel configuration. Type conversion The current version of the driver tries to convert the values received for all the events on a subtree to the type defined in the value.type configuration parameter. Since the value types of the discovered nodes are heterogeneous, the conversion might fail if the types are not compatible (e.g. if value.type is set to INTEGER and the received value is a string). Setting value.type to STRING should allow to perform safe conversions for most data types.","title":"OPC UA Driver"},{"location":"connect-field-devices/opcua-driver/#opc-ua-driver","text":"This Driver implements the client side of the OPC UA protocol using the Driver model. The Driver can be used to interact as a client with OPC UA servers using different abstractions, such as the Wires framework, the Asset model or by directly using the Driver itself. The Driver is distributed as a deployment package on Eclipse Marketplace for Kura 3.x and 4.x/5.x . It can be installed following the instructions provided here .","title":"OPC UA Driver"},{"location":"connect-field-devices/opcua-driver/#features","text":"The OPC UA Driver features include: Support for the OPC UA protocol over TCP. Support for reading and writing OPC UA variable nodes by node ID.","title":"Features"},{"location":"connect-field-devices/opcua-driver/#instance-creation","text":"A new OPC UA instance can be created either by clicking the New Driver button in the dedicated Drivers and Assets Web UI section or by clicking on the + button under Services . In both cases, the org.eclipse.kura.driver.opcua factory must be selected and a unique name must be provided for the new instance.","title":"Instance creation"},{"location":"connect-field-devices/opcua-driver/#channel-configuration","text":"The OPC UA Driver channel configuration is composed of the following parameters: name : the channel name. type : the channel type, ( READ , WRITE , or READ_WRITE ). value type : the Java type of the channel value. node.id : The node id of the variable node to be used, the format of the node id depends on the value of the node.id.type property. node.namespace.index : The namespace index of the variable node to be used. opcua.type : The OPC-UA built-in type of the attribute to be read/written. If set to DEFINED_BY_JAVA_TYPE (default), the driver will attempt to determine the OPC-UA type basing on the value type parameter value. If the read/write operation fails, it may be necessary to use one of the other values of this configuration parameter to explicitly select the type. This parameter also lists the OPC-UA types currently supported by the driver. Not all value type and opcua.type combinations are valid, the allowed ones are the following: opcua.type Allowed value.type s Recommended value.type BOOLEAN BOOLEAN BOOLEAN SBYTE INTEGER, LONG, FLOAT, DOUBLE, STRING INTEGER INT16 INTEGER, LONG, FLOAT, DOUBLE, STRING INTEGER INT32 INTEGER, LONG, FLOAT, DOUBLE, STRING INTEGER INT64 INTEGER, LONG, FLOAT, DOUBLE, STRING LONG BYTE INTEGER, LONG, FLOAT, DOUBLE, STRING INTEGER UINT16 INTEGER, LONG, FLOAT, DOUBLE, STRING INTEGER UINT32 INTEGER, LONG, FLOAT, DOUBLE, STRING LONG UINT64 INTEGER, LONG, FLOAT, DOUBLE, STRING STRING FLOAT FLOAT, STRING FLOAT DOUBLE DOUBLE, STRING DOUBLE STRING STRING STRING BYTE_STRING BYTE_ARRAY BYTE_ARRAY BYTE_ARRAY BYTE_ARRAY BYTE_ARRAY SBYTE_ARRAY BYTE_ARRAY BYTE_ARRAY Using a non allowed value.type will result in read/write operation failures. It should be noted that there is not a one to one match between the opcua.type and Java value.type . It is recommended to compare the allowed ranges for numeric types specified in OPC-UA Reference and Java reference for selecting the best match. node.id.type : The type of the node id (see the Node Id types section) attribute : The attribute of the referenced variable node. If the listen flag is enabled for an OPC-UA channel, the driver will request the server to send notifications if it detects changes in the referenced attribute value. In order to enable this, the driver will create a global subscription (one per Driver instance), and a monitored item for each channel. See [ 1 ] for more details. The Subscription publish interval global configuration parameter can be used to tune the subscription publishing interval . listen.sampling.interval : The sampling interval for the monitored item . See the Sampling interval section of [ 1 ] for more details. listen.queue.size : The queue size for the monitored item . See the Queue parameters section of [ 1 ] for more details. listen.discard.oldest : The value of the discardOldest flag for the monitored item . See the Queue parameters section of [ 1 ] for more details. The listen.subscribe.to.children parameter can be used to enable the Subtree Subscription feature. [1] MonitoredItem model","title":"Channel configuration"},{"location":"connect-field-devices/opcua-driver/#node-id-types","text":"The Driver supports the following node id types: Node ID Type Format of node.id NUMERIC node.id must be parseable into an integer STRING node.id can be any string OPAQUE Opaque node ids are represented by raw byte arrays. In this case node.id must be the base64 encoding of the node id. GUID node.id must be a string conforming to the format described in the documentation of the java.util.UUID.toString() method.","title":"Node ID types"},{"location":"connect-field-devices/opcua-driver/#certificate-setup","text":"In order to use settings for Security Policy different than None , the OPCUA driver must be configured to trust the server certificate and a new client certificate - private key pair must be generated for the driver. These items can be placed in a Java keystore that can be referenced from driver configuration. The keystore does not exist by default and without it connections that use Security Policy different than None will fail. The following steps can be used to generate the keystore: Download the certificate used by the server, usually this can be done from server management UI. Copy the downloaded certificate to the gateway using SSH. Copy the following example script to the device using SSH, it can be used to import the server certificate and generate the client key pair. It can be modified if needed: #!/bin/bash # the alias for the imported server certificate SERVER_ALIAS = \"server-cert\" # the file name of the generated keystore KEYSTORE_FILE_NAME = \"opcua-keystore.ks\" # the password of the generated keystore and private keys, it is recommended to change it KEYSTORE_PASSWORD = \"changeit\" # server certificate to be imported is expected as first argument SERVER_CERTIFICATE_FILE = \" $1 \" # import existing certificate keytool -import \\ -alias \" ${ SERVER_ALIAS } \" \\ -file \" ${ SERVER_CERTIFICATE_FILE } \" \\ -keystore \" ${ KEYSTORE_FILE_NAME } \" \\ -noprompt \\ -storepass \" ${ KEYSTORE_PASSWORD } \" # alias for client certificate CLIENT_ALIAS = \"client-cert\" # client certificate distinguished name, it is recommended to change it CLIENT_DN = \"CN=MyCn, OU=MyOu, O=MyOrganization, L=Amaro, S=UD, C=IT\" # the application id, must match the corresponding parameter in driver configuration APPLICATION_ID = \"urn:kura:opcua:client\" # generate the client private key and certificate keytool -genkey \\ -alias \" ${ CLIENT_ALIAS } \" \\ -keyalg RSA \\ -keysize 4096 \\ -keystore \" ${ KEYSTORE_FILE_NAME } \" \\ -dname \" ${ CLIENT_DN } \" \\ -ext ku = digitalSignature,nonRepudiation,keyEncipherment,dataEncipherment \\ -ext eku = clientAuth \\ -ext \"san=uri: ${ APPLICATION_ID } \" \\ -validity 1000 \\ -noprompt \\ -storepass ${ KEYSTORE_PASSWORD } \\ -keypass ${ KEYSTORE_PASSWORD } Update the following parameters in driver configuration: Keystore Path : Set the absolute path of the opcua-keystore.ks file created at step 3. **Security Policy ** -> Set the desired option Client Certificate Alias -> Set the value of the CLIENT_ALIAS script variable (the default is client-cert ) Enable Server Authentication -> true Keystore type -> JKS Keystore Password -> Set the value of the KEYSTORE_PASSWORD script variable (the default value is changeit ) Application URI -> Set the value of the APPLICATION_ID script variable (default value should be already ok). Configurare the server to trust the client certificate generated at step 3. The steps required to do this vary depending on the server. Usually the following steps are needed: Make a connection attempt using OPC-UA driver, this will likely fail because the server does not trust client certificate. After the failed connection attempt, the server should display the certificate used by the driver in the administration UI. The server UI should allow to set it as trusted. Make another connection attempt once the certificate has been set to trusted, this connection attempt should succeed.","title":"Certificate setup"},{"location":"connect-field-devices/opcua-driver/#substree-subscription","text":"The driver can be configured to recursively visit the children of a folder node and create a Monitored Item for the value of each discovered variable node with a single channel in Asset configuration. Warning: This feature should be used with care since it can cause high load on both the gateway and the server if the referenced folder contains a large number of nodes and/or the notification rate is high.","title":"Substree Subscription"},{"location":"connect-field-devices/opcua-driver/#channel-configuration_1","text":"In order to configure the driver to perform the discovery operation, a single channel can be defined with the following configuration: type : READ value.type : STRING (see below) listen : true node.id : the node id of the root of the subtree to visit node.namespace.index : the namespace index of the root of the subtree to visit node.id.type the node id type of the root of the subtree to visit listen.subscribe.to.children ( NEW ): true The rest of the configuration parameters can be specified in the same way as for the single node subscription use case. The listen.sampling.interval , listen.queue.size and listen.discard.oldest parameters of the root will be used for all subscriptions on the subtree.","title":"Channel configuration"},{"location":"connect-field-devices/opcua-driver/#discovery-procedure","text":"The driver will consider as folders to visit all nodes that whose type definition is FolderType , or more precisely all nodes with the following reference: HasTypeDefinition : * namespace index: 0 * node id: 61 (numeric) * URN: http://opcfoundation.org/UA/ The driver will subscribe to all the variable nodes found.","title":"Discovery procedure"},{"location":"connect-field-devices/opcua-driver/#event-reporting","text":"If the Driver is used by a Wire Asset, it will emit on the wire a single message per received event. All emitted events will contain a single property. Depending on the value of the Subtree subscription events channel name format global configuration parameter, the name of this property is the node id or the browsed path of the source OPCUA node relative to the root folder defined in the channel configuration.","title":"Event reporting"},{"location":"connect-field-devices/opcua-driver/#type-conversion","text":"The current version of the driver tries to convert the values received for all the events on a subtree to the type defined in the value.type configuration parameter. Since the value types of the discovered nodes are heterogeneous, the conversion might fail if the types are not compatible (e.g. if value.type is set to INTEGER and the received value is a string). Setting value.type to STRING should allow to perform safe conversions for most data types.","title":"Type conversion"},{"location":"connect-field-devices/s7-driver/","text":"S7comm Driver This Driver implements the s7comm protocol and can be used to interact with Siemens S7 PLCs using different abstractions, such as the Wires framework, the Asset model or by directly using the Driver itself. The Driver is distributed as a deployment package on the Eclipse Marketplace for Kura 3.x and 4.x/5.x . It can be installed following the instructions provided here . Features The S7comm Plc Driver features include: Support for the s7comm protocol over TCP. Support for reading and writing data from the Data Blocks (DB) memory areas. The driver is capable of automatically aggregating reads/writes for contiguous data in larger bulk requests in order to reduce IO times. Instance creation A new S7comm driver instance can be created either by clicking the New Driver button in the dedicated Drivers and Assets Web UI section or by clicking on the + button under Services . In both cases, the org.eclipse.kura.driver.s7plc factory must be selected and a unique name must be provided for the new instance. Channel configuration The S7 Driver channel configuration is composed of the following parameters: name : the channel name. type : the channel type, ( READ , WRITE , or READ_WRITE ). value type : the Java type of the channel value. s7.data.type : the S7 data type involved in channel operation. data.block.no : the data block number involved in channel operation. offset : the start address of the data. byte.count : the size in bytes of the transferred data. This parameter is required only if the value type parameter is set to STRING or BYTE_ARRAY . In the other cases, this parameter is ignored and the data size is automatically derived from the s7.data.type . bit.index : the index of the bit involved in channel operation inside its containing byte, index 0 is the least significant bit. This parameter is required only if the value type parameter is set to BOOLEAN and s7.data.type is set to BOOL . In the other cases, this parameter is ignored. Data Types When performing operations that deal with numeric data, two data types are involved: The Java primitive type that is used in the ChannelRecords exchanged between the driver and Java applications. (the Java type of the value received/supplied by external applications from/to the Driver in case of a read/write operation). This value type is specified by the value type configuration property. The S7 type of the data on the PLC. This value type is specified by the s7.data.type configuration property. The following S7 data types are supported: S7 Data Type Size Sign INT 16 bits signed DINT 32 bits signed WORD 16 bits unsigned DWORD 32 bits unsigned REAL 32 bits signed BOOL 1 bit n.d. BYTE 1 byte unsigned CHAR 1 byte (only supported as char arrays using the String Java data type) n.d. The Driver automatically adapts the data type used by external applications and the S7 device depending on the value of the two configuration properties mentioned above. The adaptation process involves the following steps: Each device data type is internally converted by the driver from/to a Java type large enough to represent the value of the device data without losing precision. The type mappings are the following: S7 Data Type Java Type INT int DINT int WORD int DWORD long REAL float BOOL boolean BYTE int If the value type of the channel does not match the Java type specified in mapping above, a conversion is performed by the Driver to convert it to/from the matching type, choosing appropriately between the Number.toInt() , Number.toLong() , Number.toFloat() or Number.toDouble() methods. Precision losses may occur if the Java type used by the external application is not suitable to represent all possible values of the device data type. Array Data The driver supports transferring data as raw byte arrays or ASCII strings: Byte arrays : For transferring data as byte arrays the channel value type property must be set to BYTE_ARRAY , the data.type configuration property must be set to BYTE and the byte.count property must be set to the data length in bytes. Strings : For transferring data as ASCII strings the channel value type property must be set to STRING , the data.type configuration property must be set to CHAR and the array.data.length property must be set to the data length in bytes. Writing Single Bits The Driver supports setting the value of single bits without overwriting the other bits of the same byte. This operation can be performed defining a channel having BOOLEAN as value type , BOOL as s7.data.type and the proper index set to the bit.index property. The Driver will fetch the byte containing the bit to be written, update its contents and then write back the obtained value. If multiple bits on the same byte need to be modified, the driver will perform only one read and write for that byte. If bits that need to be changed are located in contiguous bytes, the driver will perform only one bulk read and one bulk write transferring all the required data in a single request.","title":"S7comm Driver"},{"location":"connect-field-devices/s7-driver/#s7comm-driver","text":"This Driver implements the s7comm protocol and can be used to interact with Siemens S7 PLCs using different abstractions, such as the Wires framework, the Asset model or by directly using the Driver itself. The Driver is distributed as a deployment package on the Eclipse Marketplace for Kura 3.x and 4.x/5.x . It can be installed following the instructions provided here .","title":"S7comm Driver"},{"location":"connect-field-devices/s7-driver/#features","text":"The S7comm Plc Driver features include: Support for the s7comm protocol over TCP. Support for reading and writing data from the Data Blocks (DB) memory areas. The driver is capable of automatically aggregating reads/writes for contiguous data in larger bulk requests in order to reduce IO times.","title":"Features"},{"location":"connect-field-devices/s7-driver/#instance-creation","text":"A new S7comm driver instance can be created either by clicking the New Driver button in the dedicated Drivers and Assets Web UI section or by clicking on the + button under Services . In both cases, the org.eclipse.kura.driver.s7plc factory must be selected and a unique name must be provided for the new instance.","title":"Instance creation"},{"location":"connect-field-devices/s7-driver/#channel-configuration","text":"The S7 Driver channel configuration is composed of the following parameters: name : the channel name. type : the channel type, ( READ , WRITE , or READ_WRITE ). value type : the Java type of the channel value. s7.data.type : the S7 data type involved in channel operation. data.block.no : the data block number involved in channel operation. offset : the start address of the data. byte.count : the size in bytes of the transferred data. This parameter is required only if the value type parameter is set to STRING or BYTE_ARRAY . In the other cases, this parameter is ignored and the data size is automatically derived from the s7.data.type . bit.index : the index of the bit involved in channel operation inside its containing byte, index 0 is the least significant bit. This parameter is required only if the value type parameter is set to BOOLEAN and s7.data.type is set to BOOL . In the other cases, this parameter is ignored.","title":"Channel configuration"},{"location":"connect-field-devices/s7-driver/#data-types","text":"When performing operations that deal with numeric data, two data types are involved: The Java primitive type that is used in the ChannelRecords exchanged between the driver and Java applications. (the Java type of the value received/supplied by external applications from/to the Driver in case of a read/write operation). This value type is specified by the value type configuration property. The S7 type of the data on the PLC. This value type is specified by the s7.data.type configuration property. The following S7 data types are supported: S7 Data Type Size Sign INT 16 bits signed DINT 32 bits signed WORD 16 bits unsigned DWORD 32 bits unsigned REAL 32 bits signed BOOL 1 bit n.d. BYTE 1 byte unsigned CHAR 1 byte (only supported as char arrays using the String Java data type) n.d. The Driver automatically adapts the data type used by external applications and the S7 device depending on the value of the two configuration properties mentioned above. The adaptation process involves the following steps: Each device data type is internally converted by the driver from/to a Java type large enough to represent the value of the device data without losing precision. The type mappings are the following: S7 Data Type Java Type INT int DINT int WORD int DWORD long REAL float BOOL boolean BYTE int If the value type of the channel does not match the Java type specified in mapping above, a conversion is performed by the Driver to convert it to/from the matching type, choosing appropriately between the Number.toInt() , Number.toLong() , Number.toFloat() or Number.toDouble() methods. Precision losses may occur if the Java type used by the external application is not suitable to represent all possible values of the device data type.","title":"Data Types"},{"location":"connect-field-devices/s7-driver/#array-data","text":"The driver supports transferring data as raw byte arrays or ASCII strings: Byte arrays : For transferring data as byte arrays the channel value type property must be set to BYTE_ARRAY , the data.type configuration property must be set to BYTE and the byte.count property must be set to the data length in bytes. Strings : For transferring data as ASCII strings the channel value type property must be set to STRING , the data.type configuration property must be set to CHAR and the array.data.length property must be set to the data length in bytes.","title":"Array Data"},{"location":"connect-field-devices/s7-driver/#writing-single-bits","text":"The Driver supports setting the value of single bits without overwriting the other bits of the same byte. This operation can be performed defining a channel having BOOLEAN as value type , BOOL as s7.data.type and the proper index set to the bit.index property. The Driver will fetch the byte containing the bit to be written, update its contents and then write back the obtained value. If multiple bits on the same byte need to be modified, the driver will perform only one read and write for that byte. If bits that need to be changed are located in contiguous bytes, the driver will perform only one bulk read and one bulk write transferring all the required data in a single request.","title":"Writing Single Bits"},{"location":"connect-field-devices/sensehat-driver/","text":"RaspberryPi SenseHat driver The SenseHat driver allows to interact to a RaspberryPi SenseHat device using Kura Driver, Asset and Wires frameworks. The driver allows access to the following resources: Sensors Joystick LED Matrix The driver-specific channel configuration contains a single parameter, resource , which allows to select the specific device resource that the channel is addressing (a sensor, a joystick event, etc). Note about running on OpenJDK If some exceptions reporting Locked by other application are visible in the log and the driver fails to start, try switching to the Oracle JVM by installing the oracle-java8-jdk package. For more information on the problem, please see this GitHub issue. Installation As the others Drivers supported by Kura, it is distributed as a deployment package on the Eclipse Marketplace here . It can be installed following the instructions provided here . In order to use the driver, the Sensehat Support Library Bundle for Eclipse Kura needs to be installed as a prerequisite dependency. It is available from Eclipse Marketplace here . Sensors The following values of the resource parameters refer to device sensors: Resource Unit Description ACCELERATION_X , ACCELERATION_Y , ACCELERATION_Z G The proper acceleration for each axis GYROSCOPE_X , GYROSCOPE_Y , GYROSCOPE_Z rad/S The angular acceleration for each axis MAGNETOMETER_X , MAGNETOMETER_Y , MAGNETOMETERE_Z uT The magnetometer value for each axis HUMIDITY %rH The relative humidity PRESSURE mbar The pressure value TEMPERATURE_FROM_HUMIDITY \u00b0C The temperature obtained from the humidity sensor TEMPERATURE_FROM_PRESSURE \u00b0C The temperature obtained from the pressure sensor The channels referencing sensor resources can only be used for reads and only in polling mode. The driver will attempt to convert the value obtained from the sensor into the data type selected using the value.type parameter Example sensors Asset configuration: Joystick The SenseHat joystick provides four buttons: UP DOWN LEFT RIGHT ENTER For each button, the driver allows to listen to the following events: PRESS : Fired once when a button is pressed RELEASE : Fired once when a button is released HOLD : Fired periodically every few seconds if the button is kept pressed The values of the resource parameter related to joystick have the following structure: JOYSTICK_{BUTTON}_{EVENT} Channels referencing joystick events must use LONG as value.type . The channel value supplied by the driver is the Java timestamp in milliseconds of the Joystick event, a value of 0 signifies that no events have been observed yet. Joystick related channels can be only used for reading and both in polling and event-driven mode. Example joystick Asset configuration: LED Matrix The driver allows accessing the SenseHat LED matrix in two ways: Using a monochrome framebuffer Using a RGB565 framebuffer Coordinates The coordinate system used by the driver defines the x coordinate as increasing along the direction identified by the joystick RIGHT button and the y coordinate increasing along the direction identified by the DOWN joystick button. Monochrome framebuffer In monochrome mode, only two colors will be used: the front color and the back color. Front and back colors Front and back colors can be configured using channels having the following values for the resource parameter: LED_MATRIX_FRONT_COLOR_R LED_MATRIX_FRONT_COLOR_G LED_MATRIX_FRONT_COLOR_B LED_MATRIX_BACK_COLOR_R LED_MATRIX_BACK_COLOR_G LED_MATRIX_BACK_COLOR_B These channel types allow to set the rgb components of the front and back color and can only be used in write mode. The supplied value must be a floating point number between 0 (led turned off) and 1 (full brightness). Note: Front and back colors are internally represented using the RGB565 format. The available colors are only the ones that can be represented using RGB565 and are supported by the device. Front and back color are retained for successive draw operations, the initial value for both colors is black (led turned off). Drawing The following resources can be used for modifying framebuffer contents: LED_MATRIX_FB_MONOCHROME : A channel of this type allows to set the framebuffer contents in monochrome mode. It can only be used in write mode and its value.type must be BYTE_ARRAY . The supplied value must be a byte array of length 64 that represent the state of the 8x8 led matrix. The offset in the array of a pixel having coordinates (x, y) is y*8 + x . The back/front color will be used for a pixel if the corresponding byte in the array is zero/non-zero. LED_MATRIX_CHARS : A channel of this type allows showing a text message using the LED matrix. It can only be used for writing and its value.type must be STRING . The characters of the message will be rendered using the front color and the background using the back color. RGB565 framebuffer The following resource allows writing the framebuffer using the RGB565 format: LED_MATRIX_FB_RGB565 : A channel of this type allows to set the framebuffer contents in RGB565 mode. It can only be used in write mode and its value.type must be BYTE_ARRAY . The supplied value must be a byte array of length 128 that represents the state of the 8x8 led matrix. Each pixel is represented by two consecutive bytes in the following way: | MSB | LSB | | RRRRRGGG | GGGBBBBB | | 15 ... 8 | 7 ... 0 | The LSB must be stored first in the array, the offset of the LSB and MSB for a pixel at coordinates (x, y) is the following: LSB : 2*(y*8 + x) MSB : 2*(y*8 + x) + 1 Mode independent resources LED_MATRIX_CLEAR : Writing anything to a LED_MATRIX_CLEAR channel will clear the framebuffer turning off all leds. LED_MATRIX_ROTATION : Allows to rotate the framebuffer of 0, 90, 180, and 170 degrees clockwise. Rotation setting will be retained for successive draw operations. The default value is 0. Writes to a LED_MATRIX_ROTATION channel can be performed using any numeric type as value.type . Example framebuffer Asset configuration: Examples This section contains some examples describing how to use the driver using Kura Wires and the Wires Script filter. Moving a pixel using the Joystick Open the Wires section of the Kura Web UI. Create an Asset that emits joystick events like the one described in the Joystick section. Only left_release , right_release , up_release and down_release channels will be used. Make sure to enable the listen flag for the channels. Create the Asset described in the LED Matrix section. Create a Script Filter and paste the code below in the script field. Connect the Joystick Asset to the input port of the Script Filter, and the output port of the Script filter to the framebuffer Asset. Open the Drivers and Assets section of the Kura Web UI, select the framebuffer Asset, click on the Data tab and select front and back colors. For example for using green as front color and red as back color, write 1 as Value for the front_g and back_r channels. You should now be able to move the green pixel with the joystick. var FB_SIZE = 8 if ( typeof ( state ) === 'undefined' ) { // framebuffer as byte array (0 -> back color, non zero -> front color) var fb = newByteArray ( FB_SIZE * FB_SIZE | 0 ) // record to be emitted for updating the fb var outRecord = newWireRecord () // property in emitted record containing fb data // change the name if needed // should match the name of a channel configured as LED_MATRIX_FB_MONOCHROME outRecord [ 'fb_mono' ] = newByteArrayValue ( fb ) state = { fb : fb , outRecord : outRecord , x : 0 , // current pixel position y : 0 , dx : 0 , // deltas to be added to pixel position dy : 0 , } } if ( typeof ( actions ) === 'undefined' ) { // associations between input property names // and position update actions, // input can be supplied using an Asset // with joystick event channels actions = { 'up_release' : function () { // decrease y coordinate state . dy = - 1 }, 'down_release' : function () { // increase y coordinate state . dy = 1 }, 'left_release' : function () { // decrease x coordinate state . dx = - 1 }, 'right_release' : function () { // increase x coordinate state . dx = 1 } } } if ( input . records . length ) { var input = input . records [ 0 ] var update = false for ( var prop in input ) { var action = actions [ prop ] // if there is an action associated with the received property, execute it if ( action ) { action () // request framebuffer update update = true } } if ( update ) { // framebuffer update requested // clear old pixel state . fb [ state . y * FB_SIZE + state . x ] = 0 // compute new pixel position state . x = ( state . x + state . dx + FB_SIZE ) % FB_SIZE state . y = ( state . y + state . dy + FB_SIZE ) % FB_SIZE // set new pixel state . fb [ state . y * FB_SIZE + state . x ] = 1 // clear deltas state . dx = 0 state . dy = 0 // emit record output . add ( state . outRecord ) } } Using RGB565 framebuffer Open the Wires section of the Kura Web UI. Create the Asset described in the LED Matrix section. Create a Script Filter and paste the code below in the script field. Create a Timer that ticks every 16 milliseconds. Connect the Timer to the input port of the Script Filter, and the output port of the Script filter to the framebuffer Asset. The framebuffer should now display an animation, the animation can be changed by modifying the wave parameters and setting script.context.drop to false. var FB_SIZE = 8 var BYTES_PER_PIXEL = 2 if ( typeof ( state ) === 'undefined' ) { // framebuffer as RGB565 byte array var fb = newByteArray ( FB_SIZE * FB_SIZE * BYTES_PER_PIXEL | 0 ) // record to be emitted for updating the fb var outRecord = newWireRecord () // property in emitted record containing fb data // change the name if needed // must match the name of a channel configured as LED_MATRIX_FB_565 outRecord [ 'fb_rgb565' ] = newByteArrayValue ( fb ) // framebuffer array and output record state = { fb : fb , outRecord : outRecord , } RMASK = (( 1 << 5 ) - 1 ) GMASK = (( 1 << 6 ) - 1 ) BMASK = RMASK // converts the r, g, b values provided as a floating point // number between 0 and 1 to RGB565 and stores the result // inside the output array function putPixel ( off , r , g , b ) { var _r = Math . floor ( r * RMASK ) & 0xff var _g = Math . floor ( g * GMASK ) & 0xff var _b = Math . floor ( b * BMASK ) & 0xff var b0 = ( _r << 3 | _g >> 3 ) var b1 = ( _g << 5 | _b ) state . fb [ off + 1 ] = b0 state . fb [ off ] = b1 } // parameters for 3 sin waves, one per color component RED_WAVE_PARAMS = { a : 5 , b : 10 , c : 10 , d : 0 } GREEN_WAVE_PARAMS = { a : 5 , b : 10 , c : 10 , d : 1 } BLUE_WAVE_PARAMS = { a : 5 , b : 10 , c : 10 , d : 2 } function wave ( x , y , t , params ) { return Math . abs ( Math . sin ( 2 * Math . PI * ( t + x / params . b + y / params . c + params . d ) / params . a )) } } var t = new Date (). getTime () / 1000 var off = 0 for ( var y = 0 ; y < FB_SIZE ; y ++ ) for ( var x = 0 ; x < FB_SIZE ; x ++ ) { var r = wave ( x , y , t , RED_WAVE_PARAMS ) var g = wave ( x , y , t , GREEN_WAVE_PARAMS ) var b = wave ( x , y , t , BLUE_WAVE_PARAMS ) putPixel ( off , r , g , b ) off += 2 } output . add ( state . outRecord )","title":"RaspberryPi SenseHat driver"},{"location":"connect-field-devices/sensehat-driver/#raspberrypi-sensehat-driver","text":"The SenseHat driver allows to interact to a RaspberryPi SenseHat device using Kura Driver, Asset and Wires frameworks. The driver allows access to the following resources: Sensors Joystick LED Matrix The driver-specific channel configuration contains a single parameter, resource , which allows to select the specific device resource that the channel is addressing (a sensor, a joystick event, etc). Note about running on OpenJDK If some exceptions reporting Locked by other application are visible in the log and the driver fails to start, try switching to the Oracle JVM by installing the oracle-java8-jdk package. For more information on the problem, please see this GitHub issue.","title":"RaspberryPi SenseHat driver"},{"location":"connect-field-devices/sensehat-driver/#installation","text":"As the others Drivers supported by Kura, it is distributed as a deployment package on the Eclipse Marketplace here . It can be installed following the instructions provided here . In order to use the driver, the Sensehat Support Library Bundle for Eclipse Kura needs to be installed as a prerequisite dependency. It is available from Eclipse Marketplace here .","title":"Installation"},{"location":"connect-field-devices/sensehat-driver/#sensors","text":"The following values of the resource parameters refer to device sensors: Resource Unit Description ACCELERATION_X , ACCELERATION_Y , ACCELERATION_Z G The proper acceleration for each axis GYROSCOPE_X , GYROSCOPE_Y , GYROSCOPE_Z rad/S The angular acceleration for each axis MAGNETOMETER_X , MAGNETOMETER_Y , MAGNETOMETERE_Z uT The magnetometer value for each axis HUMIDITY %rH The relative humidity PRESSURE mbar The pressure value TEMPERATURE_FROM_HUMIDITY \u00b0C The temperature obtained from the humidity sensor TEMPERATURE_FROM_PRESSURE \u00b0C The temperature obtained from the pressure sensor The channels referencing sensor resources can only be used for reads and only in polling mode. The driver will attempt to convert the value obtained from the sensor into the data type selected using the value.type parameter Example sensors Asset configuration:","title":"Sensors"},{"location":"connect-field-devices/sensehat-driver/#joystick","text":"The SenseHat joystick provides four buttons: UP DOWN LEFT RIGHT ENTER For each button, the driver allows to listen to the following events: PRESS : Fired once when a button is pressed RELEASE : Fired once when a button is released HOLD : Fired periodically every few seconds if the button is kept pressed The values of the resource parameter related to joystick have the following structure: JOYSTICK_{BUTTON}_{EVENT} Channels referencing joystick events must use LONG as value.type . The channel value supplied by the driver is the Java timestamp in milliseconds of the Joystick event, a value of 0 signifies that no events have been observed yet. Joystick related channels can be only used for reading and both in polling and event-driven mode. Example joystick Asset configuration:","title":"Joystick"},{"location":"connect-field-devices/sensehat-driver/#led-matrix","text":"The driver allows accessing the SenseHat LED matrix in two ways: Using a monochrome framebuffer Using a RGB565 framebuffer","title":"LED Matrix"},{"location":"connect-field-devices/sensehat-driver/#coordinates","text":"The coordinate system used by the driver defines the x coordinate as increasing along the direction identified by the joystick RIGHT button and the y coordinate increasing along the direction identified by the DOWN joystick button.","title":"Coordinates"},{"location":"connect-field-devices/sensehat-driver/#monochrome-framebuffer","text":"In monochrome mode, only two colors will be used: the front color and the back color.","title":"Monochrome framebuffer"},{"location":"connect-field-devices/sensehat-driver/#front-and-back-colors","text":"Front and back colors can be configured using channels having the following values for the resource parameter: LED_MATRIX_FRONT_COLOR_R LED_MATRIX_FRONT_COLOR_G LED_MATRIX_FRONT_COLOR_B LED_MATRIX_BACK_COLOR_R LED_MATRIX_BACK_COLOR_G LED_MATRIX_BACK_COLOR_B These channel types allow to set the rgb components of the front and back color and can only be used in write mode. The supplied value must be a floating point number between 0 (led turned off) and 1 (full brightness). Note: Front and back colors are internally represented using the RGB565 format. The available colors are only the ones that can be represented using RGB565 and are supported by the device. Front and back color are retained for successive draw operations, the initial value for both colors is black (led turned off).","title":"Front and back colors"},{"location":"connect-field-devices/sensehat-driver/#drawing","text":"The following resources can be used for modifying framebuffer contents: LED_MATRIX_FB_MONOCHROME : A channel of this type allows to set the framebuffer contents in monochrome mode. It can only be used in write mode and its value.type must be BYTE_ARRAY . The supplied value must be a byte array of length 64 that represent the state of the 8x8 led matrix. The offset in the array of a pixel having coordinates (x, y) is y*8 + x . The back/front color will be used for a pixel if the corresponding byte in the array is zero/non-zero. LED_MATRIX_CHARS : A channel of this type allows showing a text message using the LED matrix. It can only be used for writing and its value.type must be STRING . The characters of the message will be rendered using the front color and the background using the back color.","title":"Drawing"},{"location":"connect-field-devices/sensehat-driver/#rgb565-framebuffer","text":"The following resource allows writing the framebuffer using the RGB565 format: LED_MATRIX_FB_RGB565 : A channel of this type allows to set the framebuffer contents in RGB565 mode. It can only be used in write mode and its value.type must be BYTE_ARRAY . The supplied value must be a byte array of length 128 that represents the state of the 8x8 led matrix. Each pixel is represented by two consecutive bytes in the following way: | MSB | LSB | | RRRRRGGG | GGGBBBBB | | 15 ... 8 | 7 ... 0 | The LSB must be stored first in the array, the offset of the LSB and MSB for a pixel at coordinates (x, y) is the following: LSB : 2*(y*8 + x) MSB : 2*(y*8 + x) + 1","title":"RGB565 framebuffer"},{"location":"connect-field-devices/sensehat-driver/#mode-independent-resources","text":"LED_MATRIX_CLEAR : Writing anything to a LED_MATRIX_CLEAR channel will clear the framebuffer turning off all leds. LED_MATRIX_ROTATION : Allows to rotate the framebuffer of 0, 90, 180, and 170 degrees clockwise. Rotation setting will be retained for successive draw operations. The default value is 0. Writes to a LED_MATRIX_ROTATION channel can be performed using any numeric type as value.type . Example framebuffer Asset configuration:","title":"Mode independent resources"},{"location":"connect-field-devices/sensehat-driver/#examples","text":"This section contains some examples describing how to use the driver using Kura Wires and the Wires Script filter.","title":"Examples"},{"location":"connect-field-devices/sensehat-driver/#moving-a-pixel-using-the-joystick","text":"Open the Wires section of the Kura Web UI. Create an Asset that emits joystick events like the one described in the Joystick section. Only left_release , right_release , up_release and down_release channels will be used. Make sure to enable the listen flag for the channels. Create the Asset described in the LED Matrix section. Create a Script Filter and paste the code below in the script field. Connect the Joystick Asset to the input port of the Script Filter, and the output port of the Script filter to the framebuffer Asset. Open the Drivers and Assets section of the Kura Web UI, select the framebuffer Asset, click on the Data tab and select front and back colors. For example for using green as front color and red as back color, write 1 as Value for the front_g and back_r channels. You should now be able to move the green pixel with the joystick. var FB_SIZE = 8 if ( typeof ( state ) === 'undefined' ) { // framebuffer as byte array (0 -> back color, non zero -> front color) var fb = newByteArray ( FB_SIZE * FB_SIZE | 0 ) // record to be emitted for updating the fb var outRecord = newWireRecord () // property in emitted record containing fb data // change the name if needed // should match the name of a channel configured as LED_MATRIX_FB_MONOCHROME outRecord [ 'fb_mono' ] = newByteArrayValue ( fb ) state = { fb : fb , outRecord : outRecord , x : 0 , // current pixel position y : 0 , dx : 0 , // deltas to be added to pixel position dy : 0 , } } if ( typeof ( actions ) === 'undefined' ) { // associations between input property names // and position update actions, // input can be supplied using an Asset // with joystick event channels actions = { 'up_release' : function () { // decrease y coordinate state . dy = - 1 }, 'down_release' : function () { // increase y coordinate state . dy = 1 }, 'left_release' : function () { // decrease x coordinate state . dx = - 1 }, 'right_release' : function () { // increase x coordinate state . dx = 1 } } } if ( input . records . length ) { var input = input . records [ 0 ] var update = false for ( var prop in input ) { var action = actions [ prop ] // if there is an action associated with the received property, execute it if ( action ) { action () // request framebuffer update update = true } } if ( update ) { // framebuffer update requested // clear old pixel state . fb [ state . y * FB_SIZE + state . x ] = 0 // compute new pixel position state . x = ( state . x + state . dx + FB_SIZE ) % FB_SIZE state . y = ( state . y + state . dy + FB_SIZE ) % FB_SIZE // set new pixel state . fb [ state . y * FB_SIZE + state . x ] = 1 // clear deltas state . dx = 0 state . dy = 0 // emit record output . add ( state . outRecord ) } }","title":"Moving a pixel using the Joystick"},{"location":"connect-field-devices/sensehat-driver/#using-rgb565-framebuffer","text":"Open the Wires section of the Kura Web UI. Create the Asset described in the LED Matrix section. Create a Script Filter and paste the code below in the script field. Create a Timer that ticks every 16 milliseconds. Connect the Timer to the input port of the Script Filter, and the output port of the Script filter to the framebuffer Asset. The framebuffer should now display an animation, the animation can be changed by modifying the wave parameters and setting script.context.drop to false. var FB_SIZE = 8 var BYTES_PER_PIXEL = 2 if ( typeof ( state ) === 'undefined' ) { // framebuffer as RGB565 byte array var fb = newByteArray ( FB_SIZE * FB_SIZE * BYTES_PER_PIXEL | 0 ) // record to be emitted for updating the fb var outRecord = newWireRecord () // property in emitted record containing fb data // change the name if needed // must match the name of a channel configured as LED_MATRIX_FB_565 outRecord [ 'fb_rgb565' ] = newByteArrayValue ( fb ) // framebuffer array and output record state = { fb : fb , outRecord : outRecord , } RMASK = (( 1 << 5 ) - 1 ) GMASK = (( 1 << 6 ) - 1 ) BMASK = RMASK // converts the r, g, b values provided as a floating point // number between 0 and 1 to RGB565 and stores the result // inside the output array function putPixel ( off , r , g , b ) { var _r = Math . floor ( r * RMASK ) & 0xff var _g = Math . floor ( g * GMASK ) & 0xff var _b = Math . floor ( b * BMASK ) & 0xff var b0 = ( _r << 3 | _g >> 3 ) var b1 = ( _g << 5 | _b ) state . fb [ off + 1 ] = b0 state . fb [ off ] = b1 } // parameters for 3 sin waves, one per color component RED_WAVE_PARAMS = { a : 5 , b : 10 , c : 10 , d : 0 } GREEN_WAVE_PARAMS = { a : 5 , b : 10 , c : 10 , d : 1 } BLUE_WAVE_PARAMS = { a : 5 , b : 10 , c : 10 , d : 2 } function wave ( x , y , t , params ) { return Math . abs ( Math . sin ( 2 * Math . PI * ( t + x / params . b + y / params . c + params . d ) / params . a )) } } var t = new Date (). getTime () / 1000 var off = 0 for ( var y = 0 ; y < FB_SIZE ; y ++ ) for ( var x = 0 ; x < FB_SIZE ; x ++ ) { var r = wave ( x , y , t , RED_WAVE_PARAMS ) var g = wave ( x , y , t , GREEN_WAVE_PARAMS ) var b = wave ( x , y , t , BLUE_WAVE_PARAMS ) putPixel ( off , r , g , b ) off += 2 } output . add ( state . outRecord )","title":"Using RGB565 framebuffer"},{"location":"connect-field-devices/sensortag-driver/","text":"TI SensorTag Driver Eclipse Kura provides a specific driver that can be used to interact with Texas Instruments SensorTag devices. The driver is available only for gateways that support the new Bluetooth LE APIs. It can be used in the Wires framework, the Asset model or directly using the Driver itself. Warning The SensorTag driver can be used only with TI SensorTags with firmware version >1.20. If your device has an older firmware, please update it. Features The SensorTag Driver can be used to get the values from all the sensor installed on the tag (both in polling mode and notification): ambient and target temperature humidity pressure three-axis acceleration three-axis magnetic field three-axis orientation light push buttons Moreover, the following resources can be written by the driver: - read and green leds - buzzer When a notification is enabled for a specific channel (sensor), the notification period can be set. Installation As the other Drivers supported by Kura, it is distributed as a deployment package on the Eclipse Marketplace here and here . It can be installed following the instructions provided here . Instance creation A new TiSensorTag Driver instance can be created either by clicking the New Driver button in the dedicated Drivers and Assets Web UI section or by clicking on the + button under Services . In both cases, the org.eclipse.kura.driver.ble.sensortag factory must be selected and a unique name must be provided for the new instance. Once instantiated, the SensorTag Driver has to be configured setting the Bluetooth interface name (i.e. hci0) that will be used to connect to the device. Channel configuration The SensorTag Driver channel can be configured with the following parameters: enabled : it allows to enable/disable the channel. If it isn't selected the channel will be ignored. name : the channel name. type : the channel type, ( READ , WRITE , or READ_WRITE ). value.type : the Java type of the channel value. The value read by the Driver will be converted to the value.type . Conversely, in write operations the Driver will accept value of this kind. listen : when selected, a listener will be attached to this channel. Any event on the channel will be reported using a callback and the value will be emitted. sensortag.address : the address of the specific SensorTag (i.e. aa:bb:cc:dd:ee:ff) sensor.name : the name of the sensor. It can be selected from a drop-down list notification.period : the period in milliseconds used to receive notification for a specific sensor. The value will be ignored it the listen option is not checked.","title":"TI SensorTag Driver"},{"location":"connect-field-devices/sensortag-driver/#ti-sensortag-driver","text":"Eclipse Kura provides a specific driver that can be used to interact with Texas Instruments SensorTag devices. The driver is available only for gateways that support the new Bluetooth LE APIs. It can be used in the Wires framework, the Asset model or directly using the Driver itself. Warning The SensorTag driver can be used only with TI SensorTags with firmware version >1.20. If your device has an older firmware, please update it.","title":"TI SensorTag Driver"},{"location":"connect-field-devices/sensortag-driver/#features","text":"The SensorTag Driver can be used to get the values from all the sensor installed on the tag (both in polling mode and notification): ambient and target temperature humidity pressure three-axis acceleration three-axis magnetic field three-axis orientation light push buttons Moreover, the following resources can be written by the driver: - read and green leds - buzzer When a notification is enabled for a specific channel (sensor), the notification period can be set.","title":"Features"},{"location":"connect-field-devices/sensortag-driver/#installation","text":"As the other Drivers supported by Kura, it is distributed as a deployment package on the Eclipse Marketplace here and here . It can be installed following the instructions provided here .","title":"Installation"},{"location":"connect-field-devices/sensortag-driver/#instance-creation","text":"A new TiSensorTag Driver instance can be created either by clicking the New Driver button in the dedicated Drivers and Assets Web UI section or by clicking on the + button under Services . In both cases, the org.eclipse.kura.driver.ble.sensortag factory must be selected and a unique name must be provided for the new instance. Once instantiated, the SensorTag Driver has to be configured setting the Bluetooth interface name (i.e. hci0) that will be used to connect to the device.","title":"Instance creation"},{"location":"connect-field-devices/sensortag-driver/#channel-configuration","text":"The SensorTag Driver channel can be configured with the following parameters: enabled : it allows to enable/disable the channel. If it isn't selected the channel will be ignored. name : the channel name. type : the channel type, ( READ , WRITE , or READ_WRITE ). value.type : the Java type of the channel value. The value read by the Driver will be converted to the value.type . Conversely, in write operations the Driver will accept value of this kind. listen : when selected, a listener will be attached to this channel. Any event on the channel will be reported using a callback and the value will be emitted. sensortag.address : the address of the specific SensorTag (i.e. aa:bb:cc:dd:ee:ff) sensor.name : the name of the sensor. It can be selected from a drop-down list notification.period : the period in milliseconds used to receive notification for a specific sensor. The value will be ignored it the listen option is not checked.","title":"Channel configuration"},{"location":"connect-field-devices/xdk-driver/","text":"Xdk Driver Eclipse Kura provides a specific driver that can be used to interact with Bosch Xdk110 devices. The driver is available only for gateways that support the new Bluetooth LE APIs. It can be used in to the Wires framework, the Asset model or directly using the Driver itself. Info The Xdk driver can only be used with Xdk110 with VirtualXdkDemo installed and with firmware version > 3.5.0 . If your device has an older firmware, please update it. Features The Xdk Driver can be used to get the values from all the sensor provider by the xdk110 (both in polling mode and notification): three-axis acceleration (or four-axis quaternion rappresentation) three-axis gyroscope (or four-axis quaternion rappresentation) light noise pressure ambient temperature humidity sd-card detect status push buttons three-axis magnetic field magnetometer resistence led status rms voltage of LEM sensor Resource Unit Description ACCELERATION_X, ACCELERATION_Y, ACCELERATION_Z G The proper acceleration for each axis* GYROSCOPE_X, GYROSCOPE_Y, GYROSCOPE_Z rad/S The angular acceleration for each axis* LIGHT lux The light value NOISE DpSpl The acustic pressure value PRESSURE Pa The pressure value TEMPERATURE C The temperature value HUMIDITY %rH The relative humidity SD_CARD_DETECTION_STATUS boolean SD-Card detect status PUSH_BUTTONS bit Button status, encoded as bit field: Bit 0, Button 1; Bit 1, Button 2 MAGNETOMETER_X, MAGNETOMETER_Y, MAGNETOMETERE_Z uT The magnetometer value for each axis MAGNETOMETER_RESISTENCE ohm The magnetometer resistence value LED_STATUS bit Led status, encoded as a bit field: Bit 0: yellow Led; Bit 1: orange Led; Bit 2: red Led VOLTAGE_LEM mV RMS voltage of LEM sensor *If the Quaternion rappresentation is selected, then: Resource Unit Description QUATERNION_M , QUATERNION_X , QUATERNION_Y , QUATERNION_Z number The rotation-quaternion for each axis When a notification is enabled for a specific channel (sensor), the notification period can't be set. Use the Timer in Wire Graph to set polling. Documentation All the information regarding the Xdk110 is available in the Xdk Bosch Connectivity here website. The XDK-Workbench is the tool that can be used to develop software for the Xdk110. It can be downloaded from here . XDK-Workbench is required to install VirtualXdkDemo. Warning We found connection problems with Xdk, probably due to issues with XDK-Workbench version 3.6.0. We recommend installing version 3.5.0. The Virtual XDK application user guide contains all the information regarding the XDK110 UUIDs and data formats here . Info To switch between quaternion and sensor representation, the XDK110 needs to be instructed using the 55b741d5-7ada-11e4-82f8-0800200c9a66 UUID. Set it to 0x01 to enable Quaternions. If quaternion representation is enabled, the data format is as follows: Bytes Data Type 0,1,2 & 3 Rotation Quaternion M float 4,5,6 & 7 Rotation Quaternion X float 8,9,10 & 11 Rotation Quaternion Y float 12,13,14 & 15 Rotation Quaternion Z float Installation As the others Drivers supported by Kura, it is distributed as a deployment package on the Eclipse Marketplace here . It can be installed following the instructions provided here . Instance creation A new Xdk Driver instance can be created either by clicking the New Driver button in the dedicated Drivers and Assets Web UI section or by clicking on the + button under Services . In both cases, the org.eclipse.kura.driver.ble.xdk factory must be selected and a unique name must be provided for the new instance. Once instantiated, the Xdk Driver has to be configured setting the Bluetooth interface name (i.e. hci0 ). Other options available are related to the quaternion/sensor representation and the sensor sampling rate (in Hz). Channel configuration The Xdk Driver channel can be configured with the following parameters: enabled : it allows to enable/disable the channel. If it isn't selected the channel will be ignored. name : the channel name. type : the channel type, ( READ , WRITE , or READ_WRITE ). Warning The Xdk driver can only be used with READ. value.type : the Java type of the channel value. The value read by the Driver will be converted to the value.type . listen : when selected, a listener will be attached to this channel. Any event on the channel will be reported using a callback and the value will be emitted. xdk.address : the address of the specific xdk (i.e. aa:bb:cc:dd:ee:ff) sensor.name : the name of the sensor. It can be selected from a drop-down list.","title":"Xdk Driver"},{"location":"connect-field-devices/xdk-driver/#xdk-driver","text":"Eclipse Kura provides a specific driver that can be used to interact with Bosch Xdk110 devices. The driver is available only for gateways that support the new Bluetooth LE APIs. It can be used in to the Wires framework, the Asset model or directly using the Driver itself. Info The Xdk driver can only be used with Xdk110 with VirtualXdkDemo installed and with firmware version > 3.5.0 . If your device has an older firmware, please update it.","title":"Xdk Driver"},{"location":"connect-field-devices/xdk-driver/#features","text":"The Xdk Driver can be used to get the values from all the sensor provider by the xdk110 (both in polling mode and notification): three-axis acceleration (or four-axis quaternion rappresentation) three-axis gyroscope (or four-axis quaternion rappresentation) light noise pressure ambient temperature humidity sd-card detect status push buttons three-axis magnetic field magnetometer resistence led status rms voltage of LEM sensor Resource Unit Description ACCELERATION_X, ACCELERATION_Y, ACCELERATION_Z G The proper acceleration for each axis* GYROSCOPE_X, GYROSCOPE_Y, GYROSCOPE_Z rad/S The angular acceleration for each axis* LIGHT lux The light value NOISE DpSpl The acustic pressure value PRESSURE Pa The pressure value TEMPERATURE C The temperature value HUMIDITY %rH The relative humidity SD_CARD_DETECTION_STATUS boolean SD-Card detect status PUSH_BUTTONS bit Button status, encoded as bit field: Bit 0, Button 1; Bit 1, Button 2 MAGNETOMETER_X, MAGNETOMETER_Y, MAGNETOMETERE_Z uT The magnetometer value for each axis MAGNETOMETER_RESISTENCE ohm The magnetometer resistence value LED_STATUS bit Led status, encoded as a bit field: Bit 0: yellow Led; Bit 1: orange Led; Bit 2: red Led VOLTAGE_LEM mV RMS voltage of LEM sensor *If the Quaternion rappresentation is selected, then: Resource Unit Description QUATERNION_M , QUATERNION_X , QUATERNION_Y , QUATERNION_Z number The rotation-quaternion for each axis When a notification is enabled for a specific channel (sensor), the notification period can't be set. Use the Timer in Wire Graph to set polling.","title":"Features"},{"location":"connect-field-devices/xdk-driver/#documentation","text":"All the information regarding the Xdk110 is available in the Xdk Bosch Connectivity here website. The XDK-Workbench is the tool that can be used to develop software for the Xdk110. It can be downloaded from here . XDK-Workbench is required to install VirtualXdkDemo. Warning We found connection problems with Xdk, probably due to issues with XDK-Workbench version 3.6.0. We recommend installing version 3.5.0. The Virtual XDK application user guide contains all the information regarding the XDK110 UUIDs and data formats here . Info To switch between quaternion and sensor representation, the XDK110 needs to be instructed using the 55b741d5-7ada-11e4-82f8-0800200c9a66 UUID. Set it to 0x01 to enable Quaternions. If quaternion representation is enabled, the data format is as follows: Bytes Data Type 0,1,2 & 3 Rotation Quaternion M float 4,5,6 & 7 Rotation Quaternion X float 8,9,10 & 11 Rotation Quaternion Y float 12,13,14 & 15 Rotation Quaternion Z float","title":"Documentation"},{"location":"connect-field-devices/xdk-driver/#installation","text":"As the others Drivers supported by Kura, it is distributed as a deployment package on the Eclipse Marketplace here . It can be installed following the instructions provided here .","title":"Installation"},{"location":"connect-field-devices/xdk-driver/#instance-creation","text":"A new Xdk Driver instance can be created either by clicking the New Driver button in the dedicated Drivers and Assets Web UI section or by clicking on the + button under Services . In both cases, the org.eclipse.kura.driver.ble.xdk factory must be selected and a unique name must be provided for the new instance. Once instantiated, the Xdk Driver has to be configured setting the Bluetooth interface name (i.e. hci0 ). Other options available are related to the quaternion/sensor representation and the sensor sampling rate (in Hz).","title":"Instance creation"},{"location":"connect-field-devices/xdk-driver/#channel-configuration","text":"The Xdk Driver channel can be configured with the following parameters: enabled : it allows to enable/disable the channel. If it isn't selected the channel will be ignored. name : the channel name. type : the channel type, ( READ , WRITE , or READ_WRITE ). Warning The Xdk driver can only be used with READ. value.type : the Java type of the channel value. The value read by the Driver will be converted to the value.type . listen : when selected, a listener will be attached to this channel. Any event on the channel will be reported using a callback and the value will be emitted. xdk.address : the address of the specific xdk (i.e. aa:bb:cc:dd:ee:ff) sensor.name : the name of the sensor. It can be selected from a drop-down list.","title":"Channel configuration"},{"location":"core-services/active-mq-artemis-broker/","text":"ActiveMQ Artemis MQTT Broker Apart from using the simple ActiveMQ-7 MQTT instance available in the Simple Artemis MQTT Broker Service , this service allows to configure, in a more detailed way, the characteristics of the ActiveMQ-7 broker instance running in Kura. This service exposes the following configuration parameters: Enabled - (Required) - Enables the broker instance Broker XML - Broker XML configuration. An empty broker configuration will disable the broker. Required protocols - A comma seperated list of all required protocol factories (e.g. AMQP or MQTT) User configuration - (Required) - User configuration in the format: user=password|role1,role2,... Default user name - The name of the default user Please refer to the official documentation for more details on how to configure the ActiveMQ broker service. Service Usage Example Setting the Broker XML field as follows: false tcp://localhost:61616 tcp://localhost:5672?protocols=AMQP tcp://localhost:1883?protocols=MQTT false the User configuration to: guest=test12|guest while setting the Default user name to: guest will determine that the TCP ports 1883, 5672 and 61616 are now open (you can verify that via netstat -antup ). Configuring the MqttDataTransport in System -> Cloud Services -> MqttDataTransport to use: broker-url - mqtt://localhost:1883 username - guest password - test12 Clicking on the Connect button will result in a successful connection of Kura cloud service to the ActiveMQ-7 MQTT broker. Note The XML configuration above only allows connections originating from the gateway itself. In order to allow external connection the bind URLs specified using the acceptor tag must be modified by specifying an external accessible address instead of localhost . If the bind address is set to 0.0.0.0 , the broker will listen on all available addresses.","title":"ActiveMQ Artemis MQTT Broker"},{"location":"core-services/active-mq-artemis-broker/#activemq-artemis-mqtt-broker","text":"Apart from using the simple ActiveMQ-7 MQTT instance available in the Simple Artemis MQTT Broker Service , this service allows to configure, in a more detailed way, the characteristics of the ActiveMQ-7 broker instance running in Kura. This service exposes the following configuration parameters: Enabled - (Required) - Enables the broker instance Broker XML - Broker XML configuration. An empty broker configuration will disable the broker. Required protocols - A comma seperated list of all required protocol factories (e.g. AMQP or MQTT) User configuration - (Required) - User configuration in the format: user=password|role1,role2,... Default user name - The name of the default user Please refer to the official documentation for more details on how to configure the ActiveMQ broker service.","title":"ActiveMQ Artemis MQTT Broker"},{"location":"core-services/active-mq-artemis-broker/#service-usage-example","text":"Setting the Broker XML field as follows: false tcp://localhost:61616 tcp://localhost:5672?protocols=AMQP tcp://localhost:1883?protocols=MQTT false the User configuration to: guest=test12|guest while setting the Default user name to: guest will determine that the TCP ports 1883, 5672 and 61616 are now open (you can verify that via netstat -antup ). Configuring the MqttDataTransport in System -> Cloud Services -> MqttDataTransport to use: broker-url - mqtt://localhost:1883 username - guest password - test12 Clicking on the Connect button will result in a successful connection of Kura cloud service to the ActiveMQ-7 MQTT broker. Note The XML configuration above only allows connections originating from the gateway itself. In order to allow external connection the bind URLs specified using the acceptor tag must be modified by specifying an external accessible address instead of localhost . If the bind address is set to 0.0.0.0 , the broker will listen on all available addresses.","title":"Service Usage Example"},{"location":"core-services/clock-service/","text":"Clock Service The ClockService handles the date and time management of the system. If enabled, it tries to update the system date and time using a Network Time Protocol (NTP) server. NTP can use NTS as authentication mechanism through chrony. Service Configuration To manage the system date and time, select the ClockService option located in the Services area as shown in the screen capture below. The ClockService provides the following configuration parameters: enabled : sets whether or not this service is enabled or disabled (Required field). clock.set.hwclock : defines if the hardware clock of the gateway must be synced after the system time is set. If enabled, the service calls the Linux command hwclock --utc --systohc . clock.provider : specifies one among Java NTP client (java-ntp), Linux chrony command (chrony-advanced), Linux ntpdate command (ntpd) (Required field). If chrony-advanced is used, Kura will not change system and/or hardware clock directly, delegating these operations to chrony. clock.ntp.host : sets a valid NTP server host address. clock.ntp.port : sets a valid NTP port number (not supported by ntpd, use the port 123 in that case). clock.ntp.timeout : specifies the NTP timeout in milliseconds. clock.ntp.max-retry : defines the number of retries when a sync fails (retry at every minute). Subsequently, the next retry occurs on the next refresh interval. clock.ntp.retry.interval : defines the interval in seconds between each retry when a sync fails. If the clock.ntp.refresh-interval parameter is less than zero, there is no update. If the clock.ntp.refresh-interval parameter is equal to zero, there is only one try at startup (Required field). clock.ntp.refresh-interval : defines the frequency (in seconds) at which the service tries to sync the clock. Note that at the start of Kura, when the ClockService is enabled, it tries to sync the clock every minute until it is successful. After a successful sync, this operation is performed at the frequency defined by this parameter. If the value is less than zero, there is no update. If the value is equal to zero, syncs only once at startup. chrony.advanced.config : specifies the content of the chrony configuration file. If this field is left blank, the default system configuration will be used. All fields above will be ignored. To obtain the hardware clock synchronization the directive rtcsync could be used. The rtcsync directive provides the hardware clock synchronization made by the linux kernel every 11 minutes. For further information reference the chrony website . Two example configuration are shown below. NTS Secure configuration example server time.cloudflare.com iburst nts server nts.sth1.ntp.se iburst nts server nts.sth2.ntp.se iburst nts sourcedir /etc/chrony/sources.d driftfile /var/lib/chrony/chrony.drift logdir /var/log/chrony maxupdateskew 100 .0 rtcsync makestep 1 -1 leapsectz right/UTC Note If the system stays disconnected from the network for a long time or if the backup battery is not working properly or is depleted, there is the possibility of a synchronization failure due to the client inability to verify the server certificates. If this happens and no counter action has been taken in the chrony configuration file, the risk is that the gateway will be unable to synchronise again its date and therefore will not be able to connect to the cloud and/or be fully operational. A possible way to prevent this issue is to temporary disable the certificate verification using the directive nocerttimecheck. This directory will disable the security checks of the activation and expiration times of certificates for the specified number of clock updates and should be used with caution due to the important security implications . As reported by the official Chrony documentation , disabling the time checks has important security implications and should be used only as a last resort, preferably with a minimal number of trusted certificates. The default value is 0, which means the time checks are always enabled. An example of the directive is nocerttimecheck 1 This would disable the time checks until the clock is updated for the first time, assuming the first update corrects the clock and later checks can work with correct time. Simple configuration example # Use public NTP servers from the pool.ntp.org project. pool pool.ntp.org iburst # Record the rate at which the system clock gains/losses time. driftfile /var/lib/chrony/drift # Allow the system clock to be stepped in the first three updates # if its offset is larger than 1 second. makestep 1 -1 # Enable kernel synchronization of the real-time clock (RTC). rtcsync","title":"Clock Service"},{"location":"core-services/clock-service/#clock-service","text":"The ClockService handles the date and time management of the system. If enabled, it tries to update the system date and time using a Network Time Protocol (NTP) server. NTP can use NTS as authentication mechanism through chrony.","title":"Clock Service"},{"location":"core-services/clock-service/#service-configuration","text":"To manage the system date and time, select the ClockService option located in the Services area as shown in the screen capture below. The ClockService provides the following configuration parameters: enabled : sets whether or not this service is enabled or disabled (Required field). clock.set.hwclock : defines if the hardware clock of the gateway must be synced after the system time is set. If enabled, the service calls the Linux command hwclock --utc --systohc . clock.provider : specifies one among Java NTP client (java-ntp), Linux chrony command (chrony-advanced), Linux ntpdate command (ntpd) (Required field). If chrony-advanced is used, Kura will not change system and/or hardware clock directly, delegating these operations to chrony. clock.ntp.host : sets a valid NTP server host address. clock.ntp.port : sets a valid NTP port number (not supported by ntpd, use the port 123 in that case). clock.ntp.timeout : specifies the NTP timeout in milliseconds. clock.ntp.max-retry : defines the number of retries when a sync fails (retry at every minute). Subsequently, the next retry occurs on the next refresh interval. clock.ntp.retry.interval : defines the interval in seconds between each retry when a sync fails. If the clock.ntp.refresh-interval parameter is less than zero, there is no update. If the clock.ntp.refresh-interval parameter is equal to zero, there is only one try at startup (Required field). clock.ntp.refresh-interval : defines the frequency (in seconds) at which the service tries to sync the clock. Note that at the start of Kura, when the ClockService is enabled, it tries to sync the clock every minute until it is successful. After a successful sync, this operation is performed at the frequency defined by this parameter. If the value is less than zero, there is no update. If the value is equal to zero, syncs only once at startup. chrony.advanced.config : specifies the content of the chrony configuration file. If this field is left blank, the default system configuration will be used. All fields above will be ignored. To obtain the hardware clock synchronization the directive rtcsync could be used. The rtcsync directive provides the hardware clock synchronization made by the linux kernel every 11 minutes. For further information reference the chrony website . Two example configuration are shown below.","title":"Service Configuration"},{"location":"core-services/clock-service/#nts-secure-configuration-example","text":"server time.cloudflare.com iburst nts server nts.sth1.ntp.se iburst nts server nts.sth2.ntp.se iburst nts sourcedir /etc/chrony/sources.d driftfile /var/lib/chrony/chrony.drift logdir /var/log/chrony maxupdateskew 100 .0 rtcsync makestep 1 -1 leapsectz right/UTC Note If the system stays disconnected from the network for a long time or if the backup battery is not working properly or is depleted, there is the possibility of a synchronization failure due to the client inability to verify the server certificates. If this happens and no counter action has been taken in the chrony configuration file, the risk is that the gateway will be unable to synchronise again its date and therefore will not be able to connect to the cloud and/or be fully operational. A possible way to prevent this issue is to temporary disable the certificate verification using the directive nocerttimecheck. This directory will disable the security checks of the activation and expiration times of certificates for the specified number of clock updates and should be used with caution due to the important security implications . As reported by the official Chrony documentation , disabling the time checks has important security implications and should be used only as a last resort, preferably with a minimal number of trusted certificates. The default value is 0, which means the time checks are always enabled. An example of the directive is nocerttimecheck 1 This would disable the time checks until the clock is updated for the first time, assuming the first update corrects the clock and later checks can work with correct time.","title":"NTS Secure configuration example"},{"location":"core-services/clock-service/#simple-configuration-example","text":"# Use public NTP servers from the pool.ntp.org project. pool pool.ntp.org iburst # Record the rate at which the system clock gains/losses time. driftfile /var/lib/chrony/drift # Allow the system clock to be stepped in the first three updates # if its offset is larger than 1 second. makestep 1 -1 # Enable kernel synchronization of the real-time clock (RTC). rtcsync","title":"Simple configuration example"},{"location":"core-services/command-service/","text":"Command Service The Command Service provides methods for running system commands from the Kura web console or from Kapua. In the Kura web console, the service is available clicking on the Command tab under the Device section, while for the cloud platform please refer to the official documentation. To run a command simply fill the Execute field with the command and click the Execute button. The service also provides the ability for a script to execute using the File option of the Command tab in the Kura web console or the Kapua Cloud Console. This script must be compressed into a zip file with the eventual, associated resource files. Once the file is selected and Execute is clicked, the zip file is sent embedded in an MQTT message on the device. The Command Service in the device stores the file in /tmp, unzips it, and tries to execute a shell script if one is present in the file. Note that in this case, the Execute parameter cannot be empty; a simple command, such as ls -l /tmp , may be entered. Warning When decompressed, the script loses its executable attribute. To fix this problem, if you plan to execute a script, the command entered into the Execute line must trigger the execution: ** bash [name of the script] **. The configuration of the service is in the CommandService tab located in the Services area as shown in the screen capture below. The Command Service provides the following configuration parameters: Command Enable : sets whether this service is enabled or disabled in the cloud platform (Required field). Command Password Value : sets a password to protect this service. Command Working Directory : specifies the working directory where the command execution is performed. Command Timeout : sets the timeout (in seconds) for the command execution. Command Environment : supplies a space-separated list of environment variables in the format key=value. Privileged/Unprivileged Command Service Selection : sets the modality of the command service. When set to privileged, the commands are run using the (privileged) user that started Kura, tipically kurad or root . When set to unprivileged, a standard user will run the commands. When a command execution is requested in the cloud platform, it sends an MQTT control message to the device requesting that the command be executed. On the device, the Command Service opens a temporary shell in the command.working.directory, sets the command.environment variables (if any), and waits command.timeout seconds to get command response.","title":"Command Service"},{"location":"core-services/command-service/#command-service","text":"The Command Service provides methods for running system commands from the Kura web console or from Kapua. In the Kura web console, the service is available clicking on the Command tab under the Device section, while for the cloud platform please refer to the official documentation. To run a command simply fill the Execute field with the command and click the Execute button. The service also provides the ability for a script to execute using the File option of the Command tab in the Kura web console or the Kapua Cloud Console. This script must be compressed into a zip file with the eventual, associated resource files. Once the file is selected and Execute is clicked, the zip file is sent embedded in an MQTT message on the device. The Command Service in the device stores the file in /tmp, unzips it, and tries to execute a shell script if one is present in the file. Note that in this case, the Execute parameter cannot be empty; a simple command, such as ls -l /tmp , may be entered. Warning When decompressed, the script loses its executable attribute. To fix this problem, if you plan to execute a script, the command entered into the Execute line must trigger the execution: ** bash [name of the script] **. The configuration of the service is in the CommandService tab located in the Services area as shown in the screen capture below. The Command Service provides the following configuration parameters: Command Enable : sets whether this service is enabled or disabled in the cloud platform (Required field). Command Password Value : sets a password to protect this service. Command Working Directory : specifies the working directory where the command execution is performed. Command Timeout : sets the timeout (in seconds) for the command execution. Command Environment : supplies a space-separated list of environment variables in the format key=value. Privileged/Unprivileged Command Service Selection : sets the modality of the command service. When set to privileged, the commands are run using the (privileged) user that started Kura, tipically kurad or root . When set to unprivileged, a standard user will run the commands. When a command execution is requested in the cloud platform, it sends an MQTT control message to the device requesting that the command be executed. On the device, the Command Service opens a temporary shell in the command.working.directory, sets the command.environment variables (if any), and waits command.timeout seconds to get command response.","title":"Command Service"},{"location":"core-services/configuration-service-rest-v1/","text":"Configuration V1 REST APIs This page describes the configuration V1 rest APIs. REST APIs The Configuration Service REST APIs are exposed by the org.eclipse.kura.rest.configuration bundle, providing the following REST APIs under the /configuration/v1 path. Method Path Allowed roles Encoding Request parameters Description GET /factoryComponents configuration JSON None The method lists all the FactoryComponents Pids tracked by the ConfigurationService POST /factoryComponents configuration JSON FactoryComponentConfiguration object Creates a new ConfigurableComponent instance by creating a new configuration from a Configuration Admin factory. The FactoryComponentConfiguration object passed as request parameter will provide all the information needed to generate the instance. It links the factory Pid to be used, the target instance Pid, the properties to be used when creating the instance, and if the request should be persisted with a snapshot DELETE /factoryComponents/{pid}?takeSnapshot={takeSnapshot} configuration JSON pid = A String representing the pid of the instance generated by a Factory Component that needs to deleted; takeSnapshot = an optional (default false) boolean to specify if a new snapshot needs to be created after the delete operation For the specified Pid and optional takeSnapshot query parameter, the ConfigurationService instance will delete the corresponding ConfigurableComponent instance GET /configurableComponents configuration JSON None Lists the tracked configurable component Pids GET /configurableComponents/configurations configuration JSON None Lists all the component configurations of all the ConfigurableComponents tracked by the ConfigurationService GET /configurableComponents/configurations/byFilter/{filter} configuration JSON filter = A String representing an OSGi filter. Lists the component configurations of all the ConfigurableComponents tracked by the ConfigurationService that match the filter specified GET /configurableComponents/configurations/byPid/{pid} configuration JSON pid = A String representing the pid of a configurable component instance Provides the ComponentConfiguration of the ConfigurableComponent matching the specified Pid GET /configurableComponents/configurations/byPid/{pid}/_default configuration JSON pid = A String representing the pid of a configurable component instance Provides the default Component Configuration for the component identified by the specified Pid POST /configurableComponents/configurations/byPid/{pid}/_update configuration JSON pid = A String representing the pid of a configurable component instance; ComponentConfigurationUpdateRequest = the updated configuration provided in the request body Allows to update the component configuration identified by the provided PID POST /configurableComponents/configurations/_update configuration JSON componentConfigurations = the list of updated configurations provided in the request body Allows to update the configuration of multiple configurable components GET /snapshots configuration JSON None Lists all the available snapshot IDs managed by the framework GET /snapshots/{id} configuration JSON id = the snapshot Id Returns the content of a given snapshot tracked by the framework POST /snapshots/_write configuration JSON None Triggers the framework to take and persist a snapshot POST /snapshots/_rollback configuration JSON None Rollbacks the framework to the last saved snapshot if available. POST /snapshots/{id}/_rollback configuration JSON id = the snapshot Id Rollbacks the framework to the snapshot identified by the provided ID POST /snapshots/_upload configuration Consumes: XML Framework snapshot in XML form provided in the request body Uploads a snapshot. The framework will update the component(s) configuration accordingly to the configurations received Get all the factory components pids Request : URL - https:///services/configuration/v1/factoryComponents Response : [ \"org.eclipse.kura.wire.Conditional\" , \"org.eclipse.kura.cloudconnection.raw.mqtt.publisher.RawMqttPublisher\" , \"org.eclipse.kura.misc.cloudcat.CloudCat\" , \"org.eclipse.kura.core.db.H2DbServer\" , \"org.eclipse.kura.wire.Fifo\" , \"org.eclipse.kura.cloudconnection.raw.mqtt.cloud.RawMqttCloudEndpoint\" , \"org.eclipse.kura.core.keystore.FilesystemKeystoreServiceImpl\" , \"org.eclipse.kura.cloud.publisher.CloudPublisher\" , \"org.eclipse.kura.core.db.H2DbService\" , \"org.eclipse.kura.wire.CloudSubscriber\" , \"org.eclipse.kura.wire.RegexFilter\" , \"org.eclipse.kura.wire.Logger\" , \"org.eclipse.kura.wire.Timer\" , \"com.eurotech.framework.log.manager.LogManager\" , \"com.eurotech.framework.log.journald.wire.JournaldWireComponent\" , \"org.eclipse.kura.cloudconnection.raw.mqtt.subscriber.RawMqttSubscriber\" , \"org.eclipse.kura.cloud.subscriber.CloudSubscriber\" , \"org.eclipse.kura.ssl.SslManagerService\" , \"org.eclipse.kura.core.data.transport.mqtt.MqttDataTransport\" , \"com.eurotech.framework.log.journald.JournaldLogReader\" , \"org.eclipse.kura.provisioning.ProvisioningService\" , \"org.eclipse.kura.wire.CloudPublisher\" , \"org.eclipse.kura.wire.H2DbWireRecordFilter\" , \"org.eclipse.kura.cloud.CloudService\" , \"org.eclipse.kura.data.DataService\" , \"org.eclipse.kura.wire.H2DbWireRecordStore\" , \"org.eclipse.kura.wire.Join\" , \"com.eurotech.framework.log.publisher.LogPublisher\" ] Create component from factory Request : URL - https:///services/configuration/v1/factoryComponents Request body : { \"factoryPid\" : \"org.eclipse.kura.core.db.H2DbServer\" , \"pid\" : \"myH2DbServer\" , \"properties\" : [], \"takeSnapshot\" : false } The request must be provided with the following elements: factoryPid : the factory used to generate the new instance pid : the new instance process id properties : eventual properties that will be used to instantiate the new instance and will override the defaults. A list of string, object pair is needed and can be optionally empty. takeSnapshot : specifies if after the creation of a new component a snapshot needs to be taken. Delete a component and optionally take a snapshot Request : URL - https:///services/configuration/v1/factoryComponents/{pid}?takeSnapshot={takeSnapshot} takeSnapshot : can be either true or false. If set to true, after the deletion, the framework will take a snapshot. List the tracked configurable component Pids Request : URL - https:///services/configuration/v1/configurableComponents Response : [ \"org.eclipse.kura.clock.ClockService\" , \"org.eclipse.kura.net.admin.NetworkConfigurationService\" , \"org.eclipse.kura.position.PositionService\" , \"com.eurotech.framework.internal.ansible.provider.AnsibleServiceImpl\" , \"org.eclipse.kura.internal.useradmin.store.RoleRepositoryStoreImpl\" , \"com.eurotech.framework.internal.ansible.cloud.AnsibleActivityHandler\" , \"default.diagnostic.publisher\" , \"org.eclipse.kura.net.admin.FirewallConfigurationService\" , \"com.eurotech.framework.internal.fail2ban.Fail2BanConfigurator\" , \"default.log.publisher\" , \"org.eclipse.kura.wire.graph.WireGraphService\" , \"com.eurotech.framework.internal.floodingprotection.FloodingProtectionConfigurator\" , \"org.eclipse.kura.ssl.SslManagerService\" , \"org.eclipse.kura.http.server.manager.HttpService\" , \"org.eclipse.kura.cloud.app.command.CommandCloudApp\" , \"default.ping.publisher\" , \"org.eclipse.kura.db.H2DbService\" , \"com.eurotech.framework.diagnostics.DiagnosticsService\" , \"org.eclipse.kura.core.data.transport.mqtt.MqttDataTransport\" , \"org.eclipse.kura.deployment.agent\" , \"DMKeystore\" , \"LogReaderJournald\" , \"default.alert.publisher\" , \"org.eclipse.kura.core.deployment.CloudDeploymentHandlerV2\" , \"HttpsKeystore\" , \"com.eurotech.framework.security.aide.AideTamperDetectionServiceConfigurator\" , \"org.eclipse.kura.provisioning.ProvisioningService\" , \"LogManagerAuth\" , \"com.eurotech.framework.security.journald.fss.FssTamperDetectionServiceConfigurator\" , \"org.eclipse.kura.watchdog.WatchdogService\" , \"org.eclipse.kura.cloud.CloudService\" , \"LogManagerActivity\" , \"org.eclipse.kura.data.DataService\" , \"LogManagerDefault\" , \"org.eclipse.kura.web.Console\" , \"SSLKeystore\" , \"com.eurotech.framework.net.vpn.client.VpnClient\" , \"org.eclipse.kura.internal.rest.provider.RestService\" , \"com.eurotech.framework.reboot.RebootService\" ] Lists all the component configurations of all the ConfigurableComponents Request : URL - https:///services/configuration/v1/configurableComponents/configurations Response : [ { \"pid\" : \"org.eclipse.kura.clock.ClockService\" , \"definition\" : { \"ad\" : [ { \"option\" : [], \"name\" : \"enabled\" , \"description\" : \"Whether or not to enable the ClockService\" , \"id\" : \"enabled\" , \"type\" : \"BOOLEAN\" , \"cardinality\" : 0 , \"_default\" : \"true\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.set.hwclock\" , \"description\" : \"Whether or not to sync the system hardware clock after the system time gets set\" , \"id\" : \"clock.set.hwclock\" , \"type\" : \"BOOLEAN\" , \"cardinality\" : 0 , \"_default\" : \"true\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [ { \"label\" : \"java-ntp\" , \"value\" : \"java-ntp\" , \"otherAttributes\" : {} }, { \"label\" : \"ntpd\" , \"value\" : \"ntpd\" , \"otherAttributes\" : {} }, { \"label\" : \"chrony-advanced\" , \"value\" : \"chrony-advanced\" , \"otherAttributes\" : {} } ], \"name\" : \"clock.provider\" , \"description\" : \"Source for setting the system clock. Verify the availabiliy of the selected provider before activate it.\" , \"id\" : \"clock.provider\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"java-ntp\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.host\" , \"description\" : \"The hostname that provides the system time via NTP\" , \"id\" : \"clock.ntp.host\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"0.pool.ntp.org\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.port\" , \"description\" : \"The port number that provides the system time via NTP\" , \"id\" : \"clock.ntp.port\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1\" , \"max\" : \"65535\" , \"_default\" : \"123\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.timeout\" , \"description\" : \"The NTP timeout in milliseconds\" , \"id\" : \"clock.ntp.timeout\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1000\" , \"_default\" : \"10000\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.max-retry\" , \"description\" : \"The maximum number of retries for the initial synchronization (with interval clock.ntp.retry.interval). If set to 0 the service will retry forever.\" , \"id\" : \"clock.ntp.max-retry\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"0\" , \"_default\" : \"0\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.retry.interval\" , \"description\" : \"When sync fails, interval in seconds between each retry.\" , \"id\" : \"clock.ntp.retry.interval\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1\" , \"_default\" : \"5\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.refresh-interval\" , \"description\" : \"Whether or not to sync the clock and if so, the frequency in seconds. If less than zero - no update, if equal to zero - sync once at startup, if greater than zero - the frequency in seconds to perform a new clock sync\" , \"id\" : \"clock.ntp.refresh-interval\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"_default\" : \"3600\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"RTC File Name\" , \"description\" : \"The RTC File Name. It defaults to /dev/rtc0. This option is not used if chrony-advanced option is selected in clock.provider.\" , \"id\" : \"rtc.filename\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"/dev/rtc0\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"Chrony Configuration\" , \"description\" : \"Chrony configuration file.|TextArea\" , \"id\" : \"chrony.advanced.config\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"required\" : false , \"otherAttributes\" : {} } ], \"icon\" : [ { \"resource\" : \"ClockService\" , \"size\" : 32 , \"otherAttributes\" : {} } ], \"name\" : \"ClockService\" , \"description\" : \"ClockService Configuration\" , \"id\" : \"org.eclipse.kura.clock.ClockService\" , \"otherAttributes\" : {} }, \"properties\" : { \"clock.ntp.host\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"0.pool.ntp.org\" }, \"clock.ntp.max-retry\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 0 }, \"clock.set.hwclock\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : true }, \"clock.ntp.timeout\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 10000 }, \"enabled\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : false }, \"clock.ntp.retry.interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 5 }, \"kura.service.pid\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" }, \"service.pid\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" }, \"clock.ntp.port\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 123 }, \"clock.provider\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"java-ntp\" }, \"clock.ntp.refresh-interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 3600 }, \"rtc.filename\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"/dev/rtc1\" }, \"chrony.advanced.config\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"\" } } }, ... ] List the configurations of all the ConfigurableComponents that match a filter Request : URL - https:///services/configuration/v1/configurableComponents/configurations/byFilter/(service.pid=org.eclipse.kura.clock.ClockService) Response : [ { \"pid\" : \"org.eclipse.kura.clock.ClockService\" , \"definition\" : { \"ad\" : [ { \"option\" : [], \"name\" : \"enabled\" , \"description\" : \"Whether or not to enable the ClockService\" , \"id\" : \"enabled\" , \"type\" : \"BOOLEAN\" , \"cardinality\" : 0 , \"_default\" : \"true\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.set.hwclock\" , \"description\" : \"Whether or not to sync the system hardware clock after the system time gets set\" , \"id\" : \"clock.set.hwclock\" , \"type\" : \"BOOLEAN\" , \"cardinality\" : 0 , \"_default\" : \"true\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [ { \"label\" : \"java-ntp\" , \"value\" : \"java-ntp\" , \"otherAttributes\" : {} }, { \"label\" : \"ntpd\" , \"value\" : \"ntpd\" , \"otherAttributes\" : {} }, { \"label\" : \"chrony-advanced\" , \"value\" : \"chrony-advanced\" , \"otherAttributes\" : {} } ], \"name\" : \"clock.provider\" , \"description\" : \"Source for setting the system clock. Verify the availabiliy of the selected provider before activate it.\" , \"id\" : \"clock.provider\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"java-ntp\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.host\" , \"description\" : \"The hostname that provides the system time via NTP\" , \"id\" : \"clock.ntp.host\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"0.pool.ntp.org\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.port\" , \"description\" : \"The port number that provides the system time via NTP\" , \"id\" : \"clock.ntp.port\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1\" , \"max\" : \"65535\" , \"_default\" : \"123\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.timeout\" , \"description\" : \"The NTP timeout in milliseconds\" , \"id\" : \"clock.ntp.timeout\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1000\" , \"_default\" : \"10000\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.max-retry\" , \"description\" : \"The maximum number of retries for the initial synchronization (with interval clock.ntp.retry.interval). If set to 0 the service will retry forever.\" , \"id\" : \"clock.ntp.max-retry\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"0\" , \"_default\" : \"0\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.retry.interval\" , \"description\" : \"When sync fails, interval in seconds between each retry.\" , \"id\" : \"clock.ntp.retry.interval\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1\" , \"_default\" : \"5\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.refresh-interval\" , \"description\" : \"Whether or not to sync the clock and if so, the frequency in seconds. If less than zero - no update, if equal to zero - sync once at startup, if greater than zero - the frequency in seconds to perform a new clock sync\" , \"id\" : \"clock.ntp.refresh-interval\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"_default\" : \"3600\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"RTC File Name\" , \"description\" : \"The RTC File Name. It defaults to /dev/rtc0. This option is not used if chrony-advanced option is selected in clock.provider.\" , \"id\" : \"rtc.filename\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"/dev/rtc0\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"Chrony Configuration\" , \"description\" : \"Chrony configuration file.|TextArea\" , \"id\" : \"chrony.advanced.config\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"required\" : false , \"otherAttributes\" : {} } ], \"icon\" : [ { \"resource\" : \"ClockService\" , \"size\" : 32 , \"otherAttributes\" : {} } ], \"name\" : \"ClockService\" , \"description\" : \"ClockService Configuration\" , \"id\" : \"org.eclipse.kura.clock.ClockService\" , \"otherAttributes\" : {} }, \"properties\" : { \"clock.ntp.host\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"0.pool.ntp.org\" }, \"clock.ntp.max-retry\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 0 }, \"clock.set.hwclock\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : true }, \"clock.ntp.timeout\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 10000 }, \"enabled\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : false }, \"clock.ntp.retry.interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 5 }, \"kura.service.pid\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" }, \"service.pid\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" }, \"clock.ntp.port\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 123 }, \"clock.provider\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"java-ntp\" }, \"clock.ntp.refresh-interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 3600 }, \"rtc.filename\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"/dev/rtc1\" }, \"chrony.advanced.config\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"\" } } } ] Get the configuration of the ConfigurableComponent matching a pid Request : URL - https:///services/configuration/v1/configurableComponents/configurations/byPid/org.eclipse.kura.clock.ClockService Response : { \"pid\" : \"org.eclipse.kura.clock.ClockService\" , \"definition\" : { \"ad\" : [ { \"option\" : [], \"name\" : \"enabled\" , \"description\" : \"Whether or not to enable the ClockService\" , \"id\" : \"enabled\" , \"type\" : \"BOOLEAN\" , \"cardinality\" : 0 , \"_default\" : \"true\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.set.hwclock\" , \"description\" : \"Whether or not to sync the system hardware clock after the system time gets set\" , \"id\" : \"clock.set.hwclock\" , \"type\" : \"BOOLEAN\" , \"cardinality\" : 0 , \"_default\" : \"true\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [ { \"label\" : \"java-ntp\" , \"value\" : \"java-ntp\" , \"otherAttributes\" : {} }, { \"label\" : \"ntpd\" , \"value\" : \"ntpd\" , \"otherAttributes\" : {} }, { \"label\" : \"chrony-advanced\" , \"value\" : \"chrony-advanced\" , \"otherAttributes\" : {} } ], \"name\" : \"clock.provider\" , \"description\" : \"Source for setting the system clock. Verify the availabiliy of the selected provider before activate it.\" , \"id\" : \"clock.provider\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"java-ntp\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.host\" , \"description\" : \"The hostname that provides the system time via NTP\" , \"id\" : \"clock.ntp.host\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"0.pool.ntp.org\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.port\" , \"description\" : \"The port number that provides the system time via NTP\" , \"id\" : \"clock.ntp.port\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1\" , \"max\" : \"65535\" , \"_default\" : \"123\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.timeout\" , \"description\" : \"The NTP timeout in milliseconds\" , \"id\" : \"clock.ntp.timeout\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1000\" , \"_default\" : \"10000\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.max-retry\" , \"description\" : \"The maximum number of retries for the initial synchronization (with interval clock.ntp.retry.interval). If set to 0 the service will retry forever.\" , \"id\" : \"clock.ntp.max-retry\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"0\" , \"_default\" : \"0\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.retry.interval\" , \"description\" : \"When sync fails, interval in seconds between each retry.\" , \"id\" : \"clock.ntp.retry.interval\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1\" , \"_default\" : \"5\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.refresh-interval\" , \"description\" : \"Whether or not to sync the clock and if so, the frequency in seconds. If less than zero - no update, if equal to zero - sync once at startup, if greater than zero - the frequency in seconds to perform a new clock sync\" , \"id\" : \"clock.ntp.refresh-interval\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"_default\" : \"3600\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"RTC File Name\" , \"description\" : \"The RTC File Name. It defaults to /dev/rtc0. This option is not used if chrony-advanced option is selected in clock.provider.\" , \"id\" : \"rtc.filename\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"/dev/rtc0\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"Chrony Configuration\" , \"description\" : \"Chrony configuration file.|TextArea\" , \"id\" : \"chrony.advanced.config\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"required\" : false , \"otherAttributes\" : {} } ], \"icon\" : [ { \"resource\" : \"ClockService\" , \"size\" : 32 , \"otherAttributes\" : {} } ], \"name\" : \"ClockService\" , \"description\" : \"ClockService Configuration\" , \"id\" : \"org.eclipse.kura.clock.ClockService\" , \"otherAttributes\" : {} }, \"properties\" : { \"clock.ntp.host\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"0.pool.ntp.org\" }, \"clock.ntp.max-retry\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 0 }, \"clock.set.hwclock\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : true }, \"clock.ntp.timeout\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 10000 }, \"enabled\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : false }, \"clock.ntp.retry.interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 5 }, \"kura.service.pid\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" }, \"service.pid\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" }, \"clock.ntp.port\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 123 }, \"clock.provider\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"java-ntp\" }, \"clock.ntp.refresh-interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 3600 }, \"rtc.filename\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"/dev/rtc1\" }, \"chrony.advanced.config\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"\" } } } Get the default configuration of the ConfigurableComponent matching a pid Request : URL - https:///services/configuration/v1/configurableComponents/configurations/byPid/org.eclipse.kura.clock.ClockService/_default Response : { \"pid\" : \"org.eclipse.kura.clock.ClockService\" , \"definition\" : { \"ad\" : [ { \"option\" : [], \"name\" : \"enabled\" , \"description\" : \"Whether or not to enable the ClockService\" , \"id\" : \"enabled\" , \"type\" : \"BOOLEAN\" , \"cardinality\" : 0 , \"_default\" : \"true\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.set.hwclock\" , \"description\" : \"Whether or not to sync the system hardware clock after the system time gets set\" , \"id\" : \"clock.set.hwclock\" , \"type\" : \"BOOLEAN\" , \"cardinality\" : 0 , \"_default\" : \"true\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [ { \"label\" : \"java-ntp\" , \"value\" : \"java-ntp\" , \"otherAttributes\" : {} }, { \"label\" : \"ntpd\" , \"value\" : \"ntpd\" , \"otherAttributes\" : {} }, { \"label\" : \"chrony-advanced\" , \"value\" : \"chrony-advanced\" , \"otherAttributes\" : {} } ], \"name\" : \"clock.provider\" , \"description\" : \"Source for setting the system clock. Verify the availabiliy of the selected provider before activate it.\" , \"id\" : \"clock.provider\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"java-ntp\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.host\" , \"description\" : \"The hostname that provides the system time via NTP\" , \"id\" : \"clock.ntp.host\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"0.pool.ntp.org\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.port\" , \"description\" : \"The port number that provides the system time via NTP\" , \"id\" : \"clock.ntp.port\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1\" , \"max\" : \"65535\" , \"_default\" : \"123\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.timeout\" , \"description\" : \"The NTP timeout in milliseconds\" , \"id\" : \"clock.ntp.timeout\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1000\" , \"_default\" : \"10000\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.max-retry\" , \"description\" : \"The maximum number of retries for the initial synchronization (with interval clock.ntp.retry.interval). If set to 0 the service will retry forever.\" , \"id\" : \"clock.ntp.max-retry\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"0\" , \"_default\" : \"0\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.retry.interval\" , \"description\" : \"When sync fails, interval in seconds between each retry.\" , \"id\" : \"clock.ntp.retry.interval\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1\" , \"_default\" : \"5\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.refresh-interval\" , \"description\" : \"Whether or not to sync the clock and if so, the frequency in seconds. If less than zero - no update, if equal to zero - sync once at startup, if greater than zero - the frequency in seconds to perform a new clock sync\" , \"id\" : \"clock.ntp.refresh-interval\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"_default\" : \"3600\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"RTC File Name\" , \"description\" : \"The RTC File Name. It defaults to /dev/rtc0. This option is not used if chrony-advanced option is selected in clock.provider.\" , \"id\" : \"rtc.filename\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"/dev/rtc0\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"Chrony Configuration\" , \"description\" : \"Chrony configuration file.|TextArea\" , \"id\" : \"chrony.advanced.config\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"required\" : false , \"otherAttributes\" : {} } ], \"icon\" : [ { \"resource\" : \"ClockService\" , \"size\" : 32 , \"otherAttributes\" : {} } ], \"name\" : \"ClockService\" , \"description\" : \"ClockService Configuration\" , \"id\" : \"org.eclipse.kura.clock.ClockService\" , \"otherAttributes\" : {} }, \"properties\" : { \"clock.ntp.host\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"0.pool.ntp.org\" }, \"clock.provider\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"java-ntp\" }, \"clock.ntp.port\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 123 }, \"clock.ntp.max-retry\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 0 }, \"clock.ntp.refresh-interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 3600 }, \"rtc.filename\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"/dev/rtc0\" }, \"clock.set.hwclock\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : true }, \"enabled\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : true }, \"clock.ntp.timeout\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 10000 }, \"clock.ntp.retry.interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 5 } } } Update the component configuration identified matching a pid Request : URL - https:///services/configuration/v1/configurableComponents/configurations/byPid/org.eclipse.kura.clock.ClockService/_update Request body : { \"takeSnapshot\" : true , \"componentConfigurationRequest\" : { \"properties\" : { \"enabled\" : { \"type\" : \"boolean\" , \"value\" : false , \"array\" : false } } } } Warning Every service may need a different set of parameters and combination of them to reach the desired result. For the NetworkAdminService , for example, the following configuration is required to disable a specific network interface (enp2s0) and prevent re-enabling at reboot. Please verify offline the REST APIs executed and the different deploying scenarios before distributing updates to the fleet of devices. { \"takeSnapshot\" : true , \"componentConfigurationRequest\" : { \"properties\" : { \"net.interface.enp2s0.config.ip4.status\" : { \"type\" : \"string\" , \"value\" : \"netIPv4StatusDisabled\" , \"array\" : false }, \"net.interface.enp2s0.config.autoconnect\" : { \"type\" : \"boolean\" , \"value\" : false , \"array\" : false } } } } Update the configuration of multiple configurable components Request : URL - https:///services/configuration/v1/configurableComponents/configurations/_update Request body : { \"takeSnapshot\" : true , \"componentConfigurations\" : [ { \"pid\" : \"org.eclipse.kura.clock.ClockService\" , \"properties\" : { \"enabled\" : { \"type\" : \"boolean\" , \"value\" : false , \"array\" : false } } } ] } List all the available snapshot IDs Request : URL - https:///services/configuration/v1/snapshots Response : [ 0 , 1630930775789 , 1630930776355 , 1630930776839 , 1630930797402 , 1630930805305 ] Get the content of a given snapshot Request : URL - https:///services/configuration/v1/snapshots/{id} Response : [ { \"pid\" : \"org.eclipse.kura.clock.ClockService\" , \"properties\" : { \"clock.ntp.host\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"0.pool.ntp.org\" }, \"clock.ntp.port\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 123 }, \"clock.provider\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"java-ntp\" }, \"clock.ntp.max-retry\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 0 }, \"clock.ntp.refresh-interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 3600 }, \"rtc.filename\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"/dev/rtc1\" }, \"clock.set.hwclock\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : true }, \"clock.ntp.timeout\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 10000 }, \"enabled\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : true }, \"clock.ntp.retry.interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 5 }, \"kura.service.pid\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" }, \"service.pid\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" } } }, ... ] Trigger the framework to take and persist a snapshot Request : URL - https:///services/configuration/v1/snapshots/_write Response : 1631095409516 Rollbacks to the snapshot identified by the provided ID Request : URL - https:///services/configuration/v1/snapshots/_rollback Response : 1631093011618 Upload a snapshot as XML Request : URL - https:///services/configuration/v1/snapshots/_upload Request body : 0.pool.ntp.org 123 java-ntp 0 3600 /dev/rtc1 true 10000 true 5 org.eclipse.kura.clock.ClockService org.eclipse.kura.clock.ClockService ","title":"Configuration V1 REST APIs"},{"location":"core-services/configuration-service-rest-v1/#configuration-v1-rest-apis","text":"This page describes the configuration V1 rest APIs.","title":"Configuration V1 REST APIs"},{"location":"core-services/configuration-service-rest-v1/#rest-apis","text":"The Configuration Service REST APIs are exposed by the org.eclipse.kura.rest.configuration bundle, providing the following REST APIs under the /configuration/v1 path. Method Path Allowed roles Encoding Request parameters Description GET /factoryComponents configuration JSON None The method lists all the FactoryComponents Pids tracked by the ConfigurationService POST /factoryComponents configuration JSON FactoryComponentConfiguration object Creates a new ConfigurableComponent instance by creating a new configuration from a Configuration Admin factory. The FactoryComponentConfiguration object passed as request parameter will provide all the information needed to generate the instance. It links the factory Pid to be used, the target instance Pid, the properties to be used when creating the instance, and if the request should be persisted with a snapshot DELETE /factoryComponents/{pid}?takeSnapshot={takeSnapshot} configuration JSON pid = A String representing the pid of the instance generated by a Factory Component that needs to deleted; takeSnapshot = an optional (default false) boolean to specify if a new snapshot needs to be created after the delete operation For the specified Pid and optional takeSnapshot query parameter, the ConfigurationService instance will delete the corresponding ConfigurableComponent instance GET /configurableComponents configuration JSON None Lists the tracked configurable component Pids GET /configurableComponents/configurations configuration JSON None Lists all the component configurations of all the ConfigurableComponents tracked by the ConfigurationService GET /configurableComponents/configurations/byFilter/{filter} configuration JSON filter = A String representing an OSGi filter. Lists the component configurations of all the ConfigurableComponents tracked by the ConfigurationService that match the filter specified GET /configurableComponents/configurations/byPid/{pid} configuration JSON pid = A String representing the pid of a configurable component instance Provides the ComponentConfiguration of the ConfigurableComponent matching the specified Pid GET /configurableComponents/configurations/byPid/{pid}/_default configuration JSON pid = A String representing the pid of a configurable component instance Provides the default Component Configuration for the component identified by the specified Pid POST /configurableComponents/configurations/byPid/{pid}/_update configuration JSON pid = A String representing the pid of a configurable component instance; ComponentConfigurationUpdateRequest = the updated configuration provided in the request body Allows to update the component configuration identified by the provided PID POST /configurableComponents/configurations/_update configuration JSON componentConfigurations = the list of updated configurations provided in the request body Allows to update the configuration of multiple configurable components GET /snapshots configuration JSON None Lists all the available snapshot IDs managed by the framework GET /snapshots/{id} configuration JSON id = the snapshot Id Returns the content of a given snapshot tracked by the framework POST /snapshots/_write configuration JSON None Triggers the framework to take and persist a snapshot POST /snapshots/_rollback configuration JSON None Rollbacks the framework to the last saved snapshot if available. POST /snapshots/{id}/_rollback configuration JSON id = the snapshot Id Rollbacks the framework to the snapshot identified by the provided ID POST /snapshots/_upload configuration Consumes: XML Framework snapshot in XML form provided in the request body Uploads a snapshot. The framework will update the component(s) configuration accordingly to the configurations received","title":"REST APIs"},{"location":"core-services/configuration-service-rest-v1/#get-all-the-factory-components-pids","text":"Request : URL - https:///services/configuration/v1/factoryComponents Response : [ \"org.eclipse.kura.wire.Conditional\" , \"org.eclipse.kura.cloudconnection.raw.mqtt.publisher.RawMqttPublisher\" , \"org.eclipse.kura.misc.cloudcat.CloudCat\" , \"org.eclipse.kura.core.db.H2DbServer\" , \"org.eclipse.kura.wire.Fifo\" , \"org.eclipse.kura.cloudconnection.raw.mqtt.cloud.RawMqttCloudEndpoint\" , \"org.eclipse.kura.core.keystore.FilesystemKeystoreServiceImpl\" , \"org.eclipse.kura.cloud.publisher.CloudPublisher\" , \"org.eclipse.kura.core.db.H2DbService\" , \"org.eclipse.kura.wire.CloudSubscriber\" , \"org.eclipse.kura.wire.RegexFilter\" , \"org.eclipse.kura.wire.Logger\" , \"org.eclipse.kura.wire.Timer\" , \"com.eurotech.framework.log.manager.LogManager\" , \"com.eurotech.framework.log.journald.wire.JournaldWireComponent\" , \"org.eclipse.kura.cloudconnection.raw.mqtt.subscriber.RawMqttSubscriber\" , \"org.eclipse.kura.cloud.subscriber.CloudSubscriber\" , \"org.eclipse.kura.ssl.SslManagerService\" , \"org.eclipse.kura.core.data.transport.mqtt.MqttDataTransport\" , \"com.eurotech.framework.log.journald.JournaldLogReader\" , \"org.eclipse.kura.provisioning.ProvisioningService\" , \"org.eclipse.kura.wire.CloudPublisher\" , \"org.eclipse.kura.wire.H2DbWireRecordFilter\" , \"org.eclipse.kura.cloud.CloudService\" , \"org.eclipse.kura.data.DataService\" , \"org.eclipse.kura.wire.H2DbWireRecordStore\" , \"org.eclipse.kura.wire.Join\" , \"com.eurotech.framework.log.publisher.LogPublisher\" ]","title":"Get all the factory components pids"},{"location":"core-services/configuration-service-rest-v1/#create-component-from-factory","text":"Request : URL - https:///services/configuration/v1/factoryComponents Request body : { \"factoryPid\" : \"org.eclipse.kura.core.db.H2DbServer\" , \"pid\" : \"myH2DbServer\" , \"properties\" : [], \"takeSnapshot\" : false } The request must be provided with the following elements: factoryPid : the factory used to generate the new instance pid : the new instance process id properties : eventual properties that will be used to instantiate the new instance and will override the defaults. A list of string, object pair is needed and can be optionally empty. takeSnapshot : specifies if after the creation of a new component a snapshot needs to be taken.","title":"Create component from factory"},{"location":"core-services/configuration-service-rest-v1/#delete-a-component-and-optionally-take-a-snapshot","text":"Request : URL - https:///services/configuration/v1/factoryComponents/{pid}?takeSnapshot={takeSnapshot} takeSnapshot : can be either true or false. If set to true, after the deletion, the framework will take a snapshot.","title":"Delete a component and optionally take a snapshot"},{"location":"core-services/configuration-service-rest-v1/#list-the-tracked-configurable-component-pids","text":"Request : URL - https:///services/configuration/v1/configurableComponents Response : [ \"org.eclipse.kura.clock.ClockService\" , \"org.eclipse.kura.net.admin.NetworkConfigurationService\" , \"org.eclipse.kura.position.PositionService\" , \"com.eurotech.framework.internal.ansible.provider.AnsibleServiceImpl\" , \"org.eclipse.kura.internal.useradmin.store.RoleRepositoryStoreImpl\" , \"com.eurotech.framework.internal.ansible.cloud.AnsibleActivityHandler\" , \"default.diagnostic.publisher\" , \"org.eclipse.kura.net.admin.FirewallConfigurationService\" , \"com.eurotech.framework.internal.fail2ban.Fail2BanConfigurator\" , \"default.log.publisher\" , \"org.eclipse.kura.wire.graph.WireGraphService\" , \"com.eurotech.framework.internal.floodingprotection.FloodingProtectionConfigurator\" , \"org.eclipse.kura.ssl.SslManagerService\" , \"org.eclipse.kura.http.server.manager.HttpService\" , \"org.eclipse.kura.cloud.app.command.CommandCloudApp\" , \"default.ping.publisher\" , \"org.eclipse.kura.db.H2DbService\" , \"com.eurotech.framework.diagnostics.DiagnosticsService\" , \"org.eclipse.kura.core.data.transport.mqtt.MqttDataTransport\" , \"org.eclipse.kura.deployment.agent\" , \"DMKeystore\" , \"LogReaderJournald\" , \"default.alert.publisher\" , \"org.eclipse.kura.core.deployment.CloudDeploymentHandlerV2\" , \"HttpsKeystore\" , \"com.eurotech.framework.security.aide.AideTamperDetectionServiceConfigurator\" , \"org.eclipse.kura.provisioning.ProvisioningService\" , \"LogManagerAuth\" , \"com.eurotech.framework.security.journald.fss.FssTamperDetectionServiceConfigurator\" , \"org.eclipse.kura.watchdog.WatchdogService\" , \"org.eclipse.kura.cloud.CloudService\" , \"LogManagerActivity\" , \"org.eclipse.kura.data.DataService\" , \"LogManagerDefault\" , \"org.eclipse.kura.web.Console\" , \"SSLKeystore\" , \"com.eurotech.framework.net.vpn.client.VpnClient\" , \"org.eclipse.kura.internal.rest.provider.RestService\" , \"com.eurotech.framework.reboot.RebootService\" ]","title":"List the tracked configurable component Pids"},{"location":"core-services/configuration-service-rest-v1/#lists-all-the-component-configurations-of-all-the-configurablecomponents","text":"Request : URL - https:///services/configuration/v1/configurableComponents/configurations Response : [ { \"pid\" : \"org.eclipse.kura.clock.ClockService\" , \"definition\" : { \"ad\" : [ { \"option\" : [], \"name\" : \"enabled\" , \"description\" : \"Whether or not to enable the ClockService\" , \"id\" : \"enabled\" , \"type\" : \"BOOLEAN\" , \"cardinality\" : 0 , \"_default\" : \"true\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.set.hwclock\" , \"description\" : \"Whether or not to sync the system hardware clock after the system time gets set\" , \"id\" : \"clock.set.hwclock\" , \"type\" : \"BOOLEAN\" , \"cardinality\" : 0 , \"_default\" : \"true\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [ { \"label\" : \"java-ntp\" , \"value\" : \"java-ntp\" , \"otherAttributes\" : {} }, { \"label\" : \"ntpd\" , \"value\" : \"ntpd\" , \"otherAttributes\" : {} }, { \"label\" : \"chrony-advanced\" , \"value\" : \"chrony-advanced\" , \"otherAttributes\" : {} } ], \"name\" : \"clock.provider\" , \"description\" : \"Source for setting the system clock. Verify the availabiliy of the selected provider before activate it.\" , \"id\" : \"clock.provider\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"java-ntp\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.host\" , \"description\" : \"The hostname that provides the system time via NTP\" , \"id\" : \"clock.ntp.host\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"0.pool.ntp.org\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.port\" , \"description\" : \"The port number that provides the system time via NTP\" , \"id\" : \"clock.ntp.port\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1\" , \"max\" : \"65535\" , \"_default\" : \"123\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.timeout\" , \"description\" : \"The NTP timeout in milliseconds\" , \"id\" : \"clock.ntp.timeout\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1000\" , \"_default\" : \"10000\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.max-retry\" , \"description\" : \"The maximum number of retries for the initial synchronization (with interval clock.ntp.retry.interval). If set to 0 the service will retry forever.\" , \"id\" : \"clock.ntp.max-retry\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"0\" , \"_default\" : \"0\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.retry.interval\" , \"description\" : \"When sync fails, interval in seconds between each retry.\" , \"id\" : \"clock.ntp.retry.interval\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1\" , \"_default\" : \"5\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.refresh-interval\" , \"description\" : \"Whether or not to sync the clock and if so, the frequency in seconds. If less than zero - no update, if equal to zero - sync once at startup, if greater than zero - the frequency in seconds to perform a new clock sync\" , \"id\" : \"clock.ntp.refresh-interval\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"_default\" : \"3600\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"RTC File Name\" , \"description\" : \"The RTC File Name. It defaults to /dev/rtc0. This option is not used if chrony-advanced option is selected in clock.provider.\" , \"id\" : \"rtc.filename\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"/dev/rtc0\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"Chrony Configuration\" , \"description\" : \"Chrony configuration file.|TextArea\" , \"id\" : \"chrony.advanced.config\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"required\" : false , \"otherAttributes\" : {} } ], \"icon\" : [ { \"resource\" : \"ClockService\" , \"size\" : 32 , \"otherAttributes\" : {} } ], \"name\" : \"ClockService\" , \"description\" : \"ClockService Configuration\" , \"id\" : \"org.eclipse.kura.clock.ClockService\" , \"otherAttributes\" : {} }, \"properties\" : { \"clock.ntp.host\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"0.pool.ntp.org\" }, \"clock.ntp.max-retry\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 0 }, \"clock.set.hwclock\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : true }, \"clock.ntp.timeout\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 10000 }, \"enabled\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : false }, \"clock.ntp.retry.interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 5 }, \"kura.service.pid\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" }, \"service.pid\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" }, \"clock.ntp.port\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 123 }, \"clock.provider\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"java-ntp\" }, \"clock.ntp.refresh-interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 3600 }, \"rtc.filename\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"/dev/rtc1\" }, \"chrony.advanced.config\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"\" } } }, ... ]","title":"Lists all the component configurations of all the ConfigurableComponents"},{"location":"core-services/configuration-service-rest-v1/#list-the-configurations-of-all-the-configurablecomponents-that-match-a-filter","text":"Request : URL - https:///services/configuration/v1/configurableComponents/configurations/byFilter/(service.pid=org.eclipse.kura.clock.ClockService) Response : [ { \"pid\" : \"org.eclipse.kura.clock.ClockService\" , \"definition\" : { \"ad\" : [ { \"option\" : [], \"name\" : \"enabled\" , \"description\" : \"Whether or not to enable the ClockService\" , \"id\" : \"enabled\" , \"type\" : \"BOOLEAN\" , \"cardinality\" : 0 , \"_default\" : \"true\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.set.hwclock\" , \"description\" : \"Whether or not to sync the system hardware clock after the system time gets set\" , \"id\" : \"clock.set.hwclock\" , \"type\" : \"BOOLEAN\" , \"cardinality\" : 0 , \"_default\" : \"true\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [ { \"label\" : \"java-ntp\" , \"value\" : \"java-ntp\" , \"otherAttributes\" : {} }, { \"label\" : \"ntpd\" , \"value\" : \"ntpd\" , \"otherAttributes\" : {} }, { \"label\" : \"chrony-advanced\" , \"value\" : \"chrony-advanced\" , \"otherAttributes\" : {} } ], \"name\" : \"clock.provider\" , \"description\" : \"Source for setting the system clock. Verify the availabiliy of the selected provider before activate it.\" , \"id\" : \"clock.provider\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"java-ntp\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.host\" , \"description\" : \"The hostname that provides the system time via NTP\" , \"id\" : \"clock.ntp.host\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"0.pool.ntp.org\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.port\" , \"description\" : \"The port number that provides the system time via NTP\" , \"id\" : \"clock.ntp.port\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1\" , \"max\" : \"65535\" , \"_default\" : \"123\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.timeout\" , \"description\" : \"The NTP timeout in milliseconds\" , \"id\" : \"clock.ntp.timeout\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1000\" , \"_default\" : \"10000\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.max-retry\" , \"description\" : \"The maximum number of retries for the initial synchronization (with interval clock.ntp.retry.interval). If set to 0 the service will retry forever.\" , \"id\" : \"clock.ntp.max-retry\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"0\" , \"_default\" : \"0\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.retry.interval\" , \"description\" : \"When sync fails, interval in seconds between each retry.\" , \"id\" : \"clock.ntp.retry.interval\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1\" , \"_default\" : \"5\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.refresh-interval\" , \"description\" : \"Whether or not to sync the clock and if so, the frequency in seconds. If less than zero - no update, if equal to zero - sync once at startup, if greater than zero - the frequency in seconds to perform a new clock sync\" , \"id\" : \"clock.ntp.refresh-interval\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"_default\" : \"3600\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"RTC File Name\" , \"description\" : \"The RTC File Name. It defaults to /dev/rtc0. This option is not used if chrony-advanced option is selected in clock.provider.\" , \"id\" : \"rtc.filename\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"/dev/rtc0\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"Chrony Configuration\" , \"description\" : \"Chrony configuration file.|TextArea\" , \"id\" : \"chrony.advanced.config\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"required\" : false , \"otherAttributes\" : {} } ], \"icon\" : [ { \"resource\" : \"ClockService\" , \"size\" : 32 , \"otherAttributes\" : {} } ], \"name\" : \"ClockService\" , \"description\" : \"ClockService Configuration\" , \"id\" : \"org.eclipse.kura.clock.ClockService\" , \"otherAttributes\" : {} }, \"properties\" : { \"clock.ntp.host\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"0.pool.ntp.org\" }, \"clock.ntp.max-retry\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 0 }, \"clock.set.hwclock\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : true }, \"clock.ntp.timeout\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 10000 }, \"enabled\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : false }, \"clock.ntp.retry.interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 5 }, \"kura.service.pid\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" }, \"service.pid\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" }, \"clock.ntp.port\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 123 }, \"clock.provider\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"java-ntp\" }, \"clock.ntp.refresh-interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 3600 }, \"rtc.filename\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"/dev/rtc1\" }, \"chrony.advanced.config\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"\" } } } ]","title":"List the configurations of all the ConfigurableComponents that match a filter"},{"location":"core-services/configuration-service-rest-v1/#get-the-configuration-of-the-configurablecomponent-matching-a-pid","text":"Request : URL - https:///services/configuration/v1/configurableComponents/configurations/byPid/org.eclipse.kura.clock.ClockService Response : { \"pid\" : \"org.eclipse.kura.clock.ClockService\" , \"definition\" : { \"ad\" : [ { \"option\" : [], \"name\" : \"enabled\" , \"description\" : \"Whether or not to enable the ClockService\" , \"id\" : \"enabled\" , \"type\" : \"BOOLEAN\" , \"cardinality\" : 0 , \"_default\" : \"true\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.set.hwclock\" , \"description\" : \"Whether or not to sync the system hardware clock after the system time gets set\" , \"id\" : \"clock.set.hwclock\" , \"type\" : \"BOOLEAN\" , \"cardinality\" : 0 , \"_default\" : \"true\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [ { \"label\" : \"java-ntp\" , \"value\" : \"java-ntp\" , \"otherAttributes\" : {} }, { \"label\" : \"ntpd\" , \"value\" : \"ntpd\" , \"otherAttributes\" : {} }, { \"label\" : \"chrony-advanced\" , \"value\" : \"chrony-advanced\" , \"otherAttributes\" : {} } ], \"name\" : \"clock.provider\" , \"description\" : \"Source for setting the system clock. Verify the availabiliy of the selected provider before activate it.\" , \"id\" : \"clock.provider\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"java-ntp\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.host\" , \"description\" : \"The hostname that provides the system time via NTP\" , \"id\" : \"clock.ntp.host\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"0.pool.ntp.org\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.port\" , \"description\" : \"The port number that provides the system time via NTP\" , \"id\" : \"clock.ntp.port\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1\" , \"max\" : \"65535\" , \"_default\" : \"123\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.timeout\" , \"description\" : \"The NTP timeout in milliseconds\" , \"id\" : \"clock.ntp.timeout\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1000\" , \"_default\" : \"10000\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.max-retry\" , \"description\" : \"The maximum number of retries for the initial synchronization (with interval clock.ntp.retry.interval). If set to 0 the service will retry forever.\" , \"id\" : \"clock.ntp.max-retry\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"0\" , \"_default\" : \"0\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.retry.interval\" , \"description\" : \"When sync fails, interval in seconds between each retry.\" , \"id\" : \"clock.ntp.retry.interval\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1\" , \"_default\" : \"5\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.refresh-interval\" , \"description\" : \"Whether or not to sync the clock and if so, the frequency in seconds. If less than zero - no update, if equal to zero - sync once at startup, if greater than zero - the frequency in seconds to perform a new clock sync\" , \"id\" : \"clock.ntp.refresh-interval\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"_default\" : \"3600\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"RTC File Name\" , \"description\" : \"The RTC File Name. It defaults to /dev/rtc0. This option is not used if chrony-advanced option is selected in clock.provider.\" , \"id\" : \"rtc.filename\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"/dev/rtc0\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"Chrony Configuration\" , \"description\" : \"Chrony configuration file.|TextArea\" , \"id\" : \"chrony.advanced.config\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"required\" : false , \"otherAttributes\" : {} } ], \"icon\" : [ { \"resource\" : \"ClockService\" , \"size\" : 32 , \"otherAttributes\" : {} } ], \"name\" : \"ClockService\" , \"description\" : \"ClockService Configuration\" , \"id\" : \"org.eclipse.kura.clock.ClockService\" , \"otherAttributes\" : {} }, \"properties\" : { \"clock.ntp.host\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"0.pool.ntp.org\" }, \"clock.ntp.max-retry\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 0 }, \"clock.set.hwclock\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : true }, \"clock.ntp.timeout\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 10000 }, \"enabled\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : false }, \"clock.ntp.retry.interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 5 }, \"kura.service.pid\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" }, \"service.pid\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" }, \"clock.ntp.port\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 123 }, \"clock.provider\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"java-ntp\" }, \"clock.ntp.refresh-interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 3600 }, \"rtc.filename\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"/dev/rtc1\" }, \"chrony.advanced.config\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"\" } } }","title":"Get the configuration of the ConfigurableComponent matching a pid"},{"location":"core-services/configuration-service-rest-v1/#get-the-default-configuration-of-the-configurablecomponent-matching-a-pid","text":"Request : URL - https:///services/configuration/v1/configurableComponents/configurations/byPid/org.eclipse.kura.clock.ClockService/_default Response : { \"pid\" : \"org.eclipse.kura.clock.ClockService\" , \"definition\" : { \"ad\" : [ { \"option\" : [], \"name\" : \"enabled\" , \"description\" : \"Whether or not to enable the ClockService\" , \"id\" : \"enabled\" , \"type\" : \"BOOLEAN\" , \"cardinality\" : 0 , \"_default\" : \"true\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.set.hwclock\" , \"description\" : \"Whether or not to sync the system hardware clock after the system time gets set\" , \"id\" : \"clock.set.hwclock\" , \"type\" : \"BOOLEAN\" , \"cardinality\" : 0 , \"_default\" : \"true\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [ { \"label\" : \"java-ntp\" , \"value\" : \"java-ntp\" , \"otherAttributes\" : {} }, { \"label\" : \"ntpd\" , \"value\" : \"ntpd\" , \"otherAttributes\" : {} }, { \"label\" : \"chrony-advanced\" , \"value\" : \"chrony-advanced\" , \"otherAttributes\" : {} } ], \"name\" : \"clock.provider\" , \"description\" : \"Source for setting the system clock. Verify the availabiliy of the selected provider before activate it.\" , \"id\" : \"clock.provider\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"java-ntp\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.host\" , \"description\" : \"The hostname that provides the system time via NTP\" , \"id\" : \"clock.ntp.host\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"0.pool.ntp.org\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.port\" , \"description\" : \"The port number that provides the system time via NTP\" , \"id\" : \"clock.ntp.port\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1\" , \"max\" : \"65535\" , \"_default\" : \"123\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.timeout\" , \"description\" : \"The NTP timeout in milliseconds\" , \"id\" : \"clock.ntp.timeout\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1000\" , \"_default\" : \"10000\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.max-retry\" , \"description\" : \"The maximum number of retries for the initial synchronization (with interval clock.ntp.retry.interval). If set to 0 the service will retry forever.\" , \"id\" : \"clock.ntp.max-retry\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"0\" , \"_default\" : \"0\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.retry.interval\" , \"description\" : \"When sync fails, interval in seconds between each retry.\" , \"id\" : \"clock.ntp.retry.interval\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"min\" : \"1\" , \"_default\" : \"5\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"clock.ntp.refresh-interval\" , \"description\" : \"Whether or not to sync the clock and if so, the frequency in seconds. If less than zero - no update, if equal to zero - sync once at startup, if greater than zero - the frequency in seconds to perform a new clock sync\" , \"id\" : \"clock.ntp.refresh-interval\" , \"type\" : \"INTEGER\" , \"cardinality\" : 0 , \"_default\" : \"3600\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"RTC File Name\" , \"description\" : \"The RTC File Name. It defaults to /dev/rtc0. This option is not used if chrony-advanced option is selected in clock.provider.\" , \"id\" : \"rtc.filename\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"_default\" : \"/dev/rtc0\" , \"required\" : true , \"otherAttributes\" : {} }, { \"option\" : [], \"name\" : \"Chrony Configuration\" , \"description\" : \"Chrony configuration file.|TextArea\" , \"id\" : \"chrony.advanced.config\" , \"type\" : \"STRING\" , \"cardinality\" : 0 , \"required\" : false , \"otherAttributes\" : {} } ], \"icon\" : [ { \"resource\" : \"ClockService\" , \"size\" : 32 , \"otherAttributes\" : {} } ], \"name\" : \"ClockService\" , \"description\" : \"ClockService Configuration\" , \"id\" : \"org.eclipse.kura.clock.ClockService\" , \"otherAttributes\" : {} }, \"properties\" : { \"clock.ntp.host\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"0.pool.ntp.org\" }, \"clock.provider\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"java-ntp\" }, \"clock.ntp.port\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 123 }, \"clock.ntp.max-retry\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 0 }, \"clock.ntp.refresh-interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 3600 }, \"rtc.filename\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"/dev/rtc0\" }, \"clock.set.hwclock\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : true }, \"enabled\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : true }, \"clock.ntp.timeout\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 10000 }, \"clock.ntp.retry.interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 5 } } }","title":"Get the default configuration of the ConfigurableComponent matching a pid"},{"location":"core-services/configuration-service-rest-v1/#update-the-component-configuration-identified-matching-a-pid","text":"Request : URL - https:///services/configuration/v1/configurableComponents/configurations/byPid/org.eclipse.kura.clock.ClockService/_update Request body : { \"takeSnapshot\" : true , \"componentConfigurationRequest\" : { \"properties\" : { \"enabled\" : { \"type\" : \"boolean\" , \"value\" : false , \"array\" : false } } } } Warning Every service may need a different set of parameters and combination of them to reach the desired result. For the NetworkAdminService , for example, the following configuration is required to disable a specific network interface (enp2s0) and prevent re-enabling at reboot. Please verify offline the REST APIs executed and the different deploying scenarios before distributing updates to the fleet of devices. { \"takeSnapshot\" : true , \"componentConfigurationRequest\" : { \"properties\" : { \"net.interface.enp2s0.config.ip4.status\" : { \"type\" : \"string\" , \"value\" : \"netIPv4StatusDisabled\" , \"array\" : false }, \"net.interface.enp2s0.config.autoconnect\" : { \"type\" : \"boolean\" , \"value\" : false , \"array\" : false } } } }","title":"Update the component configuration identified matching a pid"},{"location":"core-services/configuration-service-rest-v1/#update-the-configuration-of-multiple-configurable-components","text":"Request : URL - https:///services/configuration/v1/configurableComponents/configurations/_update Request body : { \"takeSnapshot\" : true , \"componentConfigurations\" : [ { \"pid\" : \"org.eclipse.kura.clock.ClockService\" , \"properties\" : { \"enabled\" : { \"type\" : \"boolean\" , \"value\" : false , \"array\" : false } } } ] }","title":"Update the configuration of multiple configurable components"},{"location":"core-services/configuration-service-rest-v1/#list-all-the-available-snapshot-ids","text":"Request : URL - https:///services/configuration/v1/snapshots Response : [ 0 , 1630930775789 , 1630930776355 , 1630930776839 , 1630930797402 , 1630930805305 ]","title":"List all the available snapshot IDs"},{"location":"core-services/configuration-service-rest-v1/#get-the-content-of-a-given-snapshot","text":"Request : URL - https:///services/configuration/v1/snapshots/{id} Response : [ { \"pid\" : \"org.eclipse.kura.clock.ClockService\" , \"properties\" : { \"clock.ntp.host\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"0.pool.ntp.org\" }, \"clock.ntp.port\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 123 }, \"clock.provider\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"java-ntp\" }, \"clock.ntp.max-retry\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 0 }, \"clock.ntp.refresh-interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 3600 }, \"rtc.filename\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"/dev/rtc1\" }, \"clock.set.hwclock\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : true }, \"clock.ntp.timeout\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 10000 }, \"enabled\" : { \"array\" : false , \"type\" : \"Boolean\" , \"value\" : true }, \"clock.ntp.retry.interval\" : { \"array\" : false , \"type\" : \"Integer\" , \"value\" : 5 }, \"kura.service.pid\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" }, \"service.pid\" : { \"array\" : false , \"type\" : \"String\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" } } }, ... ]","title":"Get the content of a given snapshot"},{"location":"core-services/configuration-service-rest-v1/#trigger-the-framework-to-take-and-persist-a-snapshot","text":"Request : URL - https:///services/configuration/v1/snapshots/_write Response : 1631095409516","title":"Trigger the framework to take and persist a snapshot"},{"location":"core-services/configuration-service-rest-v1/#rollbacks-to-the-snapshot-identified-by-the-provided-id","text":"Request : URL - https:///services/configuration/v1/snapshots/_rollback Response : 1631093011618","title":"Rollbacks to the snapshot identified by the provided ID"},{"location":"core-services/configuration-service-rest-v1/#upload-a-snapshot-as-xml","text":"Request : URL - https:///services/configuration/v1/snapshots/_upload Request body : 0.pool.ntp.org 123 java-ntp 0 3600 /dev/rtc1 true 10000 true 5 org.eclipse.kura.clock.ClockService org.eclipse.kura.clock.ClockService ","title":"Upload a snapshot as XML"},{"location":"core-services/configuration-service-rest-v2/","text":"Configuration V2 REST APIs and CONF-V2 Request Handler This page describes the CONF-V2 request handler and configuration/v2 rest APIs. Accessing the REST APIs requires to use an identity with the rest.configuration permission assigned. Request definitions GET/snapshots GET/factoryComponents POST/factoryComponents DEL/factoryComponents/byPid GET/factoryComponents/ocd POST/factoryComponents/ocd/byFactoryPid GET/configurableComponents GET/configurableComponents/pidsWithFactory GET/configurableComponents/configurations POST/configurableComponents/configurations/byPid POST/configurableComponents/configurations/byPid/_default PUT/configurableComponents/configurations/_update EXEC/snapshots/_write EXEC/snapshots/_rollback EXEC/snapshots/byId/_rollback JSON definitions PidAndFactoryPidSet SnapshotIdSet PropertyType ConfigurationProperty ConfigurationProperties Option AttributeDefinition ObjectClassDefinition ComponentConfiguration ComponentConfigurationList CreateFactoryComponentConfigurationsRequest UpdateComponentConfigurationRequest DeleteFactoryComponentConfigurationsRequest PidSet SnaphsotId GenericFailureReport BatchFailureReport Request definitions GET/snapshots REST API path : /services/configuration/v2/snapshots description : Returns the ids of the snapshots currently stored on the device. responses : 200 description : The snapshot id set. response body : SnapshotIdSet 500 description : An unexpected internal error occurred. response body : GenericFailureReport GET/factoryComponents REST API path : /services/configuration/v2/factoryComponents description : Returns the ids of the component factories available on the device. responses : 200 description : The factory pid set. response body : PidSet 500 description : An unexpected internal error occurred. response body : GenericFailureReport POST/factoryComponents REST API path : /services/configuration/v2/factoryComponents description : This is a batch request that allows to create one or more factory component instances and optionally create a new snapshot. request body : CreateFactoryComponentConfigurationsRequest responses : 200 description : The request succeeded. 400 description : The request body is not valid JSON or it contains invalid parameters. response body : GenericFailureReport 500 description : In case of processing errors, the device will attempt to return a detailed error response containing a message describing the failure reason for each operation. The operation ids are the following: create:$pid for component creation operations, where $pid is the pid of the instance, and snapshot , for the snapshot creation operation. In case of an unexpected failure, a generic error response will be returned. response body : Variants : object GenericFailureReport object BatchFailureReport DEL/factoryComponents/byPid REST API path : /services/configuration/v2/factoryComponents/byPid description : This is a batch request that allows to delete one or more factory component instances and optionally create a new snapshot. request body : DeleteFactoryComponentConfigurationsRequest responses : 200 description : The request succeeded. 400 description : The request body is not valid JSON or it contains invalid parameters. response body : GenericFailureReport 500 description : In case of processing errors, the device will attempt to return a detailed error response containing a message describing the failure reason for each operation. The operation ids are the following: delete:$pid for component delete operations, where $pid is the pid of the instance, and snapshot , for the snapshot creation operation. In case of an unexpected failure, a generic error response will be returned. response body : Variants : object GenericFailureReport object BatchFailureReport GET/factoryComponents/ocd REST API path : /services/configuration/v2/factoryComponents/ocd description : Returns the OCD of the components created by the factories available on the device without the need of creating an instance. This request returns the information related to all available factories. responses : 200 description : The request succeeded. The pid property of the received configurations will report the factory pid, the ocd field will contain the definition, the properties field will not be present. response body : ComponentConfigurationList 500 description : An unexpected internal error occurred. response body : GenericFailureReport POST/factoryComponents/ocd/byFactoryPid REST API path : /services/configuration/v2/factoryComponents/ocd/byFactoryPid description : Returns the OCD of the components created by the factories available on the device without the need of creating an instance. This request returns the information related to a user selected set of factories. request body : PidSet responses : 200 description : The request succeeded. The pid property of the received configurations will report the factory pid, the ocd field will contain the definition, the properties field will not be present. If the OCD for a given factory pid cannot be found, it will not be included in the result. response body : ComponentConfigurationList 400 description : The request body is not valid JSON or it contains invalid parameters. response body : GenericFailureReport 500 description : An unexpected internal error occurred. response body : GenericFailureReport GET/configurableComponents REST API path : /services/configuration/v2/configurableComponents description : Returns the list of the pids available on the system. responses : 200 description : The request succeeded. response body : PidSet 500 description : An unexpected internal error occurred. response body : GenericFailureReport GET/configurableComponents/pidsWithFactory REST API path : /services/configuration/v2/configurableComponents/pidsWithFactory description : Returns the list of the pids available on the system, reporting also the factory pid where applicable. responses : 200 description : The request succeeded. response body : PidAndFactoryPidSet 500 description : An unexpected internal error occurred. response body : GenericFailureReport GET/configurableComponents/configurations REST API path : /services/configuration/v2/configurableComponents/configurations description : Returns all of component configurations available on the system. This request will return the pid , ocd and properties . responses : 200 description : The request succeeded. response body : ComponentConfigurationList 500 description : An unexpected internal error occurred. response body : GenericFailureReport POST/configurableComponents/configurations/byPid REST API path : /services/configuration/v2/configurableComponents/configurations/byPid description : Returns a user selected set of configurations. This request will return the pid , ocd and properties . request body : PidSet responses : 200 description : The request succeeded. If the configuration for a given pid cannot be found, it will not be included in the result. response body : ComponentConfigurationList 400 description : The request body is not valid JSON or it contains invalid parameters. response body : GenericFailureReport 500 description : An unexpected internal error occurred. response body : GenericFailureReport POST/configurableComponents/configurations/byPid/_default REST API path : /services/configuration/v2/configurableComponents/configurations/byPid/_default description : Returns the default configuration for a given set of component pids. The default configurations are generated basing on component definition only, user applied modifications will not be taken into account. This request will return the pid , ocd and properties . request body : PidSet responses : 200 description : The request succeeded. If the configuration for a given pid cannot be found, it will not be included in the result. response body : ComponentConfigurationList 400 description : The request body is not valid JSON or it contains invalid parameters. response body : GenericFailureReport 500 description : An unexpected internal error occurred. response body : GenericFailureReport PUT/configurableComponents/configurations/_update REST API path : /services/configuration/v2/configurableComponents/configurations/_update description : Updates a given set of component configurations. This request can be also used to apply a configuration snapshot. request body : UpdateComponentConfigurationRequest responses : 200 description : The request succeeded. 400 description : The request body is not valid JSON or it contains invalid parameters. response body : GenericFailureReport 500 description : In case of processing errors, the device will attempt to return a detailed error response containing a message describing the failure reason for each operation. The operation ids are the following: update:$pid for component update operations, where $pid is the pid of the instance, and snapshot , for the snapshot creation operation. In case of an unexpected failure, a generic error response will be returned. response body : Variants : object GenericFailureReport object BatchFailureReport EXEC/snapshots/_write REST API path : /services/configuration/v2/snapshots/_write description : Requests the device to create a new snasphot based on the current defice configuration. If this request is used through REST API, the POST method must be used. responses : 200 description : The request succeeded. The result is the identifier of the new snsapsot response body : SnaphsotId 500 description : An unexpected internal error occurred. response body : GenericFailureReport EXEC/snapshots/_rollback REST API path : /services/configuration/v2/snapshots/_rollback description : Rollbacks the framework to the last saved snapshot if available. If this request is used through REST API, the POST method must be used. responses : 200 description : The request succeeded. The result contains the id of the snapshot used for rollback. response body : SnaphsotId 500 description : An unexpected internal error occurred. response body : GenericFailureReport EXEC/snapshots/byId/_rollback REST API path : /services/configuration/v2/snapshots/byId/_rollback description : Performs a rollback to the snapshot id specified by the user. responses : 200 description : The request succeeded. 400 description : The request body is not valid JSON or it contains invalid parameters. response body : GenericFailureReport 500 description : An unexpected internal error occurred. response body : GenericFailureReport JSON definitions PidAndFactoryPidSet Represents a set of pids with the corresponding factory pid. Properties : components : array The set of pids and factory pids array elements: object The pid and factory pid Properties : pid : string The component pid. factoryPid : string optional Can be missing if the described component is not a factory instance. The factory pid { \"components\" : [ { \"factoryPid\" : \"org.eclipse.kura.core.db.H2DbService\" , \"pid\" : \"org.eclipse.kura.db.H2DbService\" }, { \"factoryPid\" : \"org.eclipse.kura.core.data.transport.mqtt.MqttDataTransport\" , \"pid\" : \"org.eclipse.kura.core.data.transport.mqtt.MqttDataTransport\" }, { \"pid\" : \"org.eclipse.kura.web.Console\" } ] } SnapshotIdSet An object decribing a set of configuration snapshot ids Properties : ids : array The set of snapshot ids. array elements: number A snapshot id. { \"ids\" : [ 0 , 1638438049921 , 1638438146960 , 1638439710944 , 1638439717931 , 1638439734077 , 1638439767252 , 1638521986953 , 1638521993692 , 1638522572822 ] } PropertyType A string that describes the type of a configuration property. * Possible values * STRING * LONG * DOUBLE * FLOAT * INTEGER * BYTE * CHAR * BOOLEAN * SHORT * PASSWORD \"STRING\" ConfigurationProperty An object describing a configuration property. Properties : type : string (enumerated) PropertyType value : variant optional In requests, this field can be omitted or set to null to assign the null value to a non required configuration property. Describes the property value. The value type depends on the type property. Variants : number If type is LONG , DOUBLE , FLOAT , INTEGER , BYTE or SHORT and the property does not represent an array. string If type is STRING , PASSWORD or CHAR and the property is not an array. In case of CHAR type, the value must have a length of 1. bool If type is BOOLEAN and the property is not an array array If type is LONG , DOUBLE , FLOAT , INTEGER , BYTE or SHORT and the property represents an array. array elements: number The property values as numbers. array If type is STRING , PASSWORD or CHAR and the property is an array. array elements: string The property values as strings. In case of CHAR type, the values must have a length of 1. array If type is BOOLEAN and the property is an array array elements: bool The property values as booleans. { \"type\" : \"STRING\" , \"value\" : \"foo\" } { \"type\" : \"STRING\" , \"value\" : [ \"foo\" , \"bar\" ] } { \"type\" : \"INTEGER\" , \"value\" : 12 } { \"type\" : \"LONG\" , \"value\" : [ 1 , 2 , 3 , 4 ] } { \"type\" : \"PASSWORD\" , \"value\" : \"myPassword\" } { \"type\" : \"PASSWORD\" , \"value\" : [ \"my\" , \"password\" , \"array\" ] } ConfigurationProperties An object representing a set of configuration properties. The members of this object represent configuration property, the member names represent the configuration property ids. This object can have a variable number of members. Properties : propertyName : object ConfigurationProperty { \"KeystoreService.target\" : { \"type\" : \"STRING\" , \"value\" : \"(kura.service.pid=HttpsKeystore)\" }, \"https.client.auth.ports\" : { \"type\" : \"INTEGER\" , \"value\" : [ 4443 ] }, \"https.client.revocation.soft.fail\" : { \"type\" : \"BOOLEAN\" , \"value\" : false }, \"https.ports\" : { \"type\" : \"INTEGER\" , \"value\" : [ 443 ] }, \"https.revocation.check.enabled\" : { \"type\" : \"BOOLEAN\" , \"value\" : false }, \"kura.service.pid\" : { \"type\" : \"STRING\" , \"value\" : \"org.eclipse.kura.http.server.manager.HttpService\" }, \"service.pid\" : { \"type\" : \"STRING\" , \"value\" : \"org.eclipse.kura.http.server.manager.HttpService\" }, \"ssl.revocation.mode\" : { \"type\" : \"STRING\" , \"value\" : \"PREFER_OCSP\" } } Option An object describing an allowed element for a multi choiche field. Properties : label : string optional This parameter may not be specified by component configuration. An user friendly label for the option. value : string The option value encoded as a string. { \"label\" : \"Value 1\" , \"value\" : \"1\" } { \"value\" : \"foo\" } AttributeDefinition A descriptor of a configuration property. Properties : id : string The id of the attribute definition. This field corresponds to the configuration property name. type : string (enumerated) PropertyType name : string optional This parameter may not be specified by component configuration. An user friendly name for the property. description : string optional This parameter may not be specified by component configuration. An user friendly description for the property. cardinality : number An integer describing the property cardinality. If the value is 0, then the property is a singleton value (not an array), if it is > 0, then the configuration property is an array and this property specifies the maximum allowed array length. min : string optional This parameter may not be specified by component configuration. If not specified, the property does not have a minimum value. Specifies the minimum value for this property as a string. max : string optional This parameter may not be specified by component configuration. If not specified, the property does not have a maximum value. Specifies the maximum value for this property as a string. isRequired : bool Specifies whether the configuration parameter is required or not. defaultValue : string optional This parameter may not be specified by component configuration. Specifies the default value for this property as a string. option : array optional If specified, describes a set of allowed values for the configuration property. The allowed values for this configuration properties array elements: object Option { \"defaultValue\" : \"false\" , \"description\" : \"Specifies whether the DB server is enabled or not.\" , \"id\" : \"db.server.enabled\" , \"isRequired\" : true , \"name\" : \"db.server.enabled\" , \"type\" : \"BOOLEAN\" } { \"defaultValue\" : \"TCP\" , \"description\" : \"Specifies the server type, see http://www.h2database.com/javadoc/org/h2/tools/Server.html for more details.\" , \"id\" : \"db.server.type\" , \"isRequired\" : true , \"name\" : \"db.server.type\" , \"option\" : [ { \"label\" : \"WEB\" , \"value\" : \"WEB\" }, { \"label\" : \"TCP\" , \"value\" : \"TCP\" }, { \"label\" : \"PG\" , \"value\" : \"PG\" } ], \"type\" : \"STRING\" } ObjectClassDefinition Provides some metadata information about a component configuration. Properties : ad : array The metadata about the configuration properties. array elements: object AttributeDefinition icon : array optional Can be missing if the OCD does not define icons. A list of icons that visually represent the configuration. array elements: object Properties : resource : string An identifier of the icon image resource. size : number The icon width and height in pixels. name : string A user friendly name for the component configuration. description : string A user friendly description of the component configuration. id : string An identifier of the component configuration. { \"ad\" : [ { \"defaultValue\" : \"false\" , \"description\" : \"The WatchdogService monitors CriticalComponents and reboots the system if one of them hangs. Once enabled the WatchdogService starts refreshing the watchdog device, which will reset the system if WatchdogService hangs.\" , \"id\" : \"enabled\" , \"isRequired\" : true , \"name\" : \"Watchdog enable\" , \"type\" : \"BOOLEAN\" }, { \"defaultValue\" : \"10000\" , \"description\" : \"WatchdogService's refresh interval in ms of the Watchdog device. The value can be set between 1 and 60 seconds and should not be set to a value greater or equal to the Watchdog device's timeout value\" , \"id\" : \"pingInterval\" , \"isRequired\" : true , \"max\" : \"60000\" , \"name\" : \"Watchdog refresh interval\" , \"type\" : \"INTEGER\" }, { \"defaultValue\" : \"/dev/watchdog\" , \"description\" : \"Watchdog device path e.g. /dev/watchdog.\" , \"id\" : \"watchdogDevice\" , \"isRequired\" : true , \"name\" : \"Watchdog device path\" , \"type\" : \"STRING\" }, { \"defaultValue\" : \"/opt/eclipse/kura/data/kura-reboot-cause\" , \"description\" : \"The path for the file that will contain the reboot cause information.\" , \"id\" : \"rebootCauseFilePath\" , \"isRequired\" : true , \"name\" : \"Reboot Cause File Path\" , \"type\" : \"STRING\" } ], \"description\" : \"The WatchdogService handles the hardware watchdog of the platform. The parameter define the ping periodicity of the hardware watchdog to ensure it does not reboot. The WatchdogService will reset the watchdog timeout, can disable it (where supported) with the Magic Character, but cannot set the refresh rate of a watchdog device.\" , \"icon\" : [ { \"resource\" : \"WatchdogService\" , \"size\" : 32 } ], \"id\" : \"org.eclipse.kura.watchdog.WatchdogService\" , \"name\" : \"WatchdogService\" } ComponentConfiguration Describes a component configuration. Properties : pid : string The identifier of this configuration. ocd : object optional Can be omitted in some requests and responses, see request documentation for more information. ObjectClassDefinition properties : object optional Can be omitted in some requests and responses, see request documentation for more information. ConfigurationProperties { \"definition\" : { \"ad\" : [ { \"cardinality\" : 3 , \"description\" : \"If set to a non empty list, REST API access will be allowed only on the specified ports. If set to an empty list, access will be allowed on all ports. Please make sure that the allowed ports are open in HttpService and Firewall configuration.\" , \"id\" : \"allowed.ports\" , \"isRequired\" : false , \"max\" : \"65535\" , \"min\" : \"1\" , \"name\" : \"Allowed ports\" , \"type\" : \"INTEGER\" } ], \"description\" : \"This service allows to configure settings related to Kura REST APIs\" , \"id\" : \"org.eclipse.kura.internal.rest.provider.RestService\" , \"name\" : \"RestService\" }, \"pid\" : \"org.eclipse.kura.internal.rest.provider.RestService\" , \"properties\" : { \"kura.service.pid\" : { \"type\" : \"STRING\" , \"value\" : \"org.eclipse.kura.internal.rest.provider.RestService\" }, \"service.pid\" : { \"type\" : \"STRING\" , \"value\" : \"org.eclipse.kura.internal.rest.provider.RestService\" } } } ComponentConfigurationList Represents a list of component configurations. Properties : configs : array The component configurations array elements: object ComponentConfiguration { \"configs\" : [ { \"definition\" : { \"ad\" : [ { \"defaultValue\" : \"true\" , \"description\" : \"Whether or not to enable the ClockService\" , \"id\" : \"enabled\" , \"isRequired\" : true , \"name\" : \"enabled\" , \"type\" : \"BOOLEAN\" }, { \"defaultValue\" : \"true\" , \"description\" : \"Whether or not to sync the system hardware clock after the system time gets set\" , \"id\" : \"clock.set.hwclock\" , \"isRequired\" : true , \"name\" : \"clock.set.hwclock\" , \"type\" : \"BOOLEAN\" }, { \"defaultValue\" : \"java-ntp\" , \"description\" : \"Source for setting the system clock. Verify the availabiliy of the selected provider before activate it.\" , \"id\" : \"clock.provider\" , \"isRequired\" : true , \"name\" : \"clock.provider\" , \"option\" : [ { \"label\" : \"java-ntp\" , \"value\" : \"java-ntp\" }, { \"label\" : \"ntpd\" , \"value\" : \"ntpd\" }, { \"label\" : \"chrony-advanced\" , \"value\" : \"chrony-advanced\" } ], \"type\" : \"STRING\" }, { \"defaultValue\" : \"0.pool.ntp.org\" , \"description\" : \"The hostname that provides the system time via NTP\" , \"id\" : \"clock.ntp.host\" , \"isRequired\" : true , \"name\" : \"clock.ntp.host\" , \"type\" : \"STRING\" }, { \"defaultValue\" : \"123\" , \"description\" : \"The port number that provides the system time via NTP\" , \"id\" : \"clock.ntp.port\" , \"isRequired\" : true , \"max\" : \"65535\" , \"min\" : \"1\" , \"name\" : \"clock.ntp.port\" , \"type\" : \"INTEGER\" }, { \"defaultValue\" : \"10000\" , \"description\" : \"The NTP timeout in milliseconds\" , \"id\" : \"clock.ntp.timeout\" , \"isRequired\" : true , \"min\" : \"1000\" , \"name\" : \"clock.ntp.timeout\" , \"type\" : \"INTEGER\" }, { \"defaultValue\" : \"0\" , \"description\" : \"The maximum number of retries for the initial synchronization (with interval clock.ntp.retry.interval). If set to 0 the service will retry forever.\" , \"id\" : \"clock.ntp.max-retry\" , \"isRequired\" : true , \"min\" : \"0\" , \"name\" : \"clock.ntp.max-retry\" , \"type\" : \"INTEGER\" }, { \"defaultValue\" : \"5\" , \"description\" : \"When sync fails, interval in seconds between each retry.\" , \"id\" : \"clock.ntp.retry.interval\" , \"isRequired\" : true , \"min\" : \"1\" , \"name\" : \"clock.ntp.retry.interval\" , \"type\" : \"INTEGER\" }, { \"defaultValue\" : \"3600\" , \"description\" : \"Whether or not to sync the clock and if so, the frequency in seconds. If less than zero - no update, if equal to zero - sync once at startup, if greater than zero - the frequency in seconds to perform a new clock sync\" , \"id\" : \"clock.ntp.refresh-interval\" , \"isRequired\" : true , \"name\" : \"clock.ntp.refresh-interval\" , \"type\" : \"INTEGER\" }, { \"defaultValue\" : \"/dev/rtc0\" , \"description\" : \"The RTC File Name. It defaults to /dev/rtc0. This option is not used if chrony-advanced option is selected in clock.provider.\" , \"id\" : \"rtc.filename\" , \"isRequired\" : true , \"name\" : \"RTC File Name\" , \"type\" : \"STRING\" }, { \"description\" : \"Chrony configuration file.|TextArea\" , \"id\" : \"chrony.advanced.config\" , \"isRequired\" : false , \"name\" : \"Chrony Configuration\" , \"type\" : \"STRING\" } ], \"description\" : \"ClockService Configuration\" , \"icon\" : [ { \"resource\" : \"ClockService\" , \"size\" : 32 } ], \"id\" : \"org.eclipse.kura.clock.ClockService\" , \"name\" : \"ClockService\" }, \"pid\" : \"org.eclipse.kura.clock.ClockService\" , \"properties\" : { \"clock.ntp.host\" : { \"type\" : \"STRING\" , \"value\" : \"0.pool.ntp.org\" }, \"clock.ntp.max-retry\" : { \"type\" : \"INTEGER\" , \"value\" : 0 }, \"clock.ntp.port\" : { \"type\" : \"INTEGER\" , \"value\" : 123 }, \"clock.ntp.refresh-interval\" : { \"type\" : \"INTEGER\" , \"value\" : 3600 }, \"clock.ntp.retry.interval\" : { \"type\" : \"INTEGER\" , \"value\" : 5 }, \"clock.ntp.timeout\" : { \"type\" : \"INTEGER\" , \"value\" : 10000 }, \"clock.provider\" : { \"type\" : \"STRING\" , \"value\" : \"java-ntp\" }, \"clock.set.hwclock\" : { \"type\" : \"BOOLEAN\" , \"value\" : true }, \"enabled\" : { \"type\" : \"BOOLEAN\" , \"value\" : true }, \"kura.service.pid\" : { \"type\" : \"STRING\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" }, \"rtc.filename\" : { \"type\" : \"STRING\" , \"value\" : \"/dev/rtc0\" }, \"service.pid\" : { \"type\" : \"STRING\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" } } }, { \"definition\" : { \"ad\" : [ { \"defaultValue\" : \"(kura.service.pid=org.eclipse.kura.ssl.SslManagerService)\" , \"description\" : \"Specifies, as an OSGi target filter, the pid of the SslManagerService used to create SSL connections for downloading packages.\" , \"id\" : \"SslManagerService.target\" , \"isRequired\" : true , \"name\" : \"SslManagerService Target Filter\" , \"type\" : \"STRING\" } ], \"description\" : \"This service is responsible of managing the deployment packages installed on the system.\" , \"id\" : \"org.eclipse.kura.deployment.agent\" , \"name\" : \"DeploymentAgent\" }, \"pid\" : \"org.eclipse.kura.deployment.agent\" , \"properties\" : { \"SslManagerService.target\" : { \"type\" : \"STRING\" , \"value\" : \"(kura.service.pid=org.eclipse.kura.ssl.SslManagerService)\" }, \"kura.service.pid\" : { \"type\" : \"STRING\" , \"value\" : \"org.eclipse.kura.deployment.agent\" }, \"service.pid\" : { \"type\" : \"STRING\" , \"value\" : \"org.eclipse.kura.deployment.agent\" } } } ] } CreateFactoryComponentConfigurationsRequest An object describing a factory component instance creation request. Properties : configs : array The set of configurations to be created array elements: object An object describing a factory component confguration. Properties : pid : string The component pid. factoryPid : string The component factory pid properties : object optional If omitted, the component innstance will be created with default configuration. ConfigurationProperties takeSnapshot : bool optional The true value will be used as default if not explicitly specified Defines whether a new snapshot should be created after that the factory component configuration instances have been created. { \"configs\" : [ { \"factoryPid\" : \"org.eclipse.kura.core.db.H2DbServer\" , \"pid\" : \"testComponent\" , \"properties\" : { \"db.server.type\" : { \"type\" : \"STRING\" , \"value\" : \"WEB\" } } }, { \"factoryPid\" : \"org.eclipse.kura.core.db.H2DbServer\" , \"pid\" : \"thirdComponent\" } ], \"takeSnapshot\" : true } UpdateComponentConfigurationRequest An object that describes a set of configurations that need to be updated. Properties : configs : array The configurations to be updated. The ocd field can be omitted, it will be ignored if specified. array elements: object ComponentConfiguration takeSnapshot : bool optional The true value will be used as default if not explicitly specified Defines whether a new snapshot should be created after that the component configurations have been applied. { \"configs\" : [ { \"pid\" : \"org.eclipse.kura.cloud.app.command.CommandCloudApp\" , \"properties\" : { \"command.enable\" : { \"type\" : \"BOOLEAN\" , \"value\" : true }, \"command.timeout\" : { \"type\" : \"INTEGER\" , \"value\" : 60 } } }, { \"pid\" : \"org.eclipse.kura.position.PositionService\" , \"properties\" : { \"parity\" : { \"type\" : \"STRING\" , \"value\" : 0 } } } ], \"takeSnapshot\" : true } DeleteFactoryComponentConfigurationsRequest An object describing a factory component instance delete request. Properties : pids : array The list of the pids of the factory component instances to be deleted. array elements: string The component pid. takeSnapshot : bool optional The true value will be used as default if not explicitly specified Defines whether a new snapshot should be created after that the factory component configuration instances have been deleted. { \"pids\" : [ \"testComponent\" , \"otherComponent\" ], \"takeSnapshot\" : true } PidSet Represents a set of pids or factory pids. Properties : pids : array The set of pids array elements: string The pid { \"pids\" : [ \"org.eclipse.kura.deployment.agent\" , \"org.eclipse.kura.clock.ClockService\" ] } SnaphsotId An object describing the identifier of a configuration snapshot. Properties : id : number The snapshot id { \"id\" : 163655959932 } GenericFailureReport An object reporting a failure message. Properties : message : string A message describing the failure. { \"message\" : \"An unexpected error occurred.\" } BatchFailureReport An object that is returned by requests that involve multiple operations, when at least one operation failed. This object report an error message for each of the operations that failed. The operations are identified by an id, see request documentation for more details. If an operation is not listed by this object, then the operation succeeded. Properties : failures : array The list of operations that failed. array elements: object An object reporting details about an operation failure. Properties : id : string An identifier of the failed operation. message : string A message describing the failure. { \"failures\" : [ { \"id\" : \"create:testComponent\" , \"message\" : \"Invalid parameter. pid testComponent already exists\" }, { \"id\" : \"create:otherComponent\" , \"message\" : \"Invalid parameter. pid otherComponent already exists\" } ] }","title":"Configuration V2 REST APIs and CONF-V2 Request Handler"},{"location":"core-services/configuration-service-rest-v2/#configuration-v2-rest-apis-and-conf-v2-request-handler","text":"This page describes the CONF-V2 request handler and configuration/v2 rest APIs. Accessing the REST APIs requires to use an identity with the rest.configuration permission assigned. Request definitions GET/snapshots GET/factoryComponents POST/factoryComponents DEL/factoryComponents/byPid GET/factoryComponents/ocd POST/factoryComponents/ocd/byFactoryPid GET/configurableComponents GET/configurableComponents/pidsWithFactory GET/configurableComponents/configurations POST/configurableComponents/configurations/byPid POST/configurableComponents/configurations/byPid/_default PUT/configurableComponents/configurations/_update EXEC/snapshots/_write EXEC/snapshots/_rollback EXEC/snapshots/byId/_rollback JSON definitions PidAndFactoryPidSet SnapshotIdSet PropertyType ConfigurationProperty ConfigurationProperties Option AttributeDefinition ObjectClassDefinition ComponentConfiguration ComponentConfigurationList CreateFactoryComponentConfigurationsRequest UpdateComponentConfigurationRequest DeleteFactoryComponentConfigurationsRequest PidSet SnaphsotId GenericFailureReport BatchFailureReport","title":"Configuration V2 REST APIs and CONF-V2 Request Handler"},{"location":"core-services/configuration-service-rest-v2/#request-definitions","text":"","title":"Request definitions"},{"location":"core-services/configuration-service-rest-v2/#getsnapshots","text":"REST API path : /services/configuration/v2/snapshots description : Returns the ids of the snapshots currently stored on the device. responses : 200 description : The snapshot id set. response body : SnapshotIdSet 500 description : An unexpected internal error occurred. response body : GenericFailureReport","title":"GET/snapshots"},{"location":"core-services/configuration-service-rest-v2/#getfactorycomponents","text":"REST API path : /services/configuration/v2/factoryComponents description : Returns the ids of the component factories available on the device. responses : 200 description : The factory pid set. response body : PidSet 500 description : An unexpected internal error occurred. response body : GenericFailureReport","title":"GET/factoryComponents"},{"location":"core-services/configuration-service-rest-v2/#postfactorycomponents","text":"REST API path : /services/configuration/v2/factoryComponents description : This is a batch request that allows to create one or more factory component instances and optionally create a new snapshot. request body : CreateFactoryComponentConfigurationsRequest responses : 200 description : The request succeeded. 400 description : The request body is not valid JSON or it contains invalid parameters. response body : GenericFailureReport 500 description : In case of processing errors, the device will attempt to return a detailed error response containing a message describing the failure reason for each operation. The operation ids are the following: create:$pid for component creation operations, where $pid is the pid of the instance, and snapshot , for the snapshot creation operation. In case of an unexpected failure, a generic error response will be returned. response body : Variants : object GenericFailureReport object BatchFailureReport","title":"POST/factoryComponents"},{"location":"core-services/configuration-service-rest-v2/#delfactorycomponentsbypid","text":"REST API path : /services/configuration/v2/factoryComponents/byPid description : This is a batch request that allows to delete one or more factory component instances and optionally create a new snapshot. request body : DeleteFactoryComponentConfigurationsRequest responses : 200 description : The request succeeded. 400 description : The request body is not valid JSON or it contains invalid parameters. response body : GenericFailureReport 500 description : In case of processing errors, the device will attempt to return a detailed error response containing a message describing the failure reason for each operation. The operation ids are the following: delete:$pid for component delete operations, where $pid is the pid of the instance, and snapshot , for the snapshot creation operation. In case of an unexpected failure, a generic error response will be returned. response body : Variants : object GenericFailureReport object BatchFailureReport","title":"DEL/factoryComponents/byPid"},{"location":"core-services/configuration-service-rest-v2/#getfactorycomponentsocd","text":"REST API path : /services/configuration/v2/factoryComponents/ocd description : Returns the OCD of the components created by the factories available on the device without the need of creating an instance. This request returns the information related to all available factories. responses : 200 description : The request succeeded. The pid property of the received configurations will report the factory pid, the ocd field will contain the definition, the properties field will not be present. response body : ComponentConfigurationList 500 description : An unexpected internal error occurred. response body : GenericFailureReport","title":"GET/factoryComponents/ocd"},{"location":"core-services/configuration-service-rest-v2/#postfactorycomponentsocdbyfactorypid","text":"REST API path : /services/configuration/v2/factoryComponents/ocd/byFactoryPid description : Returns the OCD of the components created by the factories available on the device without the need of creating an instance. This request returns the information related to a user selected set of factories. request body : PidSet responses : 200 description : The request succeeded. The pid property of the received configurations will report the factory pid, the ocd field will contain the definition, the properties field will not be present. If the OCD for a given factory pid cannot be found, it will not be included in the result. response body : ComponentConfigurationList 400 description : The request body is not valid JSON or it contains invalid parameters. response body : GenericFailureReport 500 description : An unexpected internal error occurred. response body : GenericFailureReport","title":"POST/factoryComponents/ocd/byFactoryPid"},{"location":"core-services/configuration-service-rest-v2/#getconfigurablecomponents","text":"REST API path : /services/configuration/v2/configurableComponents description : Returns the list of the pids available on the system. responses : 200 description : The request succeeded. response body : PidSet 500 description : An unexpected internal error occurred. response body : GenericFailureReport","title":"GET/configurableComponents"},{"location":"core-services/configuration-service-rest-v2/#getconfigurablecomponentspidswithfactory","text":"REST API path : /services/configuration/v2/configurableComponents/pidsWithFactory description : Returns the list of the pids available on the system, reporting also the factory pid where applicable. responses : 200 description : The request succeeded. response body : PidAndFactoryPidSet 500 description : An unexpected internal error occurred. response body : GenericFailureReport","title":"GET/configurableComponents/pidsWithFactory"},{"location":"core-services/configuration-service-rest-v2/#getconfigurablecomponentsconfigurations","text":"REST API path : /services/configuration/v2/configurableComponents/configurations description : Returns all of component configurations available on the system. This request will return the pid , ocd and properties . responses : 200 description : The request succeeded. response body : ComponentConfigurationList 500 description : An unexpected internal error occurred. response body : GenericFailureReport","title":"GET/configurableComponents/configurations"},{"location":"core-services/configuration-service-rest-v2/#postconfigurablecomponentsconfigurationsbypid","text":"REST API path : /services/configuration/v2/configurableComponents/configurations/byPid description : Returns a user selected set of configurations. This request will return the pid , ocd and properties . request body : PidSet responses : 200 description : The request succeeded. If the configuration for a given pid cannot be found, it will not be included in the result. response body : ComponentConfigurationList 400 description : The request body is not valid JSON or it contains invalid parameters. response body : GenericFailureReport 500 description : An unexpected internal error occurred. response body : GenericFailureReport","title":"POST/configurableComponents/configurations/byPid"},{"location":"core-services/configuration-service-rest-v2/#postconfigurablecomponentsconfigurationsbypid_default","text":"REST API path : /services/configuration/v2/configurableComponents/configurations/byPid/_default description : Returns the default configuration for a given set of component pids. The default configurations are generated basing on component definition only, user applied modifications will not be taken into account. This request will return the pid , ocd and properties . request body : PidSet responses : 200 description : The request succeeded. If the configuration for a given pid cannot be found, it will not be included in the result. response body : ComponentConfigurationList 400 description : The request body is not valid JSON or it contains invalid parameters. response body : GenericFailureReport 500 description : An unexpected internal error occurred. response body : GenericFailureReport","title":"POST/configurableComponents/configurations/byPid/_default"},{"location":"core-services/configuration-service-rest-v2/#putconfigurablecomponentsconfigurations_update","text":"REST API path : /services/configuration/v2/configurableComponents/configurations/_update description : Updates a given set of component configurations. This request can be also used to apply a configuration snapshot. request body : UpdateComponentConfigurationRequest responses : 200 description : The request succeeded. 400 description : The request body is not valid JSON or it contains invalid parameters. response body : GenericFailureReport 500 description : In case of processing errors, the device will attempt to return a detailed error response containing a message describing the failure reason for each operation. The operation ids are the following: update:$pid for component update operations, where $pid is the pid of the instance, and snapshot , for the snapshot creation operation. In case of an unexpected failure, a generic error response will be returned. response body : Variants : object GenericFailureReport object BatchFailureReport","title":"PUT/configurableComponents/configurations/_update"},{"location":"core-services/configuration-service-rest-v2/#execsnapshots_write","text":"REST API path : /services/configuration/v2/snapshots/_write description : Requests the device to create a new snasphot based on the current defice configuration. If this request is used through REST API, the POST method must be used. responses : 200 description : The request succeeded. The result is the identifier of the new snsapsot response body : SnaphsotId 500 description : An unexpected internal error occurred. response body : GenericFailureReport","title":"EXEC/snapshots/_write"},{"location":"core-services/configuration-service-rest-v2/#execsnapshots_rollback","text":"REST API path : /services/configuration/v2/snapshots/_rollback description : Rollbacks the framework to the last saved snapshot if available. If this request is used through REST API, the POST method must be used. responses : 200 description : The request succeeded. The result contains the id of the snapshot used for rollback. response body : SnaphsotId 500 description : An unexpected internal error occurred. response body : GenericFailureReport","title":"EXEC/snapshots/_rollback"},{"location":"core-services/configuration-service-rest-v2/#execsnapshotsbyid_rollback","text":"REST API path : /services/configuration/v2/snapshots/byId/_rollback description : Performs a rollback to the snapshot id specified by the user. responses : 200 description : The request succeeded. 400 description : The request body is not valid JSON or it contains invalid parameters. response body : GenericFailureReport 500 description : An unexpected internal error occurred. response body : GenericFailureReport","title":"EXEC/snapshots/byId/_rollback"},{"location":"core-services/configuration-service-rest-v2/#json-definitions","text":"","title":"JSON definitions"},{"location":"core-services/configuration-service-rest-v2/#pidandfactorypidset","text":"Represents a set of pids with the corresponding factory pid. Properties : components : array The set of pids and factory pids array elements: object The pid and factory pid Properties : pid : string The component pid. factoryPid : string optional Can be missing if the described component is not a factory instance. The factory pid { \"components\" : [ { \"factoryPid\" : \"org.eclipse.kura.core.db.H2DbService\" , \"pid\" : \"org.eclipse.kura.db.H2DbService\" }, { \"factoryPid\" : \"org.eclipse.kura.core.data.transport.mqtt.MqttDataTransport\" , \"pid\" : \"org.eclipse.kura.core.data.transport.mqtt.MqttDataTransport\" }, { \"pid\" : \"org.eclipse.kura.web.Console\" } ] }","title":"PidAndFactoryPidSet"},{"location":"core-services/configuration-service-rest-v2/#snapshotidset","text":"An object decribing a set of configuration snapshot ids Properties : ids : array The set of snapshot ids. array elements: number A snapshot id. { \"ids\" : [ 0 , 1638438049921 , 1638438146960 , 1638439710944 , 1638439717931 , 1638439734077 , 1638439767252 , 1638521986953 , 1638521993692 , 1638522572822 ] }","title":"SnapshotIdSet"},{"location":"core-services/configuration-service-rest-v2/#propertytype","text":"A string that describes the type of a configuration property. * Possible values * STRING * LONG * DOUBLE * FLOAT * INTEGER * BYTE * CHAR * BOOLEAN * SHORT * PASSWORD \"STRING\"","title":"PropertyType"},{"location":"core-services/configuration-service-rest-v2/#configurationproperty","text":"An object describing a configuration property. Properties : type : string (enumerated) PropertyType value : variant optional In requests, this field can be omitted or set to null to assign the null value to a non required configuration property. Describes the property value. The value type depends on the type property. Variants : number If type is LONG , DOUBLE , FLOAT , INTEGER , BYTE or SHORT and the property does not represent an array. string If type is STRING , PASSWORD or CHAR and the property is not an array. In case of CHAR type, the value must have a length of 1. bool If type is BOOLEAN and the property is not an array array If type is LONG , DOUBLE , FLOAT , INTEGER , BYTE or SHORT and the property represents an array. array elements: number The property values as numbers. array If type is STRING , PASSWORD or CHAR and the property is an array. array elements: string The property values as strings. In case of CHAR type, the values must have a length of 1. array If type is BOOLEAN and the property is an array array elements: bool The property values as booleans. { \"type\" : \"STRING\" , \"value\" : \"foo\" } { \"type\" : \"STRING\" , \"value\" : [ \"foo\" , \"bar\" ] } { \"type\" : \"INTEGER\" , \"value\" : 12 } { \"type\" : \"LONG\" , \"value\" : [ 1 , 2 , 3 , 4 ] } { \"type\" : \"PASSWORD\" , \"value\" : \"myPassword\" } { \"type\" : \"PASSWORD\" , \"value\" : [ \"my\" , \"password\" , \"array\" ] }","title":"ConfigurationProperty"},{"location":"core-services/configuration-service-rest-v2/#configurationproperties","text":"An object representing a set of configuration properties. The members of this object represent configuration property, the member names represent the configuration property ids. This object can have a variable number of members. Properties : propertyName : object ConfigurationProperty { \"KeystoreService.target\" : { \"type\" : \"STRING\" , \"value\" : \"(kura.service.pid=HttpsKeystore)\" }, \"https.client.auth.ports\" : { \"type\" : \"INTEGER\" , \"value\" : [ 4443 ] }, \"https.client.revocation.soft.fail\" : { \"type\" : \"BOOLEAN\" , \"value\" : false }, \"https.ports\" : { \"type\" : \"INTEGER\" , \"value\" : [ 443 ] }, \"https.revocation.check.enabled\" : { \"type\" : \"BOOLEAN\" , \"value\" : false }, \"kura.service.pid\" : { \"type\" : \"STRING\" , \"value\" : \"org.eclipse.kura.http.server.manager.HttpService\" }, \"service.pid\" : { \"type\" : \"STRING\" , \"value\" : \"org.eclipse.kura.http.server.manager.HttpService\" }, \"ssl.revocation.mode\" : { \"type\" : \"STRING\" , \"value\" : \"PREFER_OCSP\" } }","title":"ConfigurationProperties"},{"location":"core-services/configuration-service-rest-v2/#option","text":"An object describing an allowed element for a multi choiche field. Properties : label : string optional This parameter may not be specified by component configuration. An user friendly label for the option. value : string The option value encoded as a string. { \"label\" : \"Value 1\" , \"value\" : \"1\" } { \"value\" : \"foo\" }","title":"Option"},{"location":"core-services/configuration-service-rest-v2/#attributedefinition","text":"A descriptor of a configuration property. Properties : id : string The id of the attribute definition. This field corresponds to the configuration property name. type : string (enumerated) PropertyType name : string optional This parameter may not be specified by component configuration. An user friendly name for the property. description : string optional This parameter may not be specified by component configuration. An user friendly description for the property. cardinality : number An integer describing the property cardinality. If the value is 0, then the property is a singleton value (not an array), if it is > 0, then the configuration property is an array and this property specifies the maximum allowed array length. min : string optional This parameter may not be specified by component configuration. If not specified, the property does not have a minimum value. Specifies the minimum value for this property as a string. max : string optional This parameter may not be specified by component configuration. If not specified, the property does not have a maximum value. Specifies the maximum value for this property as a string. isRequired : bool Specifies whether the configuration parameter is required or not. defaultValue : string optional This parameter may not be specified by component configuration. Specifies the default value for this property as a string. option : array optional If specified, describes a set of allowed values for the configuration property. The allowed values for this configuration properties array elements: object Option { \"defaultValue\" : \"false\" , \"description\" : \"Specifies whether the DB server is enabled or not.\" , \"id\" : \"db.server.enabled\" , \"isRequired\" : true , \"name\" : \"db.server.enabled\" , \"type\" : \"BOOLEAN\" } { \"defaultValue\" : \"TCP\" , \"description\" : \"Specifies the server type, see http://www.h2database.com/javadoc/org/h2/tools/Server.html for more details.\" , \"id\" : \"db.server.type\" , \"isRequired\" : true , \"name\" : \"db.server.type\" , \"option\" : [ { \"label\" : \"WEB\" , \"value\" : \"WEB\" }, { \"label\" : \"TCP\" , \"value\" : \"TCP\" }, { \"label\" : \"PG\" , \"value\" : \"PG\" } ], \"type\" : \"STRING\" }","title":"AttributeDefinition"},{"location":"core-services/configuration-service-rest-v2/#objectclassdefinition","text":"Provides some metadata information about a component configuration. Properties : ad : array The metadata about the configuration properties. array elements: object AttributeDefinition icon : array optional Can be missing if the OCD does not define icons. A list of icons that visually represent the configuration. array elements: object Properties : resource : string An identifier of the icon image resource. size : number The icon width and height in pixels. name : string A user friendly name for the component configuration. description : string A user friendly description of the component configuration. id : string An identifier of the component configuration. { \"ad\" : [ { \"defaultValue\" : \"false\" , \"description\" : \"The WatchdogService monitors CriticalComponents and reboots the system if one of them hangs. Once enabled the WatchdogService starts refreshing the watchdog device, which will reset the system if WatchdogService hangs.\" , \"id\" : \"enabled\" , \"isRequired\" : true , \"name\" : \"Watchdog enable\" , \"type\" : \"BOOLEAN\" }, { \"defaultValue\" : \"10000\" , \"description\" : \"WatchdogService's refresh interval in ms of the Watchdog device. The value can be set between 1 and 60 seconds and should not be set to a value greater or equal to the Watchdog device's timeout value\" , \"id\" : \"pingInterval\" , \"isRequired\" : true , \"max\" : \"60000\" , \"name\" : \"Watchdog refresh interval\" , \"type\" : \"INTEGER\" }, { \"defaultValue\" : \"/dev/watchdog\" , \"description\" : \"Watchdog device path e.g. /dev/watchdog.\" , \"id\" : \"watchdogDevice\" , \"isRequired\" : true , \"name\" : \"Watchdog device path\" , \"type\" : \"STRING\" }, { \"defaultValue\" : \"/opt/eclipse/kura/data/kura-reboot-cause\" , \"description\" : \"The path for the file that will contain the reboot cause information.\" , \"id\" : \"rebootCauseFilePath\" , \"isRequired\" : true , \"name\" : \"Reboot Cause File Path\" , \"type\" : \"STRING\" } ], \"description\" : \"The WatchdogService handles the hardware watchdog of the platform. The parameter define the ping periodicity of the hardware watchdog to ensure it does not reboot. The WatchdogService will reset the watchdog timeout, can disable it (where supported) with the Magic Character, but cannot set the refresh rate of a watchdog device.\" , \"icon\" : [ { \"resource\" : \"WatchdogService\" , \"size\" : 32 } ], \"id\" : \"org.eclipse.kura.watchdog.WatchdogService\" , \"name\" : \"WatchdogService\" }","title":"ObjectClassDefinition"},{"location":"core-services/configuration-service-rest-v2/#componentconfiguration","text":"Describes a component configuration. Properties : pid : string The identifier of this configuration. ocd : object optional Can be omitted in some requests and responses, see request documentation for more information. ObjectClassDefinition properties : object optional Can be omitted in some requests and responses, see request documentation for more information. ConfigurationProperties { \"definition\" : { \"ad\" : [ { \"cardinality\" : 3 , \"description\" : \"If set to a non empty list, REST API access will be allowed only on the specified ports. If set to an empty list, access will be allowed on all ports. Please make sure that the allowed ports are open in HttpService and Firewall configuration.\" , \"id\" : \"allowed.ports\" , \"isRequired\" : false , \"max\" : \"65535\" , \"min\" : \"1\" , \"name\" : \"Allowed ports\" , \"type\" : \"INTEGER\" } ], \"description\" : \"This service allows to configure settings related to Kura REST APIs\" , \"id\" : \"org.eclipse.kura.internal.rest.provider.RestService\" , \"name\" : \"RestService\" }, \"pid\" : \"org.eclipse.kura.internal.rest.provider.RestService\" , \"properties\" : { \"kura.service.pid\" : { \"type\" : \"STRING\" , \"value\" : \"org.eclipse.kura.internal.rest.provider.RestService\" }, \"service.pid\" : { \"type\" : \"STRING\" , \"value\" : \"org.eclipse.kura.internal.rest.provider.RestService\" } } }","title":"ComponentConfiguration"},{"location":"core-services/configuration-service-rest-v2/#componentconfigurationlist","text":"Represents a list of component configurations. Properties : configs : array The component configurations array elements: object ComponentConfiguration { \"configs\" : [ { \"definition\" : { \"ad\" : [ { \"defaultValue\" : \"true\" , \"description\" : \"Whether or not to enable the ClockService\" , \"id\" : \"enabled\" , \"isRequired\" : true , \"name\" : \"enabled\" , \"type\" : \"BOOLEAN\" }, { \"defaultValue\" : \"true\" , \"description\" : \"Whether or not to sync the system hardware clock after the system time gets set\" , \"id\" : \"clock.set.hwclock\" , \"isRequired\" : true , \"name\" : \"clock.set.hwclock\" , \"type\" : \"BOOLEAN\" }, { \"defaultValue\" : \"java-ntp\" , \"description\" : \"Source for setting the system clock. Verify the availabiliy of the selected provider before activate it.\" , \"id\" : \"clock.provider\" , \"isRequired\" : true , \"name\" : \"clock.provider\" , \"option\" : [ { \"label\" : \"java-ntp\" , \"value\" : \"java-ntp\" }, { \"label\" : \"ntpd\" , \"value\" : \"ntpd\" }, { \"label\" : \"chrony-advanced\" , \"value\" : \"chrony-advanced\" } ], \"type\" : \"STRING\" }, { \"defaultValue\" : \"0.pool.ntp.org\" , \"description\" : \"The hostname that provides the system time via NTP\" , \"id\" : \"clock.ntp.host\" , \"isRequired\" : true , \"name\" : \"clock.ntp.host\" , \"type\" : \"STRING\" }, { \"defaultValue\" : \"123\" , \"description\" : \"The port number that provides the system time via NTP\" , \"id\" : \"clock.ntp.port\" , \"isRequired\" : true , \"max\" : \"65535\" , \"min\" : \"1\" , \"name\" : \"clock.ntp.port\" , \"type\" : \"INTEGER\" }, { \"defaultValue\" : \"10000\" , \"description\" : \"The NTP timeout in milliseconds\" , \"id\" : \"clock.ntp.timeout\" , \"isRequired\" : true , \"min\" : \"1000\" , \"name\" : \"clock.ntp.timeout\" , \"type\" : \"INTEGER\" }, { \"defaultValue\" : \"0\" , \"description\" : \"The maximum number of retries for the initial synchronization (with interval clock.ntp.retry.interval). If set to 0 the service will retry forever.\" , \"id\" : \"clock.ntp.max-retry\" , \"isRequired\" : true , \"min\" : \"0\" , \"name\" : \"clock.ntp.max-retry\" , \"type\" : \"INTEGER\" }, { \"defaultValue\" : \"5\" , \"description\" : \"When sync fails, interval in seconds between each retry.\" , \"id\" : \"clock.ntp.retry.interval\" , \"isRequired\" : true , \"min\" : \"1\" , \"name\" : \"clock.ntp.retry.interval\" , \"type\" : \"INTEGER\" }, { \"defaultValue\" : \"3600\" , \"description\" : \"Whether or not to sync the clock and if so, the frequency in seconds. If less than zero - no update, if equal to zero - sync once at startup, if greater than zero - the frequency in seconds to perform a new clock sync\" , \"id\" : \"clock.ntp.refresh-interval\" , \"isRequired\" : true , \"name\" : \"clock.ntp.refresh-interval\" , \"type\" : \"INTEGER\" }, { \"defaultValue\" : \"/dev/rtc0\" , \"description\" : \"The RTC File Name. It defaults to /dev/rtc0. This option is not used if chrony-advanced option is selected in clock.provider.\" , \"id\" : \"rtc.filename\" , \"isRequired\" : true , \"name\" : \"RTC File Name\" , \"type\" : \"STRING\" }, { \"description\" : \"Chrony configuration file.|TextArea\" , \"id\" : \"chrony.advanced.config\" , \"isRequired\" : false , \"name\" : \"Chrony Configuration\" , \"type\" : \"STRING\" } ], \"description\" : \"ClockService Configuration\" , \"icon\" : [ { \"resource\" : \"ClockService\" , \"size\" : 32 } ], \"id\" : \"org.eclipse.kura.clock.ClockService\" , \"name\" : \"ClockService\" }, \"pid\" : \"org.eclipse.kura.clock.ClockService\" , \"properties\" : { \"clock.ntp.host\" : { \"type\" : \"STRING\" , \"value\" : \"0.pool.ntp.org\" }, \"clock.ntp.max-retry\" : { \"type\" : \"INTEGER\" , \"value\" : 0 }, \"clock.ntp.port\" : { \"type\" : \"INTEGER\" , \"value\" : 123 }, \"clock.ntp.refresh-interval\" : { \"type\" : \"INTEGER\" , \"value\" : 3600 }, \"clock.ntp.retry.interval\" : { \"type\" : \"INTEGER\" , \"value\" : 5 }, \"clock.ntp.timeout\" : { \"type\" : \"INTEGER\" , \"value\" : 10000 }, \"clock.provider\" : { \"type\" : \"STRING\" , \"value\" : \"java-ntp\" }, \"clock.set.hwclock\" : { \"type\" : \"BOOLEAN\" , \"value\" : true }, \"enabled\" : { \"type\" : \"BOOLEAN\" , \"value\" : true }, \"kura.service.pid\" : { \"type\" : \"STRING\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" }, \"rtc.filename\" : { \"type\" : \"STRING\" , \"value\" : \"/dev/rtc0\" }, \"service.pid\" : { \"type\" : \"STRING\" , \"value\" : \"org.eclipse.kura.clock.ClockService\" } } }, { \"definition\" : { \"ad\" : [ { \"defaultValue\" : \"(kura.service.pid=org.eclipse.kura.ssl.SslManagerService)\" , \"description\" : \"Specifies, as an OSGi target filter, the pid of the SslManagerService used to create SSL connections for downloading packages.\" , \"id\" : \"SslManagerService.target\" , \"isRequired\" : true , \"name\" : \"SslManagerService Target Filter\" , \"type\" : \"STRING\" } ], \"description\" : \"This service is responsible of managing the deployment packages installed on the system.\" , \"id\" : \"org.eclipse.kura.deployment.agent\" , \"name\" : \"DeploymentAgent\" }, \"pid\" : \"org.eclipse.kura.deployment.agent\" , \"properties\" : { \"SslManagerService.target\" : { \"type\" : \"STRING\" , \"value\" : \"(kura.service.pid=org.eclipse.kura.ssl.SslManagerService)\" }, \"kura.service.pid\" : { \"type\" : \"STRING\" , \"value\" : \"org.eclipse.kura.deployment.agent\" }, \"service.pid\" : { \"type\" : \"STRING\" , \"value\" : \"org.eclipse.kura.deployment.agent\" } } } ] }","title":"ComponentConfigurationList"},{"location":"core-services/configuration-service-rest-v2/#createfactorycomponentconfigurationsrequest","text":"An object describing a factory component instance creation request. Properties : configs : array The set of configurations to be created array elements: object An object describing a factory component confguration. Properties : pid : string The component pid. factoryPid : string The component factory pid properties : object optional If omitted, the component innstance will be created with default configuration. ConfigurationProperties takeSnapshot : bool optional The true value will be used as default if not explicitly specified Defines whether a new snapshot should be created after that the factory component configuration instances have been created. { \"configs\" : [ { \"factoryPid\" : \"org.eclipse.kura.core.db.H2DbServer\" , \"pid\" : \"testComponent\" , \"properties\" : { \"db.server.type\" : { \"type\" : \"STRING\" , \"value\" : \"WEB\" } } }, { \"factoryPid\" : \"org.eclipse.kura.core.db.H2DbServer\" , \"pid\" : \"thirdComponent\" } ], \"takeSnapshot\" : true }","title":"CreateFactoryComponentConfigurationsRequest"},{"location":"core-services/configuration-service-rest-v2/#updatecomponentconfigurationrequest","text":"An object that describes a set of configurations that need to be updated. Properties : configs : array The configurations to be updated. The ocd field can be omitted, it will be ignored if specified. array elements: object ComponentConfiguration takeSnapshot : bool optional The true value will be used as default if not explicitly specified Defines whether a new snapshot should be created after that the component configurations have been applied. { \"configs\" : [ { \"pid\" : \"org.eclipse.kura.cloud.app.command.CommandCloudApp\" , \"properties\" : { \"command.enable\" : { \"type\" : \"BOOLEAN\" , \"value\" : true }, \"command.timeout\" : { \"type\" : \"INTEGER\" , \"value\" : 60 } } }, { \"pid\" : \"org.eclipse.kura.position.PositionService\" , \"properties\" : { \"parity\" : { \"type\" : \"STRING\" , \"value\" : 0 } } } ], \"takeSnapshot\" : true }","title":"UpdateComponentConfigurationRequest"},{"location":"core-services/configuration-service-rest-v2/#deletefactorycomponentconfigurationsrequest","text":"An object describing a factory component instance delete request. Properties : pids : array The list of the pids of the factory component instances to be deleted. array elements: string The component pid. takeSnapshot : bool optional The true value will be used as default if not explicitly specified Defines whether a new snapshot should be created after that the factory component configuration instances have been deleted. { \"pids\" : [ \"testComponent\" , \"otherComponent\" ], \"takeSnapshot\" : true }","title":"DeleteFactoryComponentConfigurationsRequest"},{"location":"core-services/configuration-service-rest-v2/#pidset","text":"Represents a set of pids or factory pids. Properties : pids : array The set of pids array elements: string The pid { \"pids\" : [ \"org.eclipse.kura.deployment.agent\" , \"org.eclipse.kura.clock.ClockService\" ] }","title":"PidSet"},{"location":"core-services/configuration-service-rest-v2/#snaphsotid","text":"An object describing the identifier of a configuration snapshot. Properties : id : number The snapshot id { \"id\" : 163655959932 }","title":"SnaphsotId"},{"location":"core-services/configuration-service-rest-v2/#genericfailurereport","text":"An object reporting a failure message. Properties : message : string A message describing the failure. { \"message\" : \"An unexpected error occurred.\" }","title":"GenericFailureReport"},{"location":"core-services/configuration-service-rest-v2/#batchfailurereport","text":"An object that is returned by requests that involve multiple operations, when at least one operation failed. This object report an error message for each of the operations that failed. The operations are identified by an id, see request documentation for more details. If an operation is not listed by this object, then the operation succeeded. Properties : failures : array The list of operations that failed. array elements: object An object reporting details about an operation failure. Properties : id : string An identifier of the failed operation. message : string A message describing the failure. { \"failures\" : [ { \"id\" : \"create:testComponent\" , \"message\" : \"Invalid parameter. pid testComponent already exists\" }, { \"id\" : \"create:otherComponent\" , \"message\" : \"Invalid parameter. pid otherComponent already exists\" } ] }","title":"BatchFailureReport"},{"location":"core-services/configuration-service/","text":"Configuration Service The Configuration Service is responsible to manage the framework configuration by creating and persisting the framework snapshot. Built on top of the OSGi Configuration Admin and Metatype services, it is also responsible to track and manage the creation and deletion of service instances as well as OSGi component factories. The Configuration Service is accessible using the following REST APIs and cloud request handlers: Configuration V1 REST APIs (deprecated) Configuration V2 REST APIs and CONF-V2 request handler","title":"Configuration Service"},{"location":"core-services/configuration-service/#configuration-service","text":"The Configuration Service is responsible to manage the framework configuration by creating and persisting the framework snapshot. Built on top of the OSGi Configuration Admin and Metatype services, it is also responsible to track and manage the creation and deletion of service instances as well as OSGi component factories. The Configuration Service is accessible using the following REST APIs and cloud request handlers: Configuration V1 REST APIs (deprecated) Configuration V2 REST APIs and CONF-V2 request handler","title":"Configuration Service"},{"location":"core-services/container-orchestration-provider-apis/","text":"Container Orchestration Provider APIs Java API ContainerOrchestrationService The ContainerOrchestrationService is used to directly communicate with the running container engine. It exposes methods for listing, creating, and stopping containers. This class utilizes an instantiated ContainerConfiguration object as a parameter for container creation. ContainerConfiguration The ContainerConfiguration class, allows you to define a container to create. Using the embedded builder class, one can define many container-related parameters such as name, image, ports and volume mounts. ContainerInstanceDescriptor The ContainerInstanceDescriptor class is used to describe a container that has already been created. This class contains runtime information such as the ID of the container. ContainerState The ContainerState is a class that exposes an enum of container states tracked by the framework. PasswordRegistryCredentials The PasswordRegistryCredentials class stores password credentials when provisioning a container to pull from an alternative password-protected registry. PasswordRegistryCredentials The PasswordRegistryCredentials class stores password credentials when provisioning a container to pull from an alternative password-protected registry. Note The Container Orchestration Provider exports an MQTT-Namespace API. This API can be used to manage containers via MQTT requests from external applications. Please visit the Remote Gateway Inventory via MQTT documentation for more information.","title":"Container Orchestration Provider APIs"},{"location":"core-services/container-orchestration-provider-apis/#container-orchestration-provider-apis","text":"","title":"Container Orchestration Provider APIs"},{"location":"core-services/container-orchestration-provider-apis/#java-api","text":"","title":"Java API"},{"location":"core-services/container-orchestration-provider-apis/#containerorchestrationservice","text":"The ContainerOrchestrationService is used to directly communicate with the running container engine. It exposes methods for listing, creating, and stopping containers. This class utilizes an instantiated ContainerConfiguration object as a parameter for container creation.","title":"ContainerOrchestrationService"},{"location":"core-services/container-orchestration-provider-apis/#containerconfiguration","text":"The ContainerConfiguration class, allows you to define a container to create. Using the embedded builder class, one can define many container-related parameters such as name, image, ports and volume mounts.","title":"ContainerConfiguration"},{"location":"core-services/container-orchestration-provider-apis/#containerinstancedescriptor","text":"The ContainerInstanceDescriptor class is used to describe a container that has already been created. This class contains runtime information such as the ID of the container.","title":"ContainerInstanceDescriptor"},{"location":"core-services/container-orchestration-provider-apis/#containerstate","text":"The ContainerState is a class that exposes an enum of container states tracked by the framework.","title":"ContainerState"},{"location":"core-services/container-orchestration-provider-apis/#passwordregistrycredentials","text":"The PasswordRegistryCredentials class stores password credentials when provisioning a container to pull from an alternative password-protected registry.","title":"PasswordRegistryCredentials"},{"location":"core-services/container-orchestration-provider-apis/#passwordregistrycredentials_1","text":"The PasswordRegistryCredentials class stores password credentials when provisioning a container to pull from an alternative password-protected registry. Note The Container Orchestration Provider exports an MQTT-Namespace API. This API can be used to manage containers via MQTT requests from external applications. Please visit the Remote Gateway Inventory via MQTT documentation for more information.","title":"PasswordRegistryCredentials"},{"location":"core-services/container-orchestration-provider-authenticated-registries/","text":"Container Orchestration Provider Authenticated Registries The Container Orchestrator provider allows the user to pull images from private and password-protected registries. The following document will provide examples of how to connect to some popular registries. Note These guides make the following two assumptions. That you have already configured the Container Orchestrator and have a container instance already created. Please see the usage doc, to learn the basics of the orchestrator. That the image you are trying to pull supports the architecture of the gateway. Private Docker-Hub Registries Preparation: have a Docker Hub account (its credentials), and a private image ready to pull. Procedure: Populate the image name field. The username containing the private image must be placed before the image name separated by a forward slash. This is demonstrated below: **Image Name: ** / for example eclipse/kura . Populate the credential fields: Authentication Registry URL: This field should be left blank. Authentication Username: Your Docker Hub username. Password: Your Docker Hub password. Amazon Web Services - Elastic Container Registries (AWS-ECR) Preparation: Have access to an Amazon ECR instance. Have the AWS-CLI tool installed and appropriately configured on your computer. Have access to your AWS ECR web console. Procedure: Sign in to your amazon web console, navigate to ECR and identify which container you will like to pull onto the gateway. Copy the URI of the container. This URI will reveal the information required for the following steps. Here is how to decode the URI .dkr.ecr..amazonaws.com//: . Generating an AWS-ECR access password. Open a terminal window on the machine with aws-cli installed and enter the following command aws ecr get-login-password --region . Your ECR region can be found by inspecting the container URI string copied in the previous step. This command will return a long string which will be used as the repo password in the gateway. Populating information on the gateway. **Image Name: ** enter the full URI without the tag. .dkr.ecr..amazonaws.com// Image Tag: enter only the image tag found at the end of the URI Authentication Registry URL: Paste only the part of the URI before the image name .dkr.ecr..amazonaws.com// Authentication Username: will be AWS Password: will be the string created in step two. A fully configured container set to pull AWS will look like the following.","title":"Container Orchestration Provider Authenticated Registries"},{"location":"core-services/container-orchestration-provider-authenticated-registries/#container-orchestration-provider-authenticated-registries","text":"The Container Orchestrator provider allows the user to pull images from private and password-protected registries. The following document will provide examples of how to connect to some popular registries. Note These guides make the following two assumptions. That you have already configured the Container Orchestrator and have a container instance already created. Please see the usage doc, to learn the basics of the orchestrator. That the image you are trying to pull supports the architecture of the gateway.","title":"Container Orchestration Provider Authenticated Registries"},{"location":"core-services/container-orchestration-provider-authenticated-registries/#private-docker-hub-registries","text":"","title":"Private Docker-Hub Registries"},{"location":"core-services/container-orchestration-provider-authenticated-registries/#preparation","text":"have a Docker Hub account (its credentials), and a private image ready to pull.","title":"Preparation:"},{"location":"core-services/container-orchestration-provider-authenticated-registries/#procedure","text":"Populate the image name field. The username containing the private image must be placed before the image name separated by a forward slash. This is demonstrated below: **Image Name: ** / for example eclipse/kura . Populate the credential fields: Authentication Registry URL: This field should be left blank. Authentication Username: Your Docker Hub username. Password: Your Docker Hub password.","title":"Procedure:"},{"location":"core-services/container-orchestration-provider-authenticated-registries/#amazon-web-services-elastic-container-registries-aws-ecr","text":"","title":"Amazon Web Services - Elastic Container Registries (AWS-ECR)"},{"location":"core-services/container-orchestration-provider-authenticated-registries/#preparation_1","text":"Have access to an Amazon ECR instance. Have the AWS-CLI tool installed and appropriately configured on your computer. Have access to your AWS ECR web console.","title":"Preparation:"},{"location":"core-services/container-orchestration-provider-authenticated-registries/#procedure_1","text":"Sign in to your amazon web console, navigate to ECR and identify which container you will like to pull onto the gateway. Copy the URI of the container. This URI will reveal the information required for the following steps. Here is how to decode the URI .dkr.ecr..amazonaws.com//: . Generating an AWS-ECR access password. Open a terminal window on the machine with aws-cli installed and enter the following command aws ecr get-login-password --region . Your ECR region can be found by inspecting the container URI string copied in the previous step. This command will return a long string which will be used as the repo password in the gateway. Populating information on the gateway. **Image Name: ** enter the full URI without the tag. .dkr.ecr..amazonaws.com// Image Tag: enter only the image tag found at the end of the URI Authentication Registry URL: Paste only the part of the URI before the image name .dkr.ecr..amazonaws.com// Authentication Username: will be AWS Password: will be the string created in step two. A fully configured container set to pull AWS will look like the following.","title":"Procedure:"},{"location":"core-services/container-orchestration-provider-usage/","text":"Container Orchestration Provider Usage Before Starting For this bundle to function appropriately, the gateway must have a supported container engine installed and running. Currently, the only officially supported engine is Docker. Starting the Service To use this service select the ContainerOrchestrationService option located in the Services area. The ContainerOrchestrationService provides the following parameters: Enabled --activates the service when set to true Container Engine Host URL --provides a string that tells the service where to find the container engine (best left to the default value). Creating your first container. To create a container, select the + icon (Create a new component) under services . A popup dialogue box will appear. In the field Factory select org.eclipse.kura.container.provider.ContainerInstance from the drop-down. Then, use the Name field to specify a name for the container. Note The name specified in the 'Name' field will also be the name of the container when it is spun up by the orchestrator. After pressing submit, a new component will be added under the services tab, with the name that was selected in the dialogue. Select this component to finish configuring the container. Configuring the container To begin configuring the container, look under Services and select the item which has the name set in the previous step. Containers may be configured using the following fields: Enabled - When true, the service will create the defined container. When false the API will not create the container or will destroy the container if already running. Image Name - Describes the image that will be used to create the container. Remember to ensure that the selected image supports the architecture of the host machine, or else the container will not be able to start. Image Tag - Describes the version of the container image that will be used to create the container. Authentication Registry URL - URL for an alternative registry to pull images from. (If the field is left blank, credentials will be applied to Docker-Hub). Please see the Authenticated Registries document for more information about connecting to different popular registries. Authentication Username - Describes the username to access the container registry entered above. Password - Describes the password to access the alternative container registry. Image Download Retries - Describes the number of retries the framework will attempt to pull the image before giving up. Image Download Retry Interval - Describes the amount of time the framework will wait before attempting to pull the image again. Image Download Timeout - Describes the amount of time the framework will let the image download before timeout. Internal Ports - This field accepts a comma-separated list of ports that will be internally exposed on the spun-up container. In this field, you can also specify which protocol to run at the port by appending a port with a colon and typing in the name of the network protocol. Example: 80, 443:tcp, 8080:udp . External Ports - This field accepts a comma-separated list of ports that will be externally exposed on the host machine. Privileged Mode - This flag if enabled will give the container root capabilities to all devices on the host system. Please be aware that setting this flag can be dangerous, and must only be used in exceptional situations. Environment Variables (optional) - This field accepts a comma-separated list of environment variables, which will be set inside the container when spun up. Entrypoint Override (optional) - This field accepts a comma-separated list which is used to override the command used to start a container. Example: ./test.sh,-v,-d,--human-readable . Memory (optional) - This field allows the configuration of the maximum amount of memory the container can use in bytes. The value is a positive integer, optionally followed by a suffix of b, k, m, g, to indicate bytes, kilobytes, megabytes, or gigabytes. The minimum and default values depends by the native container orchestrator. If left empty, the memory assigned to the container will be set to a default value. CPUs (optional) - This value specifies how many CPUs a container can use. Decimal values are allowed, so if set to 1.5, the container will use at most one and a half cpu resource. GPUs (optional) - This field configures how many Nvidia GPUs a container can use. Allowed values are 'all' or an integer number. If there's no Nvidia GPU installed, leave it empty. The Nvidia Container Toolkit must be installed on the system to correctly configure the service, otherwise the container will not start. Volume Mount (optional) - This field accepts a comma-separated list of system-to-container file mounts. This allows for the container to access files on the host machine. Peripheral Device (optional) - This field accepts a comma-separated list of device paths. This parameter allows devices to be passed through from the host to the container. Networking Mode (optional) - Use this field to specify what networking mode the container will use. Possible Drivers include: bridge, none, container:{container id}, host. Please note that this field is case-sensitive. This field can also be used to connect to any of the networks listed by the cli command docker network ls . Logger Type - This field provides a drop-down selection of supported container logging drivers. Logger Parameters (optional) - This field accepts a comma-separated list of logging parameters. More information can be found in the container-engine logger documentation, for instance here . Restart Container On Failure - A boolean that tells the container engine to automatically restart the container when it has failed or shut down. After specifying container parameters, ensure to set Enabled to true and press Apply . The container engine will then pull the respective image, spin up and start the container. If the gateway or the framework is power cycled, and the container and Container Orchestration Service are set to enabled , the framework will automatically start the container again upon startup. Stopping the container Warning Stopping a container will delete it in an irreversible way. Please be sure to only use stateless containers and/or save their data in external volumes. To stop the container without deleting the component, set the Enabled field to false , and then press Apply . This will delete the running container, but leave this component available for running the container again in the future. If you want to completely remove the container and component, press the Delete button to the top right of the screen, and press Yes on the confirmation dialogue. Container Management Dashboard The Container Orchestration service also provides the user with an intuitive container dashboard. This dashboard shows all containers running on a gateway, including containers created with the framework and those created manually through the command-line interface. To utilize this dashboard the org.eclipse.container.orchestration.provider (ContainerOrchestrationService) must be enabled, and the dashboard can be opened by navigating to Device > Containers.","title":"Container Orchestration Provider Usage"},{"location":"core-services/container-orchestration-provider-usage/#container-orchestration-provider-usage","text":"","title":"Container Orchestration Provider Usage"},{"location":"core-services/container-orchestration-provider-usage/#before-starting","text":"For this bundle to function appropriately, the gateway must have a supported container engine installed and running. Currently, the only officially supported engine is Docker.","title":"Before Starting"},{"location":"core-services/container-orchestration-provider-usage/#starting-the-service","text":"To use this service select the ContainerOrchestrationService option located in the Services area. The ContainerOrchestrationService provides the following parameters: Enabled --activates the service when set to true Container Engine Host URL --provides a string that tells the service where to find the container engine (best left to the default value).","title":"Starting the Service"},{"location":"core-services/container-orchestration-provider-usage/#creating-your-first-container","text":"To create a container, select the + icon (Create a new component) under services . A popup dialogue box will appear. In the field Factory select org.eclipse.kura.container.provider.ContainerInstance from the drop-down. Then, use the Name field to specify a name for the container. Note The name specified in the 'Name' field will also be the name of the container when it is spun up by the orchestrator. After pressing submit, a new component will be added under the services tab, with the name that was selected in the dialogue. Select this component to finish configuring the container.","title":"Creating your first container."},{"location":"core-services/container-orchestration-provider-usage/#configuring-the-container","text":"To begin configuring the container, look under Services and select the item which has the name set in the previous step. Containers may be configured using the following fields: Enabled - When true, the service will create the defined container. When false the API will not create the container or will destroy the container if already running. Image Name - Describes the image that will be used to create the container. Remember to ensure that the selected image supports the architecture of the host machine, or else the container will not be able to start. Image Tag - Describes the version of the container image that will be used to create the container. Authentication Registry URL - URL for an alternative registry to pull images from. (If the field is left blank, credentials will be applied to Docker-Hub). Please see the Authenticated Registries document for more information about connecting to different popular registries. Authentication Username - Describes the username to access the container registry entered above. Password - Describes the password to access the alternative container registry. Image Download Retries - Describes the number of retries the framework will attempt to pull the image before giving up. Image Download Retry Interval - Describes the amount of time the framework will wait before attempting to pull the image again. Image Download Timeout - Describes the amount of time the framework will let the image download before timeout. Internal Ports - This field accepts a comma-separated list of ports that will be internally exposed on the spun-up container. In this field, you can also specify which protocol to run at the port by appending a port with a colon and typing in the name of the network protocol. Example: 80, 443:tcp, 8080:udp . External Ports - This field accepts a comma-separated list of ports that will be externally exposed on the host machine. Privileged Mode - This flag if enabled will give the container root capabilities to all devices on the host system. Please be aware that setting this flag can be dangerous, and must only be used in exceptional situations. Environment Variables (optional) - This field accepts a comma-separated list of environment variables, which will be set inside the container when spun up. Entrypoint Override (optional) - This field accepts a comma-separated list which is used to override the command used to start a container. Example: ./test.sh,-v,-d,--human-readable . Memory (optional) - This field allows the configuration of the maximum amount of memory the container can use in bytes. The value is a positive integer, optionally followed by a suffix of b, k, m, g, to indicate bytes, kilobytes, megabytes, or gigabytes. The minimum and default values depends by the native container orchestrator. If left empty, the memory assigned to the container will be set to a default value. CPUs (optional) - This value specifies how many CPUs a container can use. Decimal values are allowed, so if set to 1.5, the container will use at most one and a half cpu resource. GPUs (optional) - This field configures how many Nvidia GPUs a container can use. Allowed values are 'all' or an integer number. If there's no Nvidia GPU installed, leave it empty. The Nvidia Container Toolkit must be installed on the system to correctly configure the service, otherwise the container will not start. Volume Mount (optional) - This field accepts a comma-separated list of system-to-container file mounts. This allows for the container to access files on the host machine. Peripheral Device (optional) - This field accepts a comma-separated list of device paths. This parameter allows devices to be passed through from the host to the container. Networking Mode (optional) - Use this field to specify what networking mode the container will use. Possible Drivers include: bridge, none, container:{container id}, host. Please note that this field is case-sensitive. This field can also be used to connect to any of the networks listed by the cli command docker network ls . Logger Type - This field provides a drop-down selection of supported container logging drivers. Logger Parameters (optional) - This field accepts a comma-separated list of logging parameters. More information can be found in the container-engine logger documentation, for instance here . Restart Container On Failure - A boolean that tells the container engine to automatically restart the container when it has failed or shut down. After specifying container parameters, ensure to set Enabled to true and press Apply . The container engine will then pull the respective image, spin up and start the container. If the gateway or the framework is power cycled, and the container and Container Orchestration Service are set to enabled , the framework will automatically start the container again upon startup.","title":"Configuring the container"},{"location":"core-services/container-orchestration-provider-usage/#stopping-the-container","text":"Warning Stopping a container will delete it in an irreversible way. Please be sure to only use stateless containers and/or save their data in external volumes. To stop the container without deleting the component, set the Enabled field to false , and then press Apply . This will delete the running container, but leave this component available for running the container again in the future. If you want to completely remove the container and component, press the Delete button to the top right of the screen, and press Yes on the confirmation dialogue.","title":"Stopping the container"},{"location":"core-services/container-orchestration-provider-usage/#container-management-dashboard","text":"The Container Orchestration service also provides the user with an intuitive container dashboard. This dashboard shows all containers running on a gateway, including containers created with the framework and those created manually through the command-line interface. To utilize this dashboard the org.eclipse.container.orchestration.provider (ContainerOrchestrationService) must be enabled, and the dashboard can be opened by navigating to Device > Containers.","title":"Container Management Dashboard"},{"location":"core-services/container-orchestration-provider/","text":"Container Orchestration Provider The Container Orchestration Provider allows Kura to manage Docker. With this tool, you can arbitrarily pull and deploy containerized software packages and run them on your gateway. This Service allows the user to create, configure, start, and stop containers all from the browser. The bundle will also restart containers if the gateway is restarted. The feature is composed of two bundles, one that exposes APIs for container management and one that implements those APIs. This API is exposed so that you can leverage it to implement containerization in your own Kura plugins.","title":"Container Orchestration Provider"},{"location":"core-services/container-orchestration-provider/#container-orchestration-provider","text":"The Container Orchestration Provider allows Kura to manage Docker. With this tool, you can arbitrarily pull and deploy containerized software packages and run them on your gateway. This Service allows the user to create, configure, start, and stop containers all from the browser. The bundle will also restart containers if the gateway is restarted. The feature is composed of two bundles, one that exposes APIs for container management and one that implements those APIs. This API is exposed so that you can leverage it to implement containerization in your own Kura plugins.","title":"Container Orchestration Provider"},{"location":"core-services/deployment-service/","text":"Deployment Service The Deployment Service allows to download files to the gateway and to perform actions on them. In the configuration tab it is possible to specify which is the directory that has to be used to store the downloaded files and the list of actions declared as deployment hooks that will be invoked when a corresponding metric is received with the download request. The configuration requires to specify two parameters: downloads.directory - The directory to be used to store the downloaded files; deployment.hook.associations - The list of DeploymentHook associations in the form = , where is the Kura Service Pid of a DeploymentHook instance and is the value of the request.type metric received with the request.","title":"Deployment Service"},{"location":"core-services/deployment-service/#deployment-service","text":"The Deployment Service allows to download files to the gateway and to perform actions on them. In the configuration tab it is possible to specify which is the directory that has to be used to store the downloaded files and the list of actions declared as deployment hooks that will be invoked when a corresponding metric is received with the download request. The configuration requires to specify two parameters: downloads.directory - The directory to be used to store the downloaded files; deployment.hook.associations - The list of DeploymentHook associations in the form = , where is the Kura Service Pid of a DeploymentHook instance and is the value of the request.type metric received with the request.","title":"Deployment Service"},{"location":"core-services/device-configuration-changes/","text":"Device Configuration Changes Kura can detect changes to the components and publish them using a selected Cloud Publisher. There are two main components that enable this: org.eclipse.kura.configuration.change.manager , and org.eclipse.kura.event.publisher The org.eclipse.kura.configuration.change.manager is responsible for detecting changes to any of the configurations currently running on the system and to publish a notification to a user-defined cloud publisher. By default, the org.eclipse.kura.event.publisher is used. Configuration Change Manager The configuration change manager allows to collection of the PIDs of the components that have changed in the system. The configurable properties of this component are: Enable : whether to enable or not this component. CloudPublisher Target Filter : allows to specify the cloud publisher to use for sending the produced messages. Notification send delay (sec) : allows to stack the changed PIDs for a given time before sending. In other words, it allows to group together sequences of PIDs that are changed in that time frame. This is to prevent message flooding at reboot or rollback. The collected PIDs are sent to the Cloud Publisher as a KuraMessage with a payload body in JSON format. The timestamp of the KuraMessage is set to the last detected configuration change event. An example of message body is: [ { \u201cpid\u201d : \u201corg.eclipse.kura.clock.ClockService\u201d }, { \u201cpid\u201d : \u201corg.eclipse.kura.log. f ilesys te m.provider.Filesys te mLogProvider\u201d } ] In the example above, a ClockService update triggered the delay timer, which was then reset by a configuration update on the FilesystemLogProvider . Afterward, no configuration updates reset the timer so the message containing the two PIDs was sent after expiration. Event Publisher By default, the org.eclipse.kura.event.publisher used by the configuration change manager does the actual publishing on a user-defined topic of the form: $EVT/#account_id/#client_id/CONF/V1/CHANGE This topic is adjusted for integration with EC, but the $EVT and the CONF/V1/CHANGE parts can be customized according to user needs by tweaking the Topic prefix and Topic properties. The #account_id and #client_id fields are substituted at runtime with the account name and client ID at the Data Transport Service layer of the associated Cloud Connection. The Qos , Retain , and Priority properties are the usual ones defined in the standard Cloud Publisher.","title":"Device Configuration Changes"},{"location":"core-services/device-configuration-changes/#device-configuration-changes","text":"Kura can detect changes to the components and publish them using a selected Cloud Publisher. There are two main components that enable this: org.eclipse.kura.configuration.change.manager , and org.eclipse.kura.event.publisher The org.eclipse.kura.configuration.change.manager is responsible for detecting changes to any of the configurations currently running on the system and to publish a notification to a user-defined cloud publisher. By default, the org.eclipse.kura.event.publisher is used.","title":"Device Configuration Changes"},{"location":"core-services/device-configuration-changes/#configuration-change-manager","text":"The configuration change manager allows to collection of the PIDs of the components that have changed in the system. The configurable properties of this component are: Enable : whether to enable or not this component. CloudPublisher Target Filter : allows to specify the cloud publisher to use for sending the produced messages. Notification send delay (sec) : allows to stack the changed PIDs for a given time before sending. In other words, it allows to group together sequences of PIDs that are changed in that time frame. This is to prevent message flooding at reboot or rollback. The collected PIDs are sent to the Cloud Publisher as a KuraMessage with a payload body in JSON format. The timestamp of the KuraMessage is set to the last detected configuration change event. An example of message body is: [ { \u201cpid\u201d : \u201corg.eclipse.kura.clock.ClockService\u201d }, { \u201cpid\u201d : \u201corg.eclipse.kura.log. f ilesys te m.provider.Filesys te mLogProvider\u201d } ] In the example above, a ClockService update triggered the delay timer, which was then reset by a configuration update on the FilesystemLogProvider . Afterward, no configuration updates reset the timer so the message containing the two PIDs was sent after expiration.","title":"Configuration Change Manager"},{"location":"core-services/device-configuration-changes/#event-publisher","text":"By default, the org.eclipse.kura.event.publisher used by the configuration change manager does the actual publishing on a user-defined topic of the form: $EVT/#account_id/#client_id/CONF/V1/CHANGE This topic is adjusted for integration with EC, but the $EVT and the CONF/V1/CHANGE parts can be customized according to user needs by tweaking the Topic prefix and Topic properties. The #account_id and #client_id fields are substituted at runtime with the account name and client ID at the Data Transport Service layer of the associated Cloud Connection. The Qos , Retain , and Priority properties are the usual ones defined in the standard Cloud Publisher.","title":"Event Publisher"},{"location":"core-services/h2db-service/","text":"H2Db Service Kura integrates a Java SQL database named H2 . The main features of this SQL Database are: Very fast, open source, JDBC API Embedded and server modes; in-memory databases Browser-based Console application Small footprint Supported Features Kura supports the following H2 database features: Persistence modes : The H2 implementation currently supports in-memory and file-based database instances. See the Persistence Modes section for more details. Multiple database instances : It is possible to create and configure multiple database instances from the Kura Administration UI, these instances can be selectively consumed by applications. A default database instance is created automatically. TCP Server : The current implementation allows external processes to access the database instances managed by Kura using TCP. This enables the integration of external applications that can share data with Kura components using the database. Web-based console : It is possible to start the H2 Web console directly from the Kura Administration UI. The console can be used to inspect the database contents and perform arbitrary queries for debug purposes. Basic credential management : The current implementation allows to change the password of the admin DB user from the Kura Administration UI. This allows the access restriction to the existing database instances. By default, the DataService in Kura uses the H2 database to persist the messages. Limitations Private in-memory instances : Only named in-memory instances are supported (e.g. jdbc:h2:mem: , where is not the empty string), private instances represented by the jdbc:h2:mem: URL are currently not supported. Remote connections : The current implementation only supports embedded database instances. Connecting to remote instances using the jdbc:h2:tcp:* and jdbc:h2:ssl:* connector URLs is not supported. Note The new DbWireRecordFilter and DbWireRecordStore Wire components have been added. These components provide the same functionalities offered by the old H2DbWireRecordFilter and H2DbWireRecordStore components, but they can be used for connectiong to a generic relational database (i.e. H2DB, MySQL or MariaDB). The legacy components will continue to be available in order to keep backward compatibility, but will be deprecated since Kura 5.2.0 and should not be used for new installations. Usage Creating a new H2 database instance To create a new H2 database instance, use the following procedure: Open the Administrative UI and press the + button in the side menu, under the Services section. A pop-up dialog should appear. Select org.eclipse.kura.core.db.H2DbService from the Factory drop-down list, enter an arbitrary name for the new instance and click Apply . An entry for the newly created instance should appear in the side menu under Services , click on it to review its configuration. It is not possible to create different DB instances that manage the same DB URL. When creating a new instance please make sure that the URL specified in the field db.connector.url is not managed by another instance. Configuration Parameters The H2DbService provides the following configuration parameters: Connector URL : JDBC connector URL of the database instance. Passing the USER and PASSWORD parameters in the connector URL is not supported, these paramters will be ignored if present. Please use the db.user and db.password fields to provide the credentials. Warning If the database is created in persisted mode, please make sure that the Linux user running Eclipse Kura has the permissions required to create the database file. If the permissions are not ok, Eclipse Kura may be able to create the database (by default it runs with the CAP_DAC_OVERRIDE capability) but it may not be able to perform the periodic defragmentation process, this may cause the database file size to grow expecially if the write rate is high. Executing the following commands as root can be useful to detect potential issues, replace database_parent_directory with the parent directory of the database file and kura_linux_user with the Linux user that is executing Eclipse Kura (e.g. kurad): export TARGET=\"$(readlink -f database_parent_directory)\" export KURA_USER=\"kura_linux_user\" sudo -u \"${KURA_USER}\" sh -c \"touch '${TARGET}/.testfile' && rm '${TARGET}/.testfile'\" If command fails it may be necessary to change the database directory or adjust the permissions. User : Specifies the user for the database connection. Furthermore Password : Specifies the password. The default password is the empty string. Checkpoint interval (seconds) : H2DbService instances support running periodic checkpoints to ensure data consistency. This parameter specifies the interval in seconds between two successive checkpoints. This setting has no effect for in-memory database instances. Defrag interval (minutes) : H2DbService instances support running periodic defragmentation (compaction). This parameter specifies the interval in minutes between two successive checkpoints, set to zero to disable. This setting has no effect for in-memory database instances. Existing database connections will be closed during the defragmentation process and need to be reopened by the applications. Connection pool max size : The H2DbService manages connections using a connection pool. This parameter defines the maximum number of connections for the pool Selecting a database instance for existing components A database instance is identified by its Kura service PID . The PID for the default instance is org.eclipse.kura.db.H2DbService while the PID for instances created using the Web UI is the string entered in the Name field at step 2 of the previous section. The built-in components that use database functionalities allow to specify which instance to use in their configuration. These components are the DataService component of the cloud stack, the DbWireRecordFilter and DbWireRecordStore wire components. The configuration of each component contains a property that allows to specify the service PID of the desired instance. Usage through Wires It is possible to store and extract Wire Records into/from a H2 database instance using the Wire Record Store and Wire Record Query wire components. When a Wire Record is received by a Wire Record Store attached to a H2 based database instance, the data will be stored in a table whose name is the current value of the Record Collection Name configuration parameter of the Wire Component. Each property contained in a Wire Record will be appended to a column with the same name as the property key. A new column will be created if it doesn't already exists. Note Storing wire record properties with the FLOAT data type using the Wire Record Store is not recommended since the type information will be lost. Values inserted as FLOAT using the Wire Record Store will be retrieved as DOUBLE using the Wire Record Query component. Warning It is not recommended to store Wire Records having properties with the same key and different value type. If the value type changes, the target column will be dropped and recreated with the type derived from the last received record. All existing data in the target column will be lost. The purpose of this is to allow changing the type of a column with a Wire Graph configuration update. Enabling the TCP Server Danger This feature is intended to be used only for debugging/development purposes . The server created by H2 is not running on a secure protocol . Only enable the server for a limited time and make sure to properly secure the firewall ports on which it is running. The TCP server can be used by creating a H2DbServer instance: Open the Web UI and press the + button in the side menu, under the Services section. A pop-up dialog should appear. Select org.eclipse.kura.core.db.H2DbServer from the Factory drop-down\u200b list, enter an arbitrary name for the new instance and click Apply. Clicking on the name of the new server instance on the left side of the Web UI\u200b. The configuration of the server component will appear. Set the db.server.type field to TCP . Review the server options under db.server.commandline , check the official documentation for more information about the available options. Set the db.server.enabled to true . The server, with the default configuration, will be listening on port 9123. Tip Make sure to review the firewall configuration in order to ensure that the server is reachable from an external process. Enabling the Web Console Danger This feature is intended to be used only for debugging/development purposes . The server created by H2 is not running on a secure protocol . Only enable the server for a limited time and make sure to properly secure the firewall ports on which it is running. In order to enable the H2 Web console, proceed as follows: Create a new H2DbServer instance. Set the db.server.type field to WEB . Enter appropriate parameters for the Web server in the db.server.commandline field. An example of valid settings can be: -webPort 9123 -webAllowOthers -ifExists -webExternalNames . Set the db.server.enabled to true . The server is now listening on the specified port. Tip Make sure to review the firewall configuration in order to ensure that the server is reachable from an external process. Use a browser to access the console. Open the http:// : URL, where is the IP address of the gateway and is the port specified at step 3. Enter the DB URL as specified in the Kura configuration in the JDBC URL field and the credentials. Click on Connect , you should be able to access the console. Change the Database Password To change the database password the System Administrator needs to: Open the configuration of the desired database instance in the Web UI. Enter the new password in the db.password field. Click Apply . Warn If the H2DbServer instance fails to open a database, it will delete and recreate all database files. This behavior\u200b is aimed at preventing potential issues caused by incorrect credentials in the configuration snapshots. It is highly recommended to perform a backup of an existing database before trying to open it using a H2DbService instance and before changing the password. Persistence Modes The H2 database supports several persistence modes. In Memory An in-memory database instance can be created using the following URL structure: jdbc:h2:mem: , where is a non-empty string that represents the database name. This configuration is suggested for database instances that are frequently updated. Examples: jdbc:h2:mem:kuradb jdbc:h2:mem:mydb The default database instance is in-memory by default and uses the jdbc:h2:mem:kuradb URL. Persistent A persistent database instance can be created using the jdbc:h2:file: , where is a non-empty string that represents the database path. If no URL parameters are supplied the database will enable the transaction log by default. The transaction log is used to restore the database to a consistent state after a crash or power failure. This provides good protection against data losses but causes a lot of writes to the storage device, reducing both performance and the lifetime of flash-based storage devices. Examples: - jdbc:h2:file:/opt/db/mydb Make sure to use absolute paths in the DB URL since H2 does not support DB paths relative to the working directory.","title":"H2Db Service"},{"location":"core-services/h2db-service/#h2db-service","text":"Kura integrates a Java SQL database named H2 . The main features of this SQL Database are: Very fast, open source, JDBC API Embedded and server modes; in-memory databases Browser-based Console application Small footprint","title":"H2Db Service"},{"location":"core-services/h2db-service/#supported-features","text":"Kura supports the following H2 database features: Persistence modes : The H2 implementation currently supports in-memory and file-based database instances. See the Persistence Modes section for more details. Multiple database instances : It is possible to create and configure multiple database instances from the Kura Administration UI, these instances can be selectively consumed by applications. A default database instance is created automatically. TCP Server : The current implementation allows external processes to access the database instances managed by Kura using TCP. This enables the integration of external applications that can share data with Kura components using the database. Web-based console : It is possible to start the H2 Web console directly from the Kura Administration UI. The console can be used to inspect the database contents and perform arbitrary queries for debug purposes. Basic credential management : The current implementation allows to change the password of the admin DB user from the Kura Administration UI. This allows the access restriction to the existing database instances. By default, the DataService in Kura uses the H2 database to persist the messages.","title":"Supported Features"},{"location":"core-services/h2db-service/#limitations","text":"Private in-memory instances : Only named in-memory instances are supported (e.g. jdbc:h2:mem: , where is not the empty string), private instances represented by the jdbc:h2:mem: URL are currently not supported. Remote connections : The current implementation only supports embedded database instances. Connecting to remote instances using the jdbc:h2:tcp:* and jdbc:h2:ssl:* connector URLs is not supported. Note The new DbWireRecordFilter and DbWireRecordStore Wire components have been added. These components provide the same functionalities offered by the old H2DbWireRecordFilter and H2DbWireRecordStore components, but they can be used for connectiong to a generic relational database (i.e. H2DB, MySQL or MariaDB). The legacy components will continue to be available in order to keep backward compatibility, but will be deprecated since Kura 5.2.0 and should not be used for new installations.","title":"Limitations"},{"location":"core-services/h2db-service/#usage","text":"","title":"Usage"},{"location":"core-services/h2db-service/#creating-a-new-h2-database-instance","text":"To create a new H2 database instance, use the following procedure: Open the Administrative UI and press the + button in the side menu, under the Services section. A pop-up dialog should appear. Select org.eclipse.kura.core.db.H2DbService from the Factory drop-down list, enter an arbitrary name for the new instance and click Apply . An entry for the newly created instance should appear in the side menu under Services , click on it to review its configuration. It is not possible to create different DB instances that manage the same DB URL. When creating a new instance please make sure that the URL specified in the field db.connector.url is not managed by another instance.","title":"Creating a new H2 database instance"},{"location":"core-services/h2db-service/#configuration-parameters","text":"The H2DbService provides the following configuration parameters: Connector URL : JDBC connector URL of the database instance. Passing the USER and PASSWORD parameters in the connector URL is not supported, these paramters will be ignored if present. Please use the db.user and db.password fields to provide the credentials. Warning If the database is created in persisted mode, please make sure that the Linux user running Eclipse Kura has the permissions required to create the database file. If the permissions are not ok, Eclipse Kura may be able to create the database (by default it runs with the CAP_DAC_OVERRIDE capability) but it may not be able to perform the periodic defragmentation process, this may cause the database file size to grow expecially if the write rate is high. Executing the following commands as root can be useful to detect potential issues, replace database_parent_directory with the parent directory of the database file and kura_linux_user with the Linux user that is executing Eclipse Kura (e.g. kurad): export TARGET=\"$(readlink -f database_parent_directory)\" export KURA_USER=\"kura_linux_user\" sudo -u \"${KURA_USER}\" sh -c \"touch '${TARGET}/.testfile' && rm '${TARGET}/.testfile'\" If command fails it may be necessary to change the database directory or adjust the permissions. User : Specifies the user for the database connection. Furthermore Password : Specifies the password. The default password is the empty string. Checkpoint interval (seconds) : H2DbService instances support running periodic checkpoints to ensure data consistency. This parameter specifies the interval in seconds between two successive checkpoints. This setting has no effect for in-memory database instances. Defrag interval (minutes) : H2DbService instances support running periodic defragmentation (compaction). This parameter specifies the interval in minutes between two successive checkpoints, set to zero to disable. This setting has no effect for in-memory database instances. Existing database connections will be closed during the defragmentation process and need to be reopened by the applications. Connection pool max size : The H2DbService manages connections using a connection pool. This parameter defines the maximum number of connections for the pool","title":"Configuration Parameters"},{"location":"core-services/h2db-service/#selecting-a-database-instance-for-existing-components","text":"A database instance is identified by its Kura service PID . The PID for the default instance is org.eclipse.kura.db.H2DbService while the PID for instances created using the Web UI is the string entered in the Name field at step 2 of the previous section. The built-in components that use database functionalities allow to specify which instance to use in their configuration. These components are the DataService component of the cloud stack, the DbWireRecordFilter and DbWireRecordStore wire components. The configuration of each component contains a property that allows to specify the service PID of the desired instance.","title":"Selecting a database instance for existing components"},{"location":"core-services/h2db-service/#usage-through-wires","text":"It is possible to store and extract Wire Records into/from a H2 database instance using the Wire Record Store and Wire Record Query wire components. When a Wire Record is received by a Wire Record Store attached to a H2 based database instance, the data will be stored in a table whose name is the current value of the Record Collection Name configuration parameter of the Wire Component. Each property contained in a Wire Record will be appended to a column with the same name as the property key. A new column will be created if it doesn't already exists. Note Storing wire record properties with the FLOAT data type using the Wire Record Store is not recommended since the type information will be lost. Values inserted as FLOAT using the Wire Record Store will be retrieved as DOUBLE using the Wire Record Query component. Warning It is not recommended to store Wire Records having properties with the same key and different value type. If the value type changes, the target column will be dropped and recreated with the type derived from the last received record. All existing data in the target column will be lost. The purpose of this is to allow changing the type of a column with a Wire Graph configuration update.","title":"Usage through Wires"},{"location":"core-services/h2db-service/#enabling-the-tcp-server","text":"Danger This feature is intended to be used only for debugging/development purposes . The server created by H2 is not running on a secure protocol . Only enable the server for a limited time and make sure to properly secure the firewall ports on which it is running. The TCP server can be used by creating a H2DbServer instance: Open the Web UI and press the + button in the side menu, under the Services section. A pop-up dialog should appear. Select org.eclipse.kura.core.db.H2DbServer from the Factory drop-down\u200b list, enter an arbitrary name for the new instance and click Apply. Clicking on the name of the new server instance on the left side of the Web UI\u200b. The configuration of the server component will appear. Set the db.server.type field to TCP . Review the server options under db.server.commandline , check the official documentation for more information about the available options. Set the db.server.enabled to true . The server, with the default configuration, will be listening on port 9123. Tip Make sure to review the firewall configuration in order to ensure that the server is reachable from an external process.","title":"Enabling the TCP Server"},{"location":"core-services/h2db-service/#enabling-the-web-console","text":"Danger This feature is intended to be used only for debugging/development purposes . The server created by H2 is not running on a secure protocol . Only enable the server for a limited time and make sure to properly secure the firewall ports on which it is running. In order to enable the H2 Web console, proceed as follows: Create a new H2DbServer instance. Set the db.server.type field to WEB . Enter appropriate parameters for the Web server in the db.server.commandline field. An example of valid settings can be: -webPort 9123 -webAllowOthers -ifExists -webExternalNames . Set the db.server.enabled to true . The server is now listening on the specified port. Tip Make sure to review the firewall configuration in order to ensure that the server is reachable from an external process. Use a browser to access the console. Open the http:// : URL, where is the IP address of the gateway and is the port specified at step 3. Enter the DB URL as specified in the Kura configuration in the JDBC URL field and the credentials. Click on Connect , you should be able to access the console.","title":"Enabling the Web Console"},{"location":"core-services/h2db-service/#change-the-database-password","text":"To change the database password the System Administrator needs to: Open the configuration of the desired database instance in the Web UI. Enter the new password in the db.password field. Click Apply . Warn If the H2DbServer instance fails to open a database, it will delete and recreate all database files. This behavior\u200b is aimed at preventing potential issues caused by incorrect credentials in the configuration snapshots. It is highly recommended to perform a backup of an existing database before trying to open it using a H2DbService instance and before changing the password.","title":"Change the Database Password"},{"location":"core-services/h2db-service/#persistence-modes","text":"The H2 database supports several persistence modes.","title":"Persistence Modes"},{"location":"core-services/h2db-service/#in-memory","text":"An in-memory database instance can be created using the following URL structure: jdbc:h2:mem: , where is a non-empty string that represents the database name. This configuration is suggested for database instances that are frequently updated. Examples: jdbc:h2:mem:kuradb jdbc:h2:mem:mydb The default database instance is in-memory by default and uses the jdbc:h2:mem:kuradb URL.","title":"In Memory"},{"location":"core-services/h2db-service/#persistent","text":"A persistent database instance can be created using the jdbc:h2:file: , where is a non-empty string that represents the database path. If no URL parameters are supplied the database will enable the transaction log by default. The transaction log is used to restore the database to a consistent state after a crash or power failure. This provides good protection against data losses but causes a lot of writes to the storage device, reducing both performance and the lifetime of flash-based storage devices. Examples: - jdbc:h2:file:/opt/db/mydb Make sure to use absolute paths in the DB URL since H2 does not support DB paths relative to the working directory.","title":"Persistent"},{"location":"core-services/introduction/","text":"Introduction This section describes the administrative tools available using the Gateway Administration Console . This web interface provides the ability to configure all services and applications that are installed and running on the gateway.","title":"Introduction"},{"location":"core-services/introduction/#introduction","text":"This section describes the administrative tools available using the Gateway Administration Console . This web interface provides the ability to configure all services and applications that are installed and running on the gateway.","title":"Introduction"},{"location":"core-services/network-status-rest-v1/","text":"Network Status Service V1 REST APIs and MQTT Request Handler The NET-STATUS-V1 cloud request handler and the corresponding REST APIs allow to retrieve the current status of the network interfaces available on the system. This cloud request handler and rest API is available only on the systems that provide a NetworkStatusService implementation, at the moment this corresponds to the devices that include the NetworkManager integration. Accessing the REST APIs requires to use an identity with the rest.network.status permission assigned. Request definitions GET/interfaceIds GET/status POST/status/byInterfaceId JSON definitions InterfaceIds InterfaceStatusList LoopbackInterfaceStatus EthernetInterfaceStatus WifiInterfaceStatus ModemInterfaceStatus NetworkInterfaceStatus IPAddressString HardwareAddress NetworkInterfaceIpAddress NetworkInterfaceIpAddressStatus WifiChannel WifiAccessPoint ModemModePair Sim Bearer ModemPorts NetworkInterfaceType NetworkInterfaceState WifiCapability WifiMode WifiSecurity ModemPortType ModemCapability ModemMode ModemBand SimType ESimStatus BearerIpType ModemConnectionType ModemConnectionStatus AccessTechnology RegistrationStatus FailureReport GenericFailureReport Request definitions GET/interfaceIds REST API path : /services/networkStatus/v1/interfaceIds description : Returns the identifiers of the network interfaces detected in the system. For Ethernet and WiFi interfaces, the identifier is typically the interface name. For the modems, instead, it is the usb or pci path. responses : 200 description : The list of the identifiers of the network interfaces detected in the system. response body : InterfaceIds 500 description : If an unexpected failure occurs while retrieving the interface list. response body : GenericFailureReport GET/status REST API path : /services/networkStatus/v1/status description : Returns the status for all interfaces currently available on the system. Failures in retrieving the status of specific interfaces will be reported using the failures field of the response. responses : 200 description : The status of the network interfaces in the system. response body : InterfaceStatusList 500 description : If an unexpected failure occurs while retrieving the interface list. response body : GenericFailureReport POST/status/byInterfaceId REST API path : /services/networkStatus/v1/status/byInterfaceId description : Returns the status for the network interfaces whose id is specified in the request. Failures in retrieving the status of specific interfaces, or the fact that an interface with the requested id cannot be found will be reported using the failures field of the responses. request body : InterfaceIds responses : 200 description : The status of the network interfaces in the system. response body : InterfaceStatusList 400 description : If the request object does not contain the interfaceIds field, it is null or if it contains empty or null interface ids. response body : GenericFailureReport 500 description : If an unexpected failure occurs while retrieving the interface list. response body : GenericFailureReport JSON definitions InterfaceIds An object containing a list of network interface identifiers Properties : interfaceIds : array The list of network interface identifiers array element type: string An interface identifier { \"interfaceIds\" : [ \"lo\" ] } InterfaceStatusList An object reporting a list of network interface status. If a failure occurs retrieving the status for a specific interface, the reason will be reported in the failures list. Properties : interfaces : array A list of network interface status array element type: variant Variants : object LoopbackInterfaceStatus object EthernetInterfaceStatus object WifiInterfaceStatus object ModemInterfaceStatus failures : array array element type: object FailureReport { \"failures\" : [], \"interfaces\" : [ { \"autoConnect\" : true , \"driver\" : \"unknown\" , \"driverVersion\" : \"\" , \"firmwareVersion\" : \"\" , \"hardwareAddress\" : \"00:00:00:00:00:00\" , \"id\" : \"lo\" , \"interfaceIp4Addresses\" : { \"addresses\" : [ { \"address\" : \"127.0.0.1\" , \"prefix\" : 8 } ], \"dnsServerAddresses\" : [] }, \"interfaceName\" : \"lo\" , \"mtu\" : 65536 , \"state\" : \"UNMANAGED\" , \"type\" : \"LOOPBACK\" , \"virtual\" : true } ] } { \"failures\" : [ { \"interfaceId\" : \"foo\" , \"reason\" : \"Not found.\" } ], \"interfaces\" : [] } LoopbackInterfaceStatus Object that contains specific properties to describe the status of an Loopback interface. It contains also all of the properties specified by NetworkInterfaceStatus . Properties : { \"autoConnect\" : true , \"driver\" : \"unknown\" , \"driverVersion\" : \"\" , \"firmwareVersion\" : \"\" , \"hardwareAddress\" : \"00:00:00:00:00:00\" , \"id\" : \"lo\" , \"interfaceIp4Addresses\" : { \"addresses\" : [ { \"address\" : \"127.0.0.1\" , \"prefix\" : 8 } ], \"dnsServerAddresses\" : [] }, \"interfaceName\" : \"lo\" , \"mtu\" : 65536 , \"state\" : \"UNMANAGED\" , \"type\" : \"LOOPBACK\" , \"virtual\" : true } EthernetInterfaceStatus Object that contains specific properties to describe the status of an Ethernet interface. It contains also all of the properties specified by NetworkInterfaceStatus . Properties : linkUp : bool { \"autoConnect\" : true , \"driver\" : \"igb\" , \"driverVersion\" : \"5.6.0-k\" , \"firmwareVersion\" : \"3.25, 0x800005d0\" , \"hardwareAddress\" : \"00:E0:C7:0A:5F:89\" , \"id\" : \"eno1\" , \"interfaceIp4Addresses\" : { \"addresses\" : [ { \"address\" : \"172.16.0.1\" , \"prefix\" : 24 } ], \"dnsServerAddresses\" : [], \"gateway\" : \"0.0.0.0\" }, \"interfaceName\" : \"eno1\" , \"linkUp\" : true , \"mtu\" : 1500 , \"state\" : \"ACTIVATED\" , \"type\" : \"ETHERNET\" , \"virtual\" : false } WifiInterfaceStatus Object that contains specific properties to describe the status of a WiFi interface. It contains also all of the properties specified by NetworkInterfaceStatus . Properties : capabilities : array array element type: string (enumerated) WifiCapability channels : array array element type: object WifiChannel countryCode : string mode : string (enumerated) WifiMode activeWifiAccessPoint : object ( optional ) WifiAccessPoint availableWifiAccessPoints : array array element type: object WifiAccessPoint { \"activeWifiAccessPoint\" : { \"channel\" : { \"channel\" : 11 , \"frequency\" : 2462 }, \"hardwareAddress\" : \"11:22:33:44:55:66\" , \"maxBitrate\" : 130000 , \"mode\" : \"INFRA\" , \"rsnSecurity\" : [ \"GROUP_CCMP\" , \"KEY_MGMT_PSK\" , \"PAIR_CCMP\" ], \"signalQuality\" : 100 , \"signalStrength\" : -20 , \"ssid\" : \"MyAccessPoint\" , \"wpaSecurity\" : [ \"NONE\" ] }, \"autoConnect\" : true , \"availableWifiAccessPoints\" : [ { \"channel\" : { \"channel\" : 11 , \"frequency\" : 2462 }, \"hardwareAddress\" : \"11:22:33:44:55:66\" , \"maxBitrate\" : 130000 , \"mode\" : \"INFRA\" , \"rsnSecurity\" : [ \"GROUP_CCMP\" , \"KEY_MGMT_PSK\" , \"PAIR_CCMP\" ], \"signalQuality\" : 100 , \"signalStrength\" : -20 , \"ssid\" : \"MyAccessPoint\" , \"wpaSecurity\" : [ \"NONE\" ] }, { \"channel\" : { \"channel\" : 5 , \"frequency\" : 2432 }, \"hardwareAddress\" : \"22:33:44:55:66:77\" , \"maxBitrate\" : 270000 , \"mode\" : \"INFRA\" , \"rsnSecurity\" : [ \"GROUP_CCMP\" , \"KEY_MGMT_PSK\" , \"PAIR_CCMP\" ], \"signalQuality\" : 42 , \"signalStrength\" : -69 , \"ssid\" : \"OtherSSID\" , \"wpaSecurity\" : [ \"NONE\" ] } ], \"capabilities\" : [ \"CIPHER_WEP40\" , \"WPA\" , \"AP\" , \"FREQ_VALID\" , \"ADHOC\" , \"RSN\" , \"CIPHER_TKIP\" , \"CIPHER_WEP104\" , \"CIPHER_CCMP\" , \"FREQ_2GHZ\" ], \"channels\" : [ { \"attenuation\" : 20.0 , \"channel\" : 1 , \"disabled\" : false , \"frequency\" : 2412 , \"noInitiatingRadiation\" : false , \"radarDetection\" : false }, { \"attenuation\" : 20.0 , \"channel\" : 2 , \"disabled\" : false , \"frequency\" : 2417 , \"noInitiatingRadiation\" : false , \"radarDetection\" : false } ], \"countryCode\" : \"IT\" , \"driver\" : \"brcmfmac\" , \"driverVersion\" : \"7.45.98.94\" , \"firmwareVersion\" : \"01-3b33decd\" , \"hardwareAddress\" : \"44:55:66:77:88:99\" , \"id\" : \"wlan0\" , \"interfaceIp4Addresses\" : { \"addresses\" : [ { \"address\" : \"192.168.0.113\" , \"prefix\" : 24 } ], \"dnsServerAddresses\" : [] }, \"interfaceName\" : \"wlan0\" , \"mode\" : \"INFRA\" , \"mtu\" : 1500 , \"state\" : \"ACTIVATED\" , \"type\" : \"WIFI\" , \"virtual\" : false } { \"activeWifiAccessPoint\" : { \"channel\" : { \"channel\" : 1 , \"frequency\" : 2412 }, \"hardwareAddress\" : \"44:55:66:77:88:99\" , \"maxBitrate\" : 0 , \"mode\" : \"INFRA\" , \"rsnSecurity\" : [ \"GROUP_CCMP\" , \"KEY_MGMT_PSK\" , \"PAIR_CCMP\" ], \"signalQuality\" : 0 , \"signalStrength\" : -104 , \"ssid\" : \"kura_gateway_raspberry_pi\" , \"wpaSecurity\" : [ \"NONE\" ] }, \"autoConnect\" : true , \"availableWifiAccessPoints\" : [ { \"channel\" : { \"channel\" : 1 , \"frequency\" : 2412 }, \"hardwareAddress\" : \"44:55:66:77:88:99\" , \"maxBitrate\" : 0 , \"mode\" : \"INFRA\" , \"rsnSecurity\" : [ \"GROUP_CCMP\" , \"KEY_MGMT_PSK\" , \"PAIR_CCMP\" ], \"signalQuality\" : 0 , \"signalStrength\" : -104 , \"ssid\" : \"kura_gateway_raspberry_pi\" , \"wpaSecurity\" : [ \"NONE\" ] } ], \"capabilities\" : [ \"CIPHER_WEP40\" , \"WPA\" , \"AP\" , \"FREQ_VALID\" , \"ADHOC\" , \"RSN\" , \"CIPHER_TKIP\" , \"CIPHER_WEP104\" , \"CIPHER_CCMP\" , \"FREQ_2GHZ\" ], \"channels\" : [ { \"attenuation\" : 20.0 , \"channel\" : 1 , \"disabled\" : false , \"frequency\" : 2412 , \"noInitiatingRadiation\" : false , \"radarDetection\" : false }, { \"attenuation\" : 20.0 , \"channel\" : 2 , \"disabled\" : false , \"frequency\" : 2417 , \"noInitiatingRadiation\" : false , \"radarDetection\" : false } ], \"countryCode\" : \"00\" , \"driver\" : \"brcmfmac\" , \"driverVersion\" : \"7.45.98.94\" , \"firmwareVersion\" : \"01-3b33decd\" , \"hardwareAddress\" : \"44:55:66:77:88:99\" , \"id\" : \"wlan0\" , \"interfaceIp4Addresses\" : { \"addresses\" : [ { \"address\" : \"172.16.1.1\" , \"prefix\" : 24 } ], \"dnsServerAddresses\" : [] }, \"interfaceName\" : \"wlan0\" , \"mode\" : \"MASTER\" , \"mtu\" : 1500 , \"state\" : \"ACTIVATED\" , \"type\" : \"WIFI\" , \"virtual\" : false } ModemInterfaceStatus Object that contains specific properties to describe the status of a Modem interface. It contains also all of the properties specified by NetworkInterfaceStatus . Properties : model : string manufacturer : string serialNumber : string softwareRevision : string hardwareRevision : string primaryPort : string ports : object ModemPorts supportedModemCapabilities : array array element type: string (enumerated) ModemCapability currentModemCapabilities : array array element type: string (enumerated) ModemCapability powerState : string (enumerated) ModemPowerState supportedModes : array array element type: object ModemModePair currentModes : object ModemModePair supportedBands : array array element type: string (enumerated) ModemBand currentBands : array array element type: string (enumerated) ModemBand gpsSupported : bool availableSims : array array element type: object Sim simLocked : bool bearers : array array element type: object Bearer connectionType : string (enumerated) ModemConnectionType connectionStatus : string (enumerated) ModemConnectionStatus accessTechnologies : array array element type: string (enumerated) AccessTechnology signalQuality : number signalStrength : number registrationStatus : string (enumerated) RegistrationStatus operatorName : string { \"accessTechnologies\" : [ \"LTE\" ], \"autoConnect\" : true , \"availableSims\" : [ { \"active\" : true , \"primary\" : true , \"eSimStatus\" : \"UNKNOWN\" , \"eid\" : \"\" , \"iccid\" : \"1111111111111111111\" , \"imsi\" : \"111111111111111\" , \"operatorName\" : \"MyOperator\" , \"simType\" : \"PHYSICAL\" } ], \"bearers\" : [ { \"apn\" : \"apn.myoperator.com\" , \"bytesReceived\" : 0 , \"bytesTransmitted\" : 0 , \"connected\" : true , \"ipTypes\" : [ \"IPV4\" ], \"name\" : \"wwp11s0f2u3i4\" } ], \"connectionStatus\" : \"CONNECTED\" , \"connectionType\" : \"DirectIP\" , \"currentBands\" : [ \"DCS\" , \"EUTRAN_3\" , \"EUTRAN_19\" , \"EUTRAN_40\" , \"EUTRAN_26\" , \"EUTRAN_28\" , \"EUTRAN_41\" , \"UTRAN_6\" , \"EUTRAN_13\" , \"EUTRAN_25\" , \"EUTRAN_5\" , \"EUTRAN_7\" , \"EUTRAN_8\" , \"UTRAN_2\" , \"EUTRAN_38\" , \"UTRAN_1\" , \"EUTRAN_12\" , \"UTRAN_8\" , \"EUTRAN_18\" , \"UTRAN_19\" , \"G850\" , \"EUTRAN_20\" , \"UTRAN_5\" , \"EUTRAN_1\" , \"EUTRAN_39\" , \"EUTRAN_2\" , \"EUTRAN_4\" , \"EGSM\" , \"PCS\" , \"UTRAN_4\" ], \"currentModemCapabilities\" : [ \"GSM_UMTS\" , \"LTE\" ], \"currentModes\" : { \"modes\" : [ \"MODE_2G\" , \"MODE_3G\" , \"MODE_4G\" ], \"preferredMode\" : \"MODE_4G\" }, \"driver\" : \"qmi_wwan, option1\" , \"driverVersion\" : \"\" , \"firmwareVersion\" : \"\" , \"gpsSupported\" : true , \"hardwareAddress\" : \"00:00:00:00:00:00\" , \"hardwareRevision\" : \"10000\" , \"id\" : \"1-3\" , \"interfaceIp4Addresses\" : { \"addresses\" : [ { \"address\" : \"1.2.3.4\" , \"prefix\" : 30 } ], \"dnsServerAddresses\" : [ \"1.2.3.6\" , \"1.2.3.7\" ], \"gateway\" : \"1.2.3.5\" }, \"interfaceName\" : \"wwp11s0f2u3i4\" , \"manufacturer\" : \"QUALCOMM INCORPORATED\" , \"model\" : \"QUECTEL Mobile Broadband Module\" , \"mtu\" : 1500 , \"operatorName\" : \"MyOperator\" , \"ports\" : { \"cdc-wdm0\" : \"QMI\" , \"ttyUSB0\" : \"QCDM\" , \"ttyUSB1\" : \"GPS\" , \"ttyUSB2\" : \"AT\" , \"ttyUSB3\" : \"AT\" , \"wwp11s0f2u3i4\" : \"NET\" }, \"powerState\" : \"ON\" , \"primaryPort\" : \"cdc-wdm0\" , \"registrationStatus\" : \"HOME\" , \"serialNumber\" : \"111111111111111\" , \"signalQuality\" : 55 , \"signalStrength\" : -80 , \"simLocked\" : true , \"softwareRevision\" : \"EG25GGBR07A08M2G\" , \"state\" : \"ACTIVATED\" , \"supportedBands\" : [ \"DCS\" , \"EUTRAN_3\" , \"EUTRAN_19\" , \"EUTRAN_40\" , \"EUTRAN_26\" , \"EUTRAN_28\" , \"EUTRAN_41\" , \"UTRAN_6\" , \"EUTRAN_13\" , \"EUTRAN_25\" , \"EUTRAN_5\" , \"EUTRAN_7\" , \"EUTRAN_8\" , \"UTRAN_2\" , \"EUTRAN_38\" , \"UTRAN_1\" , \"EUTRAN_12\" , \"UTRAN_8\" , \"EUTRAN_18\" , \"UTRAN_19\" , \"G850\" , \"EUTRAN_20\" , \"UTRAN_5\" , \"EUTRAN_1\" , \"EUTRAN_39\" , \"EUTRAN_2\" , \"EUTRAN_4\" , \"EGSM\" , \"PCS\" , \"UTRAN_4\" ], \"supportedModemCapabilities\" : [ \"NONE\" ], \"supportedModes\" : [ { \"modes\" : [ \"MODE_4G\" ], \"preferredMode\" : \"NONE\" }, { \"modes\" : [ \"MODE_2G\" , \"MODE_3G\" , \"MODE_4G\" ], \"preferredMode\" : \"MODE_4G\" } ], \"type\" : \"MODEM\" , \"virtual\" : false } NetworkInterfaceStatus This object contains the common properties contained by the status object reported for a network interface. A network interface is identified by Kura using the id field. It is used to internally manage the interface. The interfaceName, instead, is the IP interface as it may appear on the system. For Ethernet and WiFi interfaces the two values coincide (i.e. eth0, wlp1s0, ...). For modems, instead, the id is typically the usb or pci path, while the interfaceName is the IP interface created when they are connected. When the modem is disconnected the interfaceName can have a different value. Properties : id : string interfaceName : string hardwareAddress : string HardwareAddress driver : string driverVersion : string firmwareVersion : string virtual : bool state : string (enumerated) NetworkInterfaceState autoConnect : bool mtu : number interfaceIp4Addresses : array ( optional ) array element type: object NetworkInterfaceIpAddressStatus interfaceIp6Addresses : array ( optional ) array element type: object NetworkInterfaceIpAddressStatus IPAddressString Represents an IPv4 or IPv6 addresses as a string. HardwareAddress Represents an hardware address as its bytes reported as two characters hexadecimal strings separated by the ':' character. e.g. 00:11:22:33:A4:FC:BB. NetworkInterfaceIpAddress This object describes an IP address with its prefix. It can be used for IPv4 or IPv6 addresses. Properties : address : string IPAddressString prefix : number NetworkInterfaceIpAddressStatus This class describes the IP address status of a network interface: a list of IP addresses, an optional gateway and a list of DNS servers address. It can be used for IPv4 or IPv6 addresses. Properties : addresses : array array element type: object NetworkInterfaceIpAddress gateway : string ( optional This field can be missing if the interface has no gateway.) IPAddressString dnsServerAddresses : array array element type: string IPAddressString WifiChannel This class represent a WiFi channel, providing the channel number, frequency, status and other useful information. Properties : channel : number frequency : number disabled : bool ( optional ) attenuation : number ( optional ) noInitiatingRadiation : bool ( optional ) radarDetection : bool ( optional ) WifiAccessPoint This object describes a Wifi Access Point. It can be used both for describing a detected AP after a WiFi scan when in Station mode and the provided AP when in Master (or Access Point) mode. Properties : ssid : string The Service Set IDentifier of the WiFi network hardwareAddress : string HardwareAddress channel : object WifiChannel mode : string (enumerated) WifiMode maxBitrate : number The maximum bitrate this access point is capable of. signalQuality : number The current signal quality of the access point in percentage. signalStrength : number The current signal strength of the access point in dBm. wpaSecurity : array The WPA capabilities of the access point array element type: string (enumerated) WifiSecurity rsnSecurity : array The RSN capabilities of the access point array element type: string (enumerated) WifiSecurity ModemModePair This object represents a pair of Modem Mode list and a preferred one. Properties : modes : array array element type: string (enumerated) ModemMode preferredMode : string (enumerated) ModemMode Sim This class contains all relevant properties to describe a SIM (Subscriber Identity Module). Properties : active : bool primary : bool iccid : string imsi : string eid : string operatorName : string simType : string (enumerated) SimType eSimStatus : string (enumerated) ESimStatus Bearer This object describes the Bearer or Context associated to a modem connection. Properties : name : string connected : bool apn : string ipTypes : array array element type: string (enumerated) BearerIpType bytesTransmitted : number bytesReceived : number ModemPorts An object representing a set of modem ports. The members of this object represent modem ports, the member names represent the modem port name. This object can have a variable number of members. Properties : propertyName : string (enumerated) ModemPortType NetworkInterfaceType The type of a network interface. Possible values UNKNOWN : The device type is unknown ETHERNET : The device is a wired Ethernet device. WIFI : The device is an 802.11 WiFi device. UNUSED1 UNUSED2 BT : The device is a Bluetooth device. OLPC_MESH : The device is an OLPC mesh networking device. WIMAX : The device is an 802.16e Mobile WiMAX device. MODEM : The device is a modem supporting one or more of analog telephone, CDMA/EVDO, GSM/UMTS/HSPA, or LTE standards to access a cellular or wireline data network. INFINIBAND : The device is an IP-capable InfiniBand interface. BOND : The device is a bond master interface. VLAN : The device is a VLAN interface. ADSL : The device is an ADSL device. BRIDGE : The device is a bridge master interface. GENERIC : This is a generic support for unrecognized device types. TEAM : The device is a team master interface. TUN : The device is a TUN or TAP interface. TUNNEL : The device is an IP tunnel interface. MACVLAN : The device is a MACVLAN interface. VXLAN : The device is a VXLAN interface. VETH : The device is a VETH interface. MACSEC : The device is a MACsec interface. DUMMY : The device is a dummy interface. PPP : The device is a PPP interface. OVS_INTERFACE : The device is a Open vSwitch interface. OVS_PORT : The device is a Open vSwitch port OVS_BRIDGE : The device is a Open vSwitch bridge. WPAN : The device is a IEEE 802.15.4 (WPAN) MAC Layer Device. SIXLOWPAN : The device is a 6LoWPAN interface. WIREGUARD : The device is a WireGuard interface. WIFI_P2P : The device is an 802.11 Wi-Fi P2P device. VRF : The device is a VRF (Virtual Routing and Forwarding) interface. LOOPBACK : The device is a loopback device. NetworkInterfaceState The state of a network interface. Possible values UNKNOWN : The device is in an unknown state. UNMANAGED : The device cannot be used (carrier off, rfkill, etc). UNAVAILABLE : The device is not connected. DISCONNECTED : The device is preparing to connect. PREPARE : The device is being configured. CONFIG : The device is awaiting secrets necessary to continue connection. NEED_AUTH : The IP settings of the device are being requested and configured. IP_CONFIG : The device's IP connectivity ability is being determined. IP_CHECK : The device is waiting for secondary connections to be activated. SECONDARIES : The device is waiting for secondary connections to be activated. ACTIVATED : The device is active. DEACTIVATING : The device's network connection is being turn down. FAILED : The device is in a failure state following an attempt to activate it. WifiCapability The capability of a WiFi interface. Possible values NONE : The device has no encryption/authentication capabilities CIPHER_WEP40 : The device supports 40/64-bit WEP encryption. CIPHER_WEP104 : The device supports 104/128-bit WEP encryption. CIPHER_TKIP : The device supports the TKIP encryption. CIPHER_CCMP : The device supports the AES/CCMP encryption. WPA : The device supports the WPA1 encryption/authentication protocol. RSN : The device supports the WPA2/RSN encryption/authentication protocol. AP : The device supports Access Point mode. ADHOC : The device supports Ad-Hoc mode. FREQ_VALID : The device reports frequency capabilities. FREQ_2GHZ : The device supports 2.4GHz frequencies. FREQ_5GHZ : The device supports 5GHz frequencies. MESH : The device supports mesh points. IBSS_RSN : The device supports WPA2 in IBSS networks WifiMode Modes of operation for wifi interfaces Possible values UNKNOWN : Mode is unknown. ADHOC : Uncoordinated network without central infrastructure. INFRA : Client mode - Coordinated network with one or more central controllers. MASTER : Access Point Mode - Coordinated network with one or more central controllers. WifiSecurity Flags describing the security capabilities of an access point. Possible values NONE : None PAIR_WEP40 : Supports pairwise 40-bit WEP encryption. PAIR_WEP104 : Supports pairwise 104-bit WEP encryption. PAIR_TKIP : Supports pairwise TKIP encryption. PAIR_CCMP : Supports pairwise CCMP encryption. GROUP_WEP40 : Supports a group 40-bit WEP cipher. GROUP_WEP104 : Supports a group 104-bit WEP cipher. GROUP_TKIP : Supports a group TKIP cipher. GROUP_CCMP : Supports a group CCMP cipher. KEY_MGMT_PSK : Supports PSK key management. KEY_MGMT_802_1X : Supports 802.1x key management. SECURITY_NONE : Supports no encryption. SECURITY_WEP : Supports WEP encryption. SECURITY_WPA : Supports WPA encryption. SECURITY_WPA2 : Supports WPA2 encryption. SECURITY_WPA_WPA2 : Supports WPA and WPA2 encryption. ModemPortType The type of a modem port. Possible values UNKNOWN NET AT QCDM GPS QMI MBIM AUDIO IGNORED ModemCapability The generic access technologies families supported by a modem. Possible values NONE : The modem has no capabilities. POTS : The modem supports the Plain Old Telephone Service (analog wired telephone network). EVDO : The modem supports EVDO revision 0, A or B. GSM_UMTS : The modem supports at least one of GSM, GPRS, EDGE, UMTS, HSDPA, HSUPA or HSPA+ technologies. LTE : The modem has LTE capabilities. IRIDIUM : The modem supports Iridium technology. FIVE_GNR : The modem supports 5GNR. TDS : The modem supports TDS. ANY : The modem supports all capabilities. ModemMode The generic access mode a modem supports. Possible values NONE CS MODE_2G MODE_3G MODE_4G MODE_5G ANY ModemBand The radio bands supported by a modem when connected to a mobile network. Possible values UNKNOWN EGSM DCS PCS G850 UTRAN_1 UTRAN_3 UTRAN_4 UTRAN_6 UTRAN_5 UTRAN_8 UTRAN_9 UTRAN_2 UTRAN_7 G450 G480 G750 G380 G410 G710 G810 EUTRAN_1 EUTRAN_2 EUTRAN_3 EUTRAN_4 EUTRAN_5 EUTRAN_6 EUTRAN_7 EUTRAN_8 EUTRAN_9 EUTRAN_10 EUTRAN_11 EUTRAN_12 EUTRAN_13 EUTRAN_14 EUTRAN_17 EUTRAN_18 EUTRAN_19 EUTRAN_20 EUTRAN_21 EUTRAN_22 EUTRAN_23 EUTRAN_24 EUTRAN_25 EUTRAN_26 EUTRAN_27 EUTRAN_28 EUTRAN_29 EUTRAN_30 EUTRAN_31 EUTRAN_32 EUTRAN_33 EUTRAN_34 EUTRAN_35 EUTRAN_36 EUTRAN_37 EUTRAN_38 EUTRAN_39 EUTRAN_40 EUTRAN_41 EUTRAN_42 EUTRAN_43 EUTRAN_44 EUTRAN_45 EUTRAN_46 EUTRAN_47 EUTRAN_48 EUTRAN_49 EUTRAN_50 EUTRAN_51 EUTRAN_52 EUTRAN_53 EUTRAN_54 EUTRAN_55 EUTRAN_56 EUTRAN_57 EUTRAN_58 EUTRAN_59 EUTRAN_60 EUTRAN_61 EUTRAN_62 EUTRAN_63 EUTRAN_64 EUTRAN_65 EUTRAN_66 EUTRAN_67 EUTRAN_68 EUTRAN_69 EUTRAN_70 EUTRAN_71 EUTRAN_85 CDMA_BC0 CDMA_BC1 CDMA_BC2 CDMA_BC3 CDMA_BC4 CDMA_BC5 CDMA_BC6 CDMA_BC7 CDMA_BC8 CDMA_BC9 CDMA_BC10 CDMA_BC11 CDMA_BC12 CDMA_BC13 CDMA_BC14 CDMA_BC15 CDMA_BC16 CDMA_BC17 CDMA_BC18 CDMA_BC19 UTRAN_10 UTRAN_11 UTRAN_12 UTRAN_13 UTRAN_14 UTRAN_19 UTRAN_20 UTRAN_21 UTRAN_22 UTRAN_25 UTRAN_26 UTRAN_32 ANY NGRAN_1 NGRAN_2 NGRAN_3 NGRAN_5 NGRAN_7 NGRAN_8 NGRAN_12 NGRAN_13 NGRAN_14 NGRAN_18 NGRAN_20 NGRAN_25 NGRAN_26 NGRAN_28 NGRAN_29 NGRAN_30 NGRAN_34 NGRAN_38 NGRAN_39 NGRAN_40 NGRAN_41 NGRAN_48 NGRAN_50 NGRAN_51 NGRAN_53 NGRAN_65 NGRAN_66 NGRAN_70 NGRAN_71 NGRAN_74 NGRAN_75 NGRAN_76 NGRAN_77 NGRAN_78 NGRAN_79 NGRAN_80 NGRAN_81 NGRAN_82 NGRAN_83 NGRAN_84 NGRAN_86 NGRAN_89 NGRAN_90 NGRAN_91 NGRAN_92 NGRAN_93 NGRAN_94 NGRAN_95 NGRAN_257 NGRAN_258 NGRAN_260 NGRAN_261 SimType The SIM (Subscriber Identity Module) type. Possible values UNKNOWN PHYSICAL ESIM ESimStatus The status of an ESIM. Possible values UNKNOWN NO_PROFILES WITH_PROFILES BearerIpType The type of Bearer or Context associated to a modem connection. Possible values NONE IPV4 IPV6 IPV4V6 NON_IP ANY ModemConnectionType Possible values PPP : Point to Point Protocol DirectIP : Direct IP ModemConnectionStatus The status of a modem. Possible values FAILED : The modem is unavailable UNKNOWN : The modem is in an unknown state. INITIALIZING : The modem is being initialised. LOCKED : The modem is locked. DISABLED : The modem is disabled and powered off. DISABLING : The modem is disabling. ENABLING : The modem is enabling.. ENABLED : The modem is enabled but not registered to a network provider. SEARCHING : The modem is searching for a network provider. REGISTERED : The modem is registered to a network provider. DISCONNECTING : The modem is disconnecting. CONNECTING : The modem is connecting. CONNECTED : The modem is connected. AccessTechnology The specific technology types used when a modem is connected or registered to a network. Possible values UNKNOWN POTS GSM GSM_COMPACT GPRS EDGE UMTS HSDPA HSUPA HSPA HSPA_PLUS ONEXRTT EVDO0 EVDOA EVDOB LTE FIVEGNR LTE_CAT_M LTE_NB_IOT ANY RegistrationStatus The registration status of a modem when connected to a mobile network. Possible values IDLE HOME SEARCHING DENIED UNKNOWN ROAMING HOME_SMS_ONLY ROAMING_SMS_ONLY EMERGENCY_ONLY HOME_CSFB_NOT_PREFERRED ROAMING_CSFB_NOT_PREFERRED ATTACHED_RLOS FailureReport An object reporting a failure while retrieving the status of a specific network interface Properties : interfaceId : string The identifier of the interface whose status cannot be retrieved. reason : string A message describing the reason of the failure. GenericFailureReport An object reporting a failure message. Properties : message : string A message describing the failure.","title":"Network Status Service V1 REST APIs and MQTT Request Handler"},{"location":"core-services/network-status-rest-v1/#network-status-service-v1-rest-apis-and-mqtt-request-handler","text":"The NET-STATUS-V1 cloud request handler and the corresponding REST APIs allow to retrieve the current status of the network interfaces available on the system. This cloud request handler and rest API is available only on the systems that provide a NetworkStatusService implementation, at the moment this corresponds to the devices that include the NetworkManager integration. Accessing the REST APIs requires to use an identity with the rest.network.status permission assigned. Request definitions GET/interfaceIds GET/status POST/status/byInterfaceId JSON definitions InterfaceIds InterfaceStatusList LoopbackInterfaceStatus EthernetInterfaceStatus WifiInterfaceStatus ModemInterfaceStatus NetworkInterfaceStatus IPAddressString HardwareAddress NetworkInterfaceIpAddress NetworkInterfaceIpAddressStatus WifiChannel WifiAccessPoint ModemModePair Sim Bearer ModemPorts NetworkInterfaceType NetworkInterfaceState WifiCapability WifiMode WifiSecurity ModemPortType ModemCapability ModemMode ModemBand SimType ESimStatus BearerIpType ModemConnectionType ModemConnectionStatus AccessTechnology RegistrationStatus FailureReport GenericFailureReport","title":"Network Status Service V1 REST APIs and MQTT Request Handler"},{"location":"core-services/network-status-rest-v1/#request-definitions","text":"","title":"Request definitions"},{"location":"core-services/network-status-rest-v1/#getinterfaceids","text":"REST API path : /services/networkStatus/v1/interfaceIds description : Returns the identifiers of the network interfaces detected in the system. For Ethernet and WiFi interfaces, the identifier is typically the interface name. For the modems, instead, it is the usb or pci path. responses : 200 description : The list of the identifiers of the network interfaces detected in the system. response body : InterfaceIds 500 description : If an unexpected failure occurs while retrieving the interface list. response body : GenericFailureReport","title":"GET/interfaceIds"},{"location":"core-services/network-status-rest-v1/#getstatus","text":"REST API path : /services/networkStatus/v1/status description : Returns the status for all interfaces currently available on the system. Failures in retrieving the status of specific interfaces will be reported using the failures field of the response. responses : 200 description : The status of the network interfaces in the system. response body : InterfaceStatusList 500 description : If an unexpected failure occurs while retrieving the interface list. response body : GenericFailureReport","title":"GET/status"},{"location":"core-services/network-status-rest-v1/#poststatusbyinterfaceid","text":"REST API path : /services/networkStatus/v1/status/byInterfaceId description : Returns the status for the network interfaces whose id is specified in the request. Failures in retrieving the status of specific interfaces, or the fact that an interface with the requested id cannot be found will be reported using the failures field of the responses. request body : InterfaceIds responses : 200 description : The status of the network interfaces in the system. response body : InterfaceStatusList 400 description : If the request object does not contain the interfaceIds field, it is null or if it contains empty or null interface ids. response body : GenericFailureReport 500 description : If an unexpected failure occurs while retrieving the interface list. response body : GenericFailureReport","title":"POST/status/byInterfaceId"},{"location":"core-services/network-status-rest-v1/#json-definitions","text":"","title":"JSON definitions"},{"location":"core-services/network-status-rest-v1/#interfaceids","text":"An object containing a list of network interface identifiers Properties : interfaceIds : array The list of network interface identifiers array element type: string An interface identifier { \"interfaceIds\" : [ \"lo\" ] }","title":"InterfaceIds"},{"location":"core-services/network-status-rest-v1/#interfacestatuslist","text":"An object reporting a list of network interface status. If a failure occurs retrieving the status for a specific interface, the reason will be reported in the failures list. Properties : interfaces : array A list of network interface status array element type: variant Variants : object LoopbackInterfaceStatus object EthernetInterfaceStatus object WifiInterfaceStatus object ModemInterfaceStatus failures : array array element type: object FailureReport { \"failures\" : [], \"interfaces\" : [ { \"autoConnect\" : true , \"driver\" : \"unknown\" , \"driverVersion\" : \"\" , \"firmwareVersion\" : \"\" , \"hardwareAddress\" : \"00:00:00:00:00:00\" , \"id\" : \"lo\" , \"interfaceIp4Addresses\" : { \"addresses\" : [ { \"address\" : \"127.0.0.1\" , \"prefix\" : 8 } ], \"dnsServerAddresses\" : [] }, \"interfaceName\" : \"lo\" , \"mtu\" : 65536 , \"state\" : \"UNMANAGED\" , \"type\" : \"LOOPBACK\" , \"virtual\" : true } ] } { \"failures\" : [ { \"interfaceId\" : \"foo\" , \"reason\" : \"Not found.\" } ], \"interfaces\" : [] }","title":"InterfaceStatusList"},{"location":"core-services/network-status-rest-v1/#loopbackinterfacestatus","text":"Object that contains specific properties to describe the status of an Loopback interface. It contains also all of the properties specified by NetworkInterfaceStatus . Properties : { \"autoConnect\" : true , \"driver\" : \"unknown\" , \"driverVersion\" : \"\" , \"firmwareVersion\" : \"\" , \"hardwareAddress\" : \"00:00:00:00:00:00\" , \"id\" : \"lo\" , \"interfaceIp4Addresses\" : { \"addresses\" : [ { \"address\" : \"127.0.0.1\" , \"prefix\" : 8 } ], \"dnsServerAddresses\" : [] }, \"interfaceName\" : \"lo\" , \"mtu\" : 65536 , \"state\" : \"UNMANAGED\" , \"type\" : \"LOOPBACK\" , \"virtual\" : true }","title":"LoopbackInterfaceStatus"},{"location":"core-services/network-status-rest-v1/#ethernetinterfacestatus","text":"Object that contains specific properties to describe the status of an Ethernet interface. It contains also all of the properties specified by NetworkInterfaceStatus . Properties : linkUp : bool { \"autoConnect\" : true , \"driver\" : \"igb\" , \"driverVersion\" : \"5.6.0-k\" , \"firmwareVersion\" : \"3.25, 0x800005d0\" , \"hardwareAddress\" : \"00:E0:C7:0A:5F:89\" , \"id\" : \"eno1\" , \"interfaceIp4Addresses\" : { \"addresses\" : [ { \"address\" : \"172.16.0.1\" , \"prefix\" : 24 } ], \"dnsServerAddresses\" : [], \"gateway\" : \"0.0.0.0\" }, \"interfaceName\" : \"eno1\" , \"linkUp\" : true , \"mtu\" : 1500 , \"state\" : \"ACTIVATED\" , \"type\" : \"ETHERNET\" , \"virtual\" : false }","title":"EthernetInterfaceStatus"},{"location":"core-services/network-status-rest-v1/#wifiinterfacestatus","text":"Object that contains specific properties to describe the status of a WiFi interface. It contains also all of the properties specified by NetworkInterfaceStatus . Properties : capabilities : array array element type: string (enumerated) WifiCapability channels : array array element type: object WifiChannel countryCode : string mode : string (enumerated) WifiMode activeWifiAccessPoint : object ( optional ) WifiAccessPoint availableWifiAccessPoints : array array element type: object WifiAccessPoint { \"activeWifiAccessPoint\" : { \"channel\" : { \"channel\" : 11 , \"frequency\" : 2462 }, \"hardwareAddress\" : \"11:22:33:44:55:66\" , \"maxBitrate\" : 130000 , \"mode\" : \"INFRA\" , \"rsnSecurity\" : [ \"GROUP_CCMP\" , \"KEY_MGMT_PSK\" , \"PAIR_CCMP\" ], \"signalQuality\" : 100 , \"signalStrength\" : -20 , \"ssid\" : \"MyAccessPoint\" , \"wpaSecurity\" : [ \"NONE\" ] }, \"autoConnect\" : true , \"availableWifiAccessPoints\" : [ { \"channel\" : { \"channel\" : 11 , \"frequency\" : 2462 }, \"hardwareAddress\" : \"11:22:33:44:55:66\" , \"maxBitrate\" : 130000 , \"mode\" : \"INFRA\" , \"rsnSecurity\" : [ \"GROUP_CCMP\" , \"KEY_MGMT_PSK\" , \"PAIR_CCMP\" ], \"signalQuality\" : 100 , \"signalStrength\" : -20 , \"ssid\" : \"MyAccessPoint\" , \"wpaSecurity\" : [ \"NONE\" ] }, { \"channel\" : { \"channel\" : 5 , \"frequency\" : 2432 }, \"hardwareAddress\" : \"22:33:44:55:66:77\" , \"maxBitrate\" : 270000 , \"mode\" : \"INFRA\" , \"rsnSecurity\" : [ \"GROUP_CCMP\" , \"KEY_MGMT_PSK\" , \"PAIR_CCMP\" ], \"signalQuality\" : 42 , \"signalStrength\" : -69 , \"ssid\" : \"OtherSSID\" , \"wpaSecurity\" : [ \"NONE\" ] } ], \"capabilities\" : [ \"CIPHER_WEP40\" , \"WPA\" , \"AP\" , \"FREQ_VALID\" , \"ADHOC\" , \"RSN\" , \"CIPHER_TKIP\" , \"CIPHER_WEP104\" , \"CIPHER_CCMP\" , \"FREQ_2GHZ\" ], \"channels\" : [ { \"attenuation\" : 20.0 , \"channel\" : 1 , \"disabled\" : false , \"frequency\" : 2412 , \"noInitiatingRadiation\" : false , \"radarDetection\" : false }, { \"attenuation\" : 20.0 , \"channel\" : 2 , \"disabled\" : false , \"frequency\" : 2417 , \"noInitiatingRadiation\" : false , \"radarDetection\" : false } ], \"countryCode\" : \"IT\" , \"driver\" : \"brcmfmac\" , \"driverVersion\" : \"7.45.98.94\" , \"firmwareVersion\" : \"01-3b33decd\" , \"hardwareAddress\" : \"44:55:66:77:88:99\" , \"id\" : \"wlan0\" , \"interfaceIp4Addresses\" : { \"addresses\" : [ { \"address\" : \"192.168.0.113\" , \"prefix\" : 24 } ], \"dnsServerAddresses\" : [] }, \"interfaceName\" : \"wlan0\" , \"mode\" : \"INFRA\" , \"mtu\" : 1500 , \"state\" : \"ACTIVATED\" , \"type\" : \"WIFI\" , \"virtual\" : false } { \"activeWifiAccessPoint\" : { \"channel\" : { \"channel\" : 1 , \"frequency\" : 2412 }, \"hardwareAddress\" : \"44:55:66:77:88:99\" , \"maxBitrate\" : 0 , \"mode\" : \"INFRA\" , \"rsnSecurity\" : [ \"GROUP_CCMP\" , \"KEY_MGMT_PSK\" , \"PAIR_CCMP\" ], \"signalQuality\" : 0 , \"signalStrength\" : -104 , \"ssid\" : \"kura_gateway_raspberry_pi\" , \"wpaSecurity\" : [ \"NONE\" ] }, \"autoConnect\" : true , \"availableWifiAccessPoints\" : [ { \"channel\" : { \"channel\" : 1 , \"frequency\" : 2412 }, \"hardwareAddress\" : \"44:55:66:77:88:99\" , \"maxBitrate\" : 0 , \"mode\" : \"INFRA\" , \"rsnSecurity\" : [ \"GROUP_CCMP\" , \"KEY_MGMT_PSK\" , \"PAIR_CCMP\" ], \"signalQuality\" : 0 , \"signalStrength\" : -104 , \"ssid\" : \"kura_gateway_raspberry_pi\" , \"wpaSecurity\" : [ \"NONE\" ] } ], \"capabilities\" : [ \"CIPHER_WEP40\" , \"WPA\" , \"AP\" , \"FREQ_VALID\" , \"ADHOC\" , \"RSN\" , \"CIPHER_TKIP\" , \"CIPHER_WEP104\" , \"CIPHER_CCMP\" , \"FREQ_2GHZ\" ], \"channels\" : [ { \"attenuation\" : 20.0 , \"channel\" : 1 , \"disabled\" : false , \"frequency\" : 2412 , \"noInitiatingRadiation\" : false , \"radarDetection\" : false }, { \"attenuation\" : 20.0 , \"channel\" : 2 , \"disabled\" : false , \"frequency\" : 2417 , \"noInitiatingRadiation\" : false , \"radarDetection\" : false } ], \"countryCode\" : \"00\" , \"driver\" : \"brcmfmac\" , \"driverVersion\" : \"7.45.98.94\" , \"firmwareVersion\" : \"01-3b33decd\" , \"hardwareAddress\" : \"44:55:66:77:88:99\" , \"id\" : \"wlan0\" , \"interfaceIp4Addresses\" : { \"addresses\" : [ { \"address\" : \"172.16.1.1\" , \"prefix\" : 24 } ], \"dnsServerAddresses\" : [] }, \"interfaceName\" : \"wlan0\" , \"mode\" : \"MASTER\" , \"mtu\" : 1500 , \"state\" : \"ACTIVATED\" , \"type\" : \"WIFI\" , \"virtual\" : false }","title":"WifiInterfaceStatus"},{"location":"core-services/network-status-rest-v1/#modeminterfacestatus","text":"Object that contains specific properties to describe the status of a Modem interface. It contains also all of the properties specified by NetworkInterfaceStatus . Properties : model : string manufacturer : string serialNumber : string softwareRevision : string hardwareRevision : string primaryPort : string ports : object ModemPorts supportedModemCapabilities : array array element type: string (enumerated) ModemCapability currentModemCapabilities : array array element type: string (enumerated) ModemCapability powerState : string (enumerated) ModemPowerState supportedModes : array array element type: object ModemModePair currentModes : object ModemModePair supportedBands : array array element type: string (enumerated) ModemBand currentBands : array array element type: string (enumerated) ModemBand gpsSupported : bool availableSims : array array element type: object Sim simLocked : bool bearers : array array element type: object Bearer connectionType : string (enumerated) ModemConnectionType connectionStatus : string (enumerated) ModemConnectionStatus accessTechnologies : array array element type: string (enumerated) AccessTechnology signalQuality : number signalStrength : number registrationStatus : string (enumerated) RegistrationStatus operatorName : string { \"accessTechnologies\" : [ \"LTE\" ], \"autoConnect\" : true , \"availableSims\" : [ { \"active\" : true , \"primary\" : true , \"eSimStatus\" : \"UNKNOWN\" , \"eid\" : \"\" , \"iccid\" : \"1111111111111111111\" , \"imsi\" : \"111111111111111\" , \"operatorName\" : \"MyOperator\" , \"simType\" : \"PHYSICAL\" } ], \"bearers\" : [ { \"apn\" : \"apn.myoperator.com\" , \"bytesReceived\" : 0 , \"bytesTransmitted\" : 0 , \"connected\" : true , \"ipTypes\" : [ \"IPV4\" ], \"name\" : \"wwp11s0f2u3i4\" } ], \"connectionStatus\" : \"CONNECTED\" , \"connectionType\" : \"DirectIP\" , \"currentBands\" : [ \"DCS\" , \"EUTRAN_3\" , \"EUTRAN_19\" , \"EUTRAN_40\" , \"EUTRAN_26\" , \"EUTRAN_28\" , \"EUTRAN_41\" , \"UTRAN_6\" , \"EUTRAN_13\" , \"EUTRAN_25\" , \"EUTRAN_5\" , \"EUTRAN_7\" , \"EUTRAN_8\" , \"UTRAN_2\" , \"EUTRAN_38\" , \"UTRAN_1\" , \"EUTRAN_12\" , \"UTRAN_8\" , \"EUTRAN_18\" , \"UTRAN_19\" , \"G850\" , \"EUTRAN_20\" , \"UTRAN_5\" , \"EUTRAN_1\" , \"EUTRAN_39\" , \"EUTRAN_2\" , \"EUTRAN_4\" , \"EGSM\" , \"PCS\" , \"UTRAN_4\" ], \"currentModemCapabilities\" : [ \"GSM_UMTS\" , \"LTE\" ], \"currentModes\" : { \"modes\" : [ \"MODE_2G\" , \"MODE_3G\" , \"MODE_4G\" ], \"preferredMode\" : \"MODE_4G\" }, \"driver\" : \"qmi_wwan, option1\" , \"driverVersion\" : \"\" , \"firmwareVersion\" : \"\" , \"gpsSupported\" : true , \"hardwareAddress\" : \"00:00:00:00:00:00\" , \"hardwareRevision\" : \"10000\" , \"id\" : \"1-3\" , \"interfaceIp4Addresses\" : { \"addresses\" : [ { \"address\" : \"1.2.3.4\" , \"prefix\" : 30 } ], \"dnsServerAddresses\" : [ \"1.2.3.6\" , \"1.2.3.7\" ], \"gateway\" : \"1.2.3.5\" }, \"interfaceName\" : \"wwp11s0f2u3i4\" , \"manufacturer\" : \"QUALCOMM INCORPORATED\" , \"model\" : \"QUECTEL Mobile Broadband Module\" , \"mtu\" : 1500 , \"operatorName\" : \"MyOperator\" , \"ports\" : { \"cdc-wdm0\" : \"QMI\" , \"ttyUSB0\" : \"QCDM\" , \"ttyUSB1\" : \"GPS\" , \"ttyUSB2\" : \"AT\" , \"ttyUSB3\" : \"AT\" , \"wwp11s0f2u3i4\" : \"NET\" }, \"powerState\" : \"ON\" , \"primaryPort\" : \"cdc-wdm0\" , \"registrationStatus\" : \"HOME\" , \"serialNumber\" : \"111111111111111\" , \"signalQuality\" : 55 , \"signalStrength\" : -80 , \"simLocked\" : true , \"softwareRevision\" : \"EG25GGBR07A08M2G\" , \"state\" : \"ACTIVATED\" , \"supportedBands\" : [ \"DCS\" , \"EUTRAN_3\" , \"EUTRAN_19\" , \"EUTRAN_40\" , \"EUTRAN_26\" , \"EUTRAN_28\" , \"EUTRAN_41\" , \"UTRAN_6\" , \"EUTRAN_13\" , \"EUTRAN_25\" , \"EUTRAN_5\" , \"EUTRAN_7\" , \"EUTRAN_8\" , \"UTRAN_2\" , \"EUTRAN_38\" , \"UTRAN_1\" , \"EUTRAN_12\" , \"UTRAN_8\" , \"EUTRAN_18\" , \"UTRAN_19\" , \"G850\" , \"EUTRAN_20\" , \"UTRAN_5\" , \"EUTRAN_1\" , \"EUTRAN_39\" , \"EUTRAN_2\" , \"EUTRAN_4\" , \"EGSM\" , \"PCS\" , \"UTRAN_4\" ], \"supportedModemCapabilities\" : [ \"NONE\" ], \"supportedModes\" : [ { \"modes\" : [ \"MODE_4G\" ], \"preferredMode\" : \"NONE\" }, { \"modes\" : [ \"MODE_2G\" , \"MODE_3G\" , \"MODE_4G\" ], \"preferredMode\" : \"MODE_4G\" } ], \"type\" : \"MODEM\" , \"virtual\" : false }","title":"ModemInterfaceStatus"},{"location":"core-services/network-status-rest-v1/#networkinterfacestatus","text":"This object contains the common properties contained by the status object reported for a network interface. A network interface is identified by Kura using the id field. It is used to internally manage the interface. The interfaceName, instead, is the IP interface as it may appear on the system. For Ethernet and WiFi interfaces the two values coincide (i.e. eth0, wlp1s0, ...). For modems, instead, the id is typically the usb or pci path, while the interfaceName is the IP interface created when they are connected. When the modem is disconnected the interfaceName can have a different value. Properties : id : string interfaceName : string hardwareAddress : string HardwareAddress driver : string driverVersion : string firmwareVersion : string virtual : bool state : string (enumerated) NetworkInterfaceState autoConnect : bool mtu : number interfaceIp4Addresses : array ( optional ) array element type: object NetworkInterfaceIpAddressStatus interfaceIp6Addresses : array ( optional ) array element type: object NetworkInterfaceIpAddressStatus","title":"NetworkInterfaceStatus"},{"location":"core-services/network-status-rest-v1/#ipaddressstring","text":"Represents an IPv4 or IPv6 addresses as a string.","title":"IPAddressString"},{"location":"core-services/network-status-rest-v1/#hardwareaddress","text":"Represents an hardware address as its bytes reported as two characters hexadecimal strings separated by the ':' character. e.g. 00:11:22:33:A4:FC:BB.","title":"HardwareAddress"},{"location":"core-services/network-status-rest-v1/#networkinterfaceipaddress","text":"This object describes an IP address with its prefix. It can be used for IPv4 or IPv6 addresses. Properties : address : string IPAddressString prefix : number","title":"NetworkInterfaceIpAddress"},{"location":"core-services/network-status-rest-v1/#networkinterfaceipaddressstatus","text":"This class describes the IP address status of a network interface: a list of IP addresses, an optional gateway and a list of DNS servers address. It can be used for IPv4 or IPv6 addresses. Properties : addresses : array array element type: object NetworkInterfaceIpAddress gateway : string ( optional This field can be missing if the interface has no gateway.) IPAddressString dnsServerAddresses : array array element type: string IPAddressString","title":"NetworkInterfaceIpAddressStatus"},{"location":"core-services/network-status-rest-v1/#wifichannel","text":"This class represent a WiFi channel, providing the channel number, frequency, status and other useful information. Properties : channel : number frequency : number disabled : bool ( optional ) attenuation : number ( optional ) noInitiatingRadiation : bool ( optional ) radarDetection : bool ( optional )","title":"WifiChannel"},{"location":"core-services/network-status-rest-v1/#wifiaccesspoint","text":"This object describes a Wifi Access Point. It can be used both for describing a detected AP after a WiFi scan when in Station mode and the provided AP when in Master (or Access Point) mode. Properties : ssid : string The Service Set IDentifier of the WiFi network hardwareAddress : string HardwareAddress channel : object WifiChannel mode : string (enumerated) WifiMode maxBitrate : number The maximum bitrate this access point is capable of. signalQuality : number The current signal quality of the access point in percentage. signalStrength : number The current signal strength of the access point in dBm. wpaSecurity : array The WPA capabilities of the access point array element type: string (enumerated) WifiSecurity rsnSecurity : array The RSN capabilities of the access point array element type: string (enumerated) WifiSecurity","title":"WifiAccessPoint"},{"location":"core-services/network-status-rest-v1/#modemmodepair","text":"This object represents a pair of Modem Mode list and a preferred one. Properties : modes : array array element type: string (enumerated) ModemMode preferredMode : string (enumerated) ModemMode","title":"ModemModePair"},{"location":"core-services/network-status-rest-v1/#sim","text":"This class contains all relevant properties to describe a SIM (Subscriber Identity Module). Properties : active : bool primary : bool iccid : string imsi : string eid : string operatorName : string simType : string (enumerated) SimType eSimStatus : string (enumerated) ESimStatus","title":"Sim"},{"location":"core-services/network-status-rest-v1/#bearer","text":"This object describes the Bearer or Context associated to a modem connection. Properties : name : string connected : bool apn : string ipTypes : array array element type: string (enumerated) BearerIpType bytesTransmitted : number bytesReceived : number","title":"Bearer"},{"location":"core-services/network-status-rest-v1/#modemports","text":"An object representing a set of modem ports. The members of this object represent modem ports, the member names represent the modem port name. This object can have a variable number of members. Properties : propertyName : string (enumerated) ModemPortType","title":"ModemPorts"},{"location":"core-services/network-status-rest-v1/#networkinterfacetype","text":"The type of a network interface. Possible values UNKNOWN : The device type is unknown ETHERNET : The device is a wired Ethernet device. WIFI : The device is an 802.11 WiFi device. UNUSED1 UNUSED2 BT : The device is a Bluetooth device. OLPC_MESH : The device is an OLPC mesh networking device. WIMAX : The device is an 802.16e Mobile WiMAX device. MODEM : The device is a modem supporting one or more of analog telephone, CDMA/EVDO, GSM/UMTS/HSPA, or LTE standards to access a cellular or wireline data network. INFINIBAND : The device is an IP-capable InfiniBand interface. BOND : The device is a bond master interface. VLAN : The device is a VLAN interface. ADSL : The device is an ADSL device. BRIDGE : The device is a bridge master interface. GENERIC : This is a generic support for unrecognized device types. TEAM : The device is a team master interface. TUN : The device is a TUN or TAP interface. TUNNEL : The device is an IP tunnel interface. MACVLAN : The device is a MACVLAN interface. VXLAN : The device is a VXLAN interface. VETH : The device is a VETH interface. MACSEC : The device is a MACsec interface. DUMMY : The device is a dummy interface. PPP : The device is a PPP interface. OVS_INTERFACE : The device is a Open vSwitch interface. OVS_PORT : The device is a Open vSwitch port OVS_BRIDGE : The device is a Open vSwitch bridge. WPAN : The device is a IEEE 802.15.4 (WPAN) MAC Layer Device. SIXLOWPAN : The device is a 6LoWPAN interface. WIREGUARD : The device is a WireGuard interface. WIFI_P2P : The device is an 802.11 Wi-Fi P2P device. VRF : The device is a VRF (Virtual Routing and Forwarding) interface. LOOPBACK : The device is a loopback device.","title":"NetworkInterfaceType"},{"location":"core-services/network-status-rest-v1/#networkinterfacestate","text":"The state of a network interface. Possible values UNKNOWN : The device is in an unknown state. UNMANAGED : The device cannot be used (carrier off, rfkill, etc). UNAVAILABLE : The device is not connected. DISCONNECTED : The device is preparing to connect. PREPARE : The device is being configured. CONFIG : The device is awaiting secrets necessary to continue connection. NEED_AUTH : The IP settings of the device are being requested and configured. IP_CONFIG : The device's IP connectivity ability is being determined. IP_CHECK : The device is waiting for secondary connections to be activated. SECONDARIES : The device is waiting for secondary connections to be activated. ACTIVATED : The device is active. DEACTIVATING : The device's network connection is being turn down. FAILED : The device is in a failure state following an attempt to activate it.","title":"NetworkInterfaceState"},{"location":"core-services/network-status-rest-v1/#wificapability","text":"The capability of a WiFi interface. Possible values NONE : The device has no encryption/authentication capabilities CIPHER_WEP40 : The device supports 40/64-bit WEP encryption. CIPHER_WEP104 : The device supports 104/128-bit WEP encryption. CIPHER_TKIP : The device supports the TKIP encryption. CIPHER_CCMP : The device supports the AES/CCMP encryption. WPA : The device supports the WPA1 encryption/authentication protocol. RSN : The device supports the WPA2/RSN encryption/authentication protocol. AP : The device supports Access Point mode. ADHOC : The device supports Ad-Hoc mode. FREQ_VALID : The device reports frequency capabilities. FREQ_2GHZ : The device supports 2.4GHz frequencies. FREQ_5GHZ : The device supports 5GHz frequencies. MESH : The device supports mesh points. IBSS_RSN : The device supports WPA2 in IBSS networks","title":"WifiCapability"},{"location":"core-services/network-status-rest-v1/#wifimode","text":"Modes of operation for wifi interfaces Possible values UNKNOWN : Mode is unknown. ADHOC : Uncoordinated network without central infrastructure. INFRA : Client mode - Coordinated network with one or more central controllers. MASTER : Access Point Mode - Coordinated network with one or more central controllers.","title":"WifiMode"},{"location":"core-services/network-status-rest-v1/#wifisecurity","text":"Flags describing the security capabilities of an access point. Possible values NONE : None PAIR_WEP40 : Supports pairwise 40-bit WEP encryption. PAIR_WEP104 : Supports pairwise 104-bit WEP encryption. PAIR_TKIP : Supports pairwise TKIP encryption. PAIR_CCMP : Supports pairwise CCMP encryption. GROUP_WEP40 : Supports a group 40-bit WEP cipher. GROUP_WEP104 : Supports a group 104-bit WEP cipher. GROUP_TKIP : Supports a group TKIP cipher. GROUP_CCMP : Supports a group CCMP cipher. KEY_MGMT_PSK : Supports PSK key management. KEY_MGMT_802_1X : Supports 802.1x key management. SECURITY_NONE : Supports no encryption. SECURITY_WEP : Supports WEP encryption. SECURITY_WPA : Supports WPA encryption. SECURITY_WPA2 : Supports WPA2 encryption. SECURITY_WPA_WPA2 : Supports WPA and WPA2 encryption.","title":"WifiSecurity"},{"location":"core-services/network-status-rest-v1/#modemporttype","text":"The type of a modem port. Possible values UNKNOWN NET AT QCDM GPS QMI MBIM AUDIO IGNORED","title":"ModemPortType"},{"location":"core-services/network-status-rest-v1/#modemcapability","text":"The generic access technologies families supported by a modem. Possible values NONE : The modem has no capabilities. POTS : The modem supports the Plain Old Telephone Service (analog wired telephone network). EVDO : The modem supports EVDO revision 0, A or B. GSM_UMTS : The modem supports at least one of GSM, GPRS, EDGE, UMTS, HSDPA, HSUPA or HSPA+ technologies. LTE : The modem has LTE capabilities. IRIDIUM : The modem supports Iridium technology. FIVE_GNR : The modem supports 5GNR. TDS : The modem supports TDS. ANY : The modem supports all capabilities.","title":"ModemCapability"},{"location":"core-services/network-status-rest-v1/#modemmode","text":"The generic access mode a modem supports. Possible values NONE CS MODE_2G MODE_3G MODE_4G MODE_5G ANY","title":"ModemMode"},{"location":"core-services/network-status-rest-v1/#modemband","text":"The radio bands supported by a modem when connected to a mobile network. Possible values UNKNOWN EGSM DCS PCS G850 UTRAN_1 UTRAN_3 UTRAN_4 UTRAN_6 UTRAN_5 UTRAN_8 UTRAN_9 UTRAN_2 UTRAN_7 G450 G480 G750 G380 G410 G710 G810 EUTRAN_1 EUTRAN_2 EUTRAN_3 EUTRAN_4 EUTRAN_5 EUTRAN_6 EUTRAN_7 EUTRAN_8 EUTRAN_9 EUTRAN_10 EUTRAN_11 EUTRAN_12 EUTRAN_13 EUTRAN_14 EUTRAN_17 EUTRAN_18 EUTRAN_19 EUTRAN_20 EUTRAN_21 EUTRAN_22 EUTRAN_23 EUTRAN_24 EUTRAN_25 EUTRAN_26 EUTRAN_27 EUTRAN_28 EUTRAN_29 EUTRAN_30 EUTRAN_31 EUTRAN_32 EUTRAN_33 EUTRAN_34 EUTRAN_35 EUTRAN_36 EUTRAN_37 EUTRAN_38 EUTRAN_39 EUTRAN_40 EUTRAN_41 EUTRAN_42 EUTRAN_43 EUTRAN_44 EUTRAN_45 EUTRAN_46 EUTRAN_47 EUTRAN_48 EUTRAN_49 EUTRAN_50 EUTRAN_51 EUTRAN_52 EUTRAN_53 EUTRAN_54 EUTRAN_55 EUTRAN_56 EUTRAN_57 EUTRAN_58 EUTRAN_59 EUTRAN_60 EUTRAN_61 EUTRAN_62 EUTRAN_63 EUTRAN_64 EUTRAN_65 EUTRAN_66 EUTRAN_67 EUTRAN_68 EUTRAN_69 EUTRAN_70 EUTRAN_71 EUTRAN_85 CDMA_BC0 CDMA_BC1 CDMA_BC2 CDMA_BC3 CDMA_BC4 CDMA_BC5 CDMA_BC6 CDMA_BC7 CDMA_BC8 CDMA_BC9 CDMA_BC10 CDMA_BC11 CDMA_BC12 CDMA_BC13 CDMA_BC14 CDMA_BC15 CDMA_BC16 CDMA_BC17 CDMA_BC18 CDMA_BC19 UTRAN_10 UTRAN_11 UTRAN_12 UTRAN_13 UTRAN_14 UTRAN_19 UTRAN_20 UTRAN_21 UTRAN_22 UTRAN_25 UTRAN_26 UTRAN_32 ANY NGRAN_1 NGRAN_2 NGRAN_3 NGRAN_5 NGRAN_7 NGRAN_8 NGRAN_12 NGRAN_13 NGRAN_14 NGRAN_18 NGRAN_20 NGRAN_25 NGRAN_26 NGRAN_28 NGRAN_29 NGRAN_30 NGRAN_34 NGRAN_38 NGRAN_39 NGRAN_40 NGRAN_41 NGRAN_48 NGRAN_50 NGRAN_51 NGRAN_53 NGRAN_65 NGRAN_66 NGRAN_70 NGRAN_71 NGRAN_74 NGRAN_75 NGRAN_76 NGRAN_77 NGRAN_78 NGRAN_79 NGRAN_80 NGRAN_81 NGRAN_82 NGRAN_83 NGRAN_84 NGRAN_86 NGRAN_89 NGRAN_90 NGRAN_91 NGRAN_92 NGRAN_93 NGRAN_94 NGRAN_95 NGRAN_257 NGRAN_258 NGRAN_260 NGRAN_261","title":"ModemBand"},{"location":"core-services/network-status-rest-v1/#simtype","text":"The SIM (Subscriber Identity Module) type. Possible values UNKNOWN PHYSICAL ESIM","title":"SimType"},{"location":"core-services/network-status-rest-v1/#esimstatus","text":"The status of an ESIM. Possible values UNKNOWN NO_PROFILES WITH_PROFILES","title":"ESimStatus"},{"location":"core-services/network-status-rest-v1/#beareriptype","text":"The type of Bearer or Context associated to a modem connection. Possible values NONE IPV4 IPV6 IPV4V6 NON_IP ANY","title":"BearerIpType"},{"location":"core-services/network-status-rest-v1/#modemconnectiontype","text":"Possible values PPP : Point to Point Protocol DirectIP : Direct IP","title":"ModemConnectionType"},{"location":"core-services/network-status-rest-v1/#modemconnectionstatus","text":"The status of a modem. Possible values FAILED : The modem is unavailable UNKNOWN : The modem is in an unknown state. INITIALIZING : The modem is being initialised. LOCKED : The modem is locked. DISABLED : The modem is disabled and powered off. DISABLING : The modem is disabling. ENABLING : The modem is enabling.. ENABLED : The modem is enabled but not registered to a network provider. SEARCHING : The modem is searching for a network provider. REGISTERED : The modem is registered to a network provider. DISCONNECTING : The modem is disconnecting. CONNECTING : The modem is connecting. CONNECTED : The modem is connected.","title":"ModemConnectionStatus"},{"location":"core-services/network-status-rest-v1/#accesstechnology","text":"The specific technology types used when a modem is connected or registered to a network. Possible values UNKNOWN POTS GSM GSM_COMPACT GPRS EDGE UMTS HSDPA HSUPA HSPA HSPA_PLUS ONEXRTT EVDO0 EVDOA EVDOB LTE FIVEGNR LTE_CAT_M LTE_NB_IOT ANY","title":"AccessTechnology"},{"location":"core-services/network-status-rest-v1/#registrationstatus","text":"The registration status of a modem when connected to a mobile network. Possible values IDLE HOME SEARCHING DENIED UNKNOWN ROAMING HOME_SMS_ONLY ROAMING_SMS_ONLY EMERGENCY_ONLY HOME_CSFB_NOT_PREFERRED ROAMING_CSFB_NOT_PREFERRED ATTACHED_RLOS","title":"RegistrationStatus"},{"location":"core-services/network-status-rest-v1/#failurereport","text":"An object reporting a failure while retrieving the status of a specific network interface Properties : interfaceId : string The identifier of the interface whose status cannot be retrieved. reason : string A message describing the reason of the failure.","title":"FailureReport"},{"location":"core-services/network-status-rest-v1/#genericfailurereport","text":"An object reporting a failure message. Properties : message : string A message describing the failure.","title":"GenericFailureReport"},{"location":"core-services/nvidia-triton-server-inference-engine/","text":"Nvidia\u2122 Triton Server Inference Engine The Nvidia\u2122 Triton Server is an open-source inference service software that enables the user to deploy trained AI models from any framework on GPU or CPU infrastructure. It supports all major frameworks like TensorFlow, TensorRT, PyTorch, ONNX Runtime, and even custom framework backend. With specific backends, it is also possible to run Python scripts, mainly for pre-and post-processing purposes, and exploit the DALI building block for optimized operations. For more detail about the Triton Server, please refer to the official website . Kura provides three components for exposing the Triton Server service functionality which implement the inference engine APIs and provides methods for interacting with a local or remote Nvidia\u2122 Triton Server: TritonServerRemoteService : provides methods for interacting with a remote Nvidia\u2122 Triton Server without managing the server lifecycle. Can be used both for connecting to a remote instance or a local non-managed instance. It exposes a simpler but more limited configuration. TritonServerNativeService : provides methods for interacting with a local native Nvidia\u2122 Triton Server. Requires the Triton Server executable to be already available on the device and offers more options and features (like AI Model Encryption). TritonServerContainerService : provides methods for interacting with a local container running Nvidia\u2122 Triton Server. Requires the Triton Server container image to be already available on the device and offers more options and features (like AI Model Encryption). TritonServerService : provides methods for interacting with a local or remote Nvidia\u2122 Triton Server within the same component. Note : deprecated since 5.2.0 Nvidia\u2122 Triton Server installation Before running Kura's Triton Server Service, you must install the Triton Inference Server. Here you can find the necessary steps for the available suggested installation methods. Native Triton installation on Jetson devices A release of Triton for JetPack is provided in the tar file in the Triton Inference Server release notes . Full documentation is available here . Installation steps: Before running the executable you need to install the Runtime Dependencies for Triton . After doing so you can extract the tar file and run the executable in the bin folder. It is highly recommended to add the tritonserver executable to your path or symlinking the executable to /usr/local/bin . Triton Docker image installation Before you can use the Triton Docker image you must install Docker . If you plan on using a GPU for inference you must also install the NVIDIA Container Toolkit . Pull the image using the following command. $ docker pull nvcr.io/nvidia/tritonserver:-py3 Where is the version of Triton that you want to pull. Native Triton installation on supported devices The official docs mention the possibility to perform a native installation on supported platform by extracting the binaries from the Docker images. To do so you must install the necessary dependencies (some can be found in the Jetson runtime dependencies docs ) on the system. For Triton to support NVIDIA GPUs you must install CUDA, cuBLAS and cuDNN referencing the support matrix . Note For Python models the libraries available to the Python model are the ones available for the user running the Triton server. Therefore you'll need to install the libraries through pip for the kurad user. Triton Server setup The Triton Inference Server serves models from one or more model repositories that are specified when the server is started. The model repository is the directory where you place the models that you want Triton to serve. Be sure to follow the instructions to setup the model repository directory. Further information about an example Triton Server setup can be found in the official documentation . Triton Server Remote Service component The Kura Triton Server Remote Service component is the implementation of the inference engine APIs and provides methods for interacting with a remote (i.e. unmnanaged) Nvidia\u2122 Triton Server. As presented below, the component enables the user to communicate to an external server to load specific models. With this component the server lifecycle (startup, shutdown) won't be handled by Kura and it's the user responsibility to make it available to Kura for connecting. The parameters used to configure the Triton Service are the following: Nvidia Triton Server address : the address of the Nvidia Triton Server. Nvidia Triton Server ports : the ports used to connect to the server for HTTP, GRPC, and Metrics services. Inference Models : a comma-separated list of inference model names that the server will load. The models have to be already present in the filesystem where the server is running. This option simply tells the server to load the given models from a local or remote repository. Timeout (in seconds) for time consuming tasks : Timeout (in seconds) for time consuming tasks like server startup, shutdown or model load. If the task exceeds the timeout, the operation will be terminated with an error. Max. GRPC message size (bytes) : this field controls the maximum allowed size for the GRPC calls to the server instance. By default, size of 4194304 bytes (= 4.19 MB) is used. Increase this value to be able to send large amounts of data as input to the Triton server (like Full HD images). The Kura logs will show the following error when exceeding such limit: io.grpc.StatusRuntimeException: RESOURCE_EXHAUSTED: gRPC message exceeds maximum size 4194304 Note Pay attention on the ports used for communicating with the Triton Server. The default ports are the 8000-8002, but these are tipically used by Kura for debug purposes. Triton Server Native Service component The Kura Triton Server component is the implementation of the inference engine APIs and provides methods for interacting with a local native Nvidia\u2122 Triton Server. As presented below, the component enables the user to configure a local server running on the gateway and handles its lifecycle. This operating mode supports more features for interacting with the server like the AI Model Encryption . Note Requirement : tritonserver executable needs to be available in the path to the kurad user. Be sure to have a working Triton Server installation before configuring the local native Triton Server instance through Kura UI. The parameters used to configure the Triton Service are the following: Nvidia Triton Server ports : the ports used to connect to the server for HTTP, GRPC, and Metrics services. Local model repository path : Specify the path on the filesystem where the models are stored. Local model decryption password : Specify the password to be used for decrypting models stored in the model repository. If none is specified, models are supposed to be plaintext. Inference Models : a comma-separated list of inference model names that the server will load. The models have to be already present in the filesystem where the server is running. This option simply tells the server to load the given models from a local or remote repository. Local backends path : Specify the path on the filesystem where the backends are stored. Optional configuration for the local backends : A semi-colon separated list of configuration for the backends. i.e. tensorflow,version=2;tensorflow,allow-soft-placement=false Timeout (in seconds) for time consuming tasks : Timeout (in seconds) for time consuming tasks like server startup, shutdown or model load. If the task exceeds the timeout, the operation will be terminated with an error. Max. GRPC message size (bytes) : this field controls the maximum allowed size for the GRPC calls to the server instance. Note Pay attention on the ports used for communicating with the Triton Server. The default ports are the 8000-8002, but these are tipically used by Kura for debug purposes. Triton Server Container Service component The Kura Triton Server component is the implementation of the inference engine APIs and provides methods for interacting with a local container running the Nvidia\u2122 Triton Server. As presented below, the component enables the user to configure a local server running on the gateway and handles its lifecycle. This operating mode supports more features for interacting with the server like the AI Model Encryption . Note Requirement : 1. Triton Server container image already installed on the device. For instructions refer to the installation section in this page. 2. Kura's Container Orchestration Service enabled. The parameters used to configure the Triton Service are the following: Container Image : The image the container will be created with. Container Image Tag : Describes which image version that should be used for creating the container. Nvidia Triton Server ports : the ports used to connect to the server for HTTP, GRPC, and Metrics services. Local model repository path : Specify the path on the filesystem where the models are stored. Local model decryption password : Specify the password to be used for decrypting models stored in the model repository. If none is specified, models are supposed to be plaintext. Inference Models : a comma-separated list of inference model names that the server will load. The models have to be already present in the filesystem where the server is running. This option simply tells the server to load the given models from a local or remote repository. Optional configuration for the local backends : A semi-colon separated list of configuration for the backends. i.e. tensorflow,version=2;tensorflow,allow-soft-placement=false Memory : The maximum amount of memory the container can use in bytes. Set it as a positive integer, optionally followed by a suffix of b, k, m, g, to indicate bytes, kilobytes, megabytes, or gigabytes. The minimum allowed value is platform dependent (i.e. 6m). If left empty, the memory assigned to the container will be set to a default value by the native container orchestrator. CPUs : Specify how many CPUs the Triton container can use. Decimal values are allowed, so if set to 1.5, the container will use at most one and a half cpu resource. GPUs : Specify how many Nvidia GPUs the Triton container can use. Allowed values are 'all' or an integer number. If there's no Nvidia GPU installed, leave the field empty. Timeout (in seconds) for time consuming tasks : Timeout (in seconds) for time consuming tasks like server startup, shutdown or model load. If the task exceeds the timeout, the operation will be terminated with an error. Max. GRPC message size (bytes) : this field controls the maximum allowed size for the GRPC calls to the server instance. Note Pay attention on the ports used for communicating with the Triton Server. The default ports are the 8000-8002, but these are typically used by Kura for debug purposes. Triton Server Service component [deprecated since 5.2.0] The Kura Triton Server component is the implementation of the inference engine APIs and provides methods for interacting with a local or remote Nvidia\u2122 Triton Server. As presented below, the component enables the user to configure a local server running on the gateway or to communicate to an external server to load specific models. The parameters used to configure the Triton Service are the following: Local Nvidia Triton Server : If enabled, a local native Nvidia Triton Server is started on the gateway. In this case, the model repository and backends path are mandatory. Moreover, the server address property is overridden and set to localhost. Be aware that the Triton Server has to be already installed on the system. Nvidia Triton Server address : the address of the Nvidia Triton Server. Nvidia Triton Server ports : the ports used to connect to the server for HTTP, GRPC, and Metrics services. Local model repository path : Only for a local instance, specify the path on the filesystem where the models are stored. Local model decryption password : Only for local instance, specify the password to be used for decrypting models stored in the model repository. If none is specified, models are supposed to be plaintext. Inference Models : a comma-separated list of inference model names that the server will load. The models have to be already present in the filesystem where the server is running. This option simply tells the server to load the given models from a local or remote repository. Local backends path : Only for a local instance, specify the path on the filesystem where the backends are stored. Optional configuration for the local backends : Only for local instance, a semi-colon separated list of configuration for the backends. i.e. tensorflow,version=2;tensorflow,allow-soft-placement=false Timeout (in seconds) for time consuming tasks : Timeout (in seconds) for time consuming tasks like server startup, shutdown or model load. If the task exceeds the timeout, the operation will be terminated with an error. Max. GRPC message size (bytes) : this field controls the maximum allowed size for the GRPC calls to the server instance. Note Pay attention on the ports used for communicating with the Triton Server. The default ports are the 8000-8002, but these are tipically used by Kura for debug purposes. Configuration for a local native Triton Server with Triton Server Service component [deprecated since 5.2.0] Note Requirement : tritonserver executable needs to be available in the path to the kurad user. Be sure to have a working Triton Server installation before configuring the local native Triton Server instance through Kura UI. When the Local Nvidia Triton Server option is set to true, a local instance of the Nvidia\u2122 Triton Server is started on the gateway. The following configuration is required: Local Nvidia Triton Server : true Nvidia Triton Server address : localhost Nvidia Triton Server ports : mandatory Local model repository path : mandatory Inference Models : mandatory. Note that the models have to be already present on the filesystem. Local backends path : mandatory The typical command used to start the Triton Server is like this: tritonserver --model-repository = \\ --backend-directory = \\ --backend-config = \\ --http-port = \\ --grpc-port = \\ --metrics-port = \\ --model-control-mode = explicit \\ --load-model = \\ --load-model = \\ ... Configuration for a local Triton Server running in a Docker container with Triton Server Service component [deprecated since 5.2.0] If the Nvidia\u2122 Triton Server is running as a Docker container in the gateway, the following configuration is required: Local Nvidia Triton Server : false Nvidia Triton Server address : localhost Nvidia Triton Server ports : \\ Inference Models : \\. The models have to be already present on the filesystem. In order to correctly load the models at runtime, configure the server with the --model-control-mode=explicit option. The typical command used for running the docker container is as follows. Note the forward of the ports to not interfere with Kura. docker run --rm \\ -p4000:8000 \\ -p4001:8001 \\ -p4002:8002 \\ --shm-size = 150m \\ -v path/to/models:/models \\ nvcr.io/nvidia/tritonserver: [ version ] \\ tritonserver --model-repository = /models --model-control-mode = explicit Configuration for a remote Triton Server with Triton Server Service component [deprecated since 5.2.0] When the Nvidia\u2122 Triton Server is running on a remote server, the following configuration is needed: Local Nvidia Triton Server : false Nvidia Triton Server address : mandatory Nvidia Triton Server ports : mandatory ** Inference Models**: mandatory. The models have to be already present on the filesystem. AI Model Encryption Support For ensuring inference integrity and providing copyright protection of deep-learning models on edge devices, Kura provides decryption capabilities for trained models to be served through the Triton Server. How it works Prerequisites : a deep-learning trained model (or more) exists with the corresponding necessary configuration for running on the Triton Server without encryption. A folder containing the required files (model, configuration etc) has been tested on a Triton Server. Restrictions : if model encryption is used, the following restrictions apply: model encryption support is only available for a local Triton Server instance all models in the folder containing the encrypted models must be encrypted all models must be encrypted with OpenPGP-compliant AES 256 cipher algorithm all models must be encrypted with the same password Once the development of the deep-learning model is complete, the developer who wants to deploy the model on the edge device in a secure manner can proceed with encrypting the Triton model using the procedure detailed below. After encrypting the model he/she can transfer the file on the edge device using his/her preferred method. Kura will keep the stored model protected at all times and have the model decrypted in runtime only for use by the Inference Server Runtime. As soon as the model is correctly loaded into memory the decrypted model will be removed from the filesystem. As an additional security measure, the Model Repository containing the decrypted models will be stored in a temporary subfolder and will feature restrictive permission such that only Kura, the Inference Server and the root user will be able to access it. Encryption procedure Given a trained model inside the folder tf_autoencoder_fp32 (for example) with the following layout (see the official documentation for details): tf_autoencoder_fp32 \u251c\u2500\u2500 1 \u2502 \u2514\u2500\u2500 model.savedmodel \u2502 \u251c\u2500\u2500 assets \u2502 \u251c\u2500\u2500 keras_metadata.pb \u2502 \u251c\u2500\u2500 saved_model.pb \u2502 \u2514\u2500\u2500 variables \u2502 \u251c\u2500\u2500 variables.data-00000-of-00001 \u2502 \u2514\u2500\u2500 variables.index \u2514\u2500\u2500 config.pbtxt Compress the model into a zip archive with the following command: zip -vr tf_autoencoder_fp32.zip tf_autoencoder_fp32/ then encrypt it with the AES 256 algorithm using the following gpg command: gpg --armor --symmetric --cipher-algo AES256 tf_autoencoder_fp32.zip The resulting archive tf_autoencoder_fp32.zip.asc can be transferred to the Local Model Repository Path on the target machine and will be decrypted by Kura.","title":"Nvidia\u2122 Triton Server Inference Engine"},{"location":"core-services/nvidia-triton-server-inference-engine/#nvidiatm-triton-server-inference-engine","text":"The Nvidia\u2122 Triton Server is an open-source inference service software that enables the user to deploy trained AI models from any framework on GPU or CPU infrastructure. It supports all major frameworks like TensorFlow, TensorRT, PyTorch, ONNX Runtime, and even custom framework backend. With specific backends, it is also possible to run Python scripts, mainly for pre-and post-processing purposes, and exploit the DALI building block for optimized operations. For more detail about the Triton Server, please refer to the official website . Kura provides three components for exposing the Triton Server service functionality which implement the inference engine APIs and provides methods for interacting with a local or remote Nvidia\u2122 Triton Server: TritonServerRemoteService : provides methods for interacting with a remote Nvidia\u2122 Triton Server without managing the server lifecycle. Can be used both for connecting to a remote instance or a local non-managed instance. It exposes a simpler but more limited configuration. TritonServerNativeService : provides methods for interacting with a local native Nvidia\u2122 Triton Server. Requires the Triton Server executable to be already available on the device and offers more options and features (like AI Model Encryption). TritonServerContainerService : provides methods for interacting with a local container running Nvidia\u2122 Triton Server. Requires the Triton Server container image to be already available on the device and offers more options and features (like AI Model Encryption). TritonServerService : provides methods for interacting with a local or remote Nvidia\u2122 Triton Server within the same component. Note : deprecated since 5.2.0","title":"Nvidia\u2122 Triton Server Inference Engine"},{"location":"core-services/nvidia-triton-server-inference-engine/#nvidiatm-triton-server-installation","text":"Before running Kura's Triton Server Service, you must install the Triton Inference Server. Here you can find the necessary steps for the available suggested installation methods.","title":"Nvidia\u2122 Triton Server installation"},{"location":"core-services/nvidia-triton-server-inference-engine/#native-triton-installation-on-jetson-devices","text":"A release of Triton for JetPack is provided in the tar file in the Triton Inference Server release notes . Full documentation is available here . Installation steps: Before running the executable you need to install the Runtime Dependencies for Triton . After doing so you can extract the tar file and run the executable in the bin folder. It is highly recommended to add the tritonserver executable to your path or symlinking the executable to /usr/local/bin .","title":"Native Triton installation on Jetson devices"},{"location":"core-services/nvidia-triton-server-inference-engine/#triton-docker-image-installation","text":"Before you can use the Triton Docker image you must install Docker . If you plan on using a GPU for inference you must also install the NVIDIA Container Toolkit . Pull the image using the following command. $ docker pull nvcr.io/nvidia/tritonserver:-py3 Where is the version of Triton that you want to pull.","title":"Triton Docker image installation"},{"location":"core-services/nvidia-triton-server-inference-engine/#native-triton-installation-on-supported-devices","text":"The official docs mention the possibility to perform a native installation on supported platform by extracting the binaries from the Docker images. To do so you must install the necessary dependencies (some can be found in the Jetson runtime dependencies docs ) on the system. For Triton to support NVIDIA GPUs you must install CUDA, cuBLAS and cuDNN referencing the support matrix . Note For Python models the libraries available to the Python model are the ones available for the user running the Triton server. Therefore you'll need to install the libraries through pip for the kurad user.","title":"Native Triton installation on supported devices"},{"location":"core-services/nvidia-triton-server-inference-engine/#triton-server-setup","text":"The Triton Inference Server serves models from one or more model repositories that are specified when the server is started. The model repository is the directory where you place the models that you want Triton to serve. Be sure to follow the instructions to setup the model repository directory. Further information about an example Triton Server setup can be found in the official documentation .","title":"Triton Server setup"},{"location":"core-services/nvidia-triton-server-inference-engine/#triton-server-remote-service-component","text":"The Kura Triton Server Remote Service component is the implementation of the inference engine APIs and provides methods for interacting with a remote (i.e. unmnanaged) Nvidia\u2122 Triton Server. As presented below, the component enables the user to communicate to an external server to load specific models. With this component the server lifecycle (startup, shutdown) won't be handled by Kura and it's the user responsibility to make it available to Kura for connecting. The parameters used to configure the Triton Service are the following: Nvidia Triton Server address : the address of the Nvidia Triton Server. Nvidia Triton Server ports : the ports used to connect to the server for HTTP, GRPC, and Metrics services. Inference Models : a comma-separated list of inference model names that the server will load. The models have to be already present in the filesystem where the server is running. This option simply tells the server to load the given models from a local or remote repository. Timeout (in seconds) for time consuming tasks : Timeout (in seconds) for time consuming tasks like server startup, shutdown or model load. If the task exceeds the timeout, the operation will be terminated with an error. Max. GRPC message size (bytes) : this field controls the maximum allowed size for the GRPC calls to the server instance. By default, size of 4194304 bytes (= 4.19 MB) is used. Increase this value to be able to send large amounts of data as input to the Triton server (like Full HD images). The Kura logs will show the following error when exceeding such limit: io.grpc.StatusRuntimeException: RESOURCE_EXHAUSTED: gRPC message exceeds maximum size 4194304 Note Pay attention on the ports used for communicating with the Triton Server. The default ports are the 8000-8002, but these are tipically used by Kura for debug purposes.","title":"Triton Server Remote Service component"},{"location":"core-services/nvidia-triton-server-inference-engine/#triton-server-native-service-component","text":"The Kura Triton Server component is the implementation of the inference engine APIs and provides methods for interacting with a local native Nvidia\u2122 Triton Server. As presented below, the component enables the user to configure a local server running on the gateway and handles its lifecycle. This operating mode supports more features for interacting with the server like the AI Model Encryption . Note Requirement : tritonserver executable needs to be available in the path to the kurad user. Be sure to have a working Triton Server installation before configuring the local native Triton Server instance through Kura UI. The parameters used to configure the Triton Service are the following: Nvidia Triton Server ports : the ports used to connect to the server for HTTP, GRPC, and Metrics services. Local model repository path : Specify the path on the filesystem where the models are stored. Local model decryption password : Specify the password to be used for decrypting models stored in the model repository. If none is specified, models are supposed to be plaintext. Inference Models : a comma-separated list of inference model names that the server will load. The models have to be already present in the filesystem where the server is running. This option simply tells the server to load the given models from a local or remote repository. Local backends path : Specify the path on the filesystem where the backends are stored. Optional configuration for the local backends : A semi-colon separated list of configuration for the backends. i.e. tensorflow,version=2;tensorflow,allow-soft-placement=false Timeout (in seconds) for time consuming tasks : Timeout (in seconds) for time consuming tasks like server startup, shutdown or model load. If the task exceeds the timeout, the operation will be terminated with an error. Max. GRPC message size (bytes) : this field controls the maximum allowed size for the GRPC calls to the server instance. Note Pay attention on the ports used for communicating with the Triton Server. The default ports are the 8000-8002, but these are tipically used by Kura for debug purposes.","title":"Triton Server Native Service component"},{"location":"core-services/nvidia-triton-server-inference-engine/#triton-server-container-service-component","text":"The Kura Triton Server component is the implementation of the inference engine APIs and provides methods for interacting with a local container running the Nvidia\u2122 Triton Server. As presented below, the component enables the user to configure a local server running on the gateway and handles its lifecycle. This operating mode supports more features for interacting with the server like the AI Model Encryption . Note Requirement : 1. Triton Server container image already installed on the device. For instructions refer to the installation section in this page. 2. Kura's Container Orchestration Service enabled. The parameters used to configure the Triton Service are the following: Container Image : The image the container will be created with. Container Image Tag : Describes which image version that should be used for creating the container. Nvidia Triton Server ports : the ports used to connect to the server for HTTP, GRPC, and Metrics services. Local model repository path : Specify the path on the filesystem where the models are stored. Local model decryption password : Specify the password to be used for decrypting models stored in the model repository. If none is specified, models are supposed to be plaintext. Inference Models : a comma-separated list of inference model names that the server will load. The models have to be already present in the filesystem where the server is running. This option simply tells the server to load the given models from a local or remote repository. Optional configuration for the local backends : A semi-colon separated list of configuration for the backends. i.e. tensorflow,version=2;tensorflow,allow-soft-placement=false Memory : The maximum amount of memory the container can use in bytes. Set it as a positive integer, optionally followed by a suffix of b, k, m, g, to indicate bytes, kilobytes, megabytes, or gigabytes. The minimum allowed value is platform dependent (i.e. 6m). If left empty, the memory assigned to the container will be set to a default value by the native container orchestrator. CPUs : Specify how many CPUs the Triton container can use. Decimal values are allowed, so if set to 1.5, the container will use at most one and a half cpu resource. GPUs : Specify how many Nvidia GPUs the Triton container can use. Allowed values are 'all' or an integer number. If there's no Nvidia GPU installed, leave the field empty. Timeout (in seconds) for time consuming tasks : Timeout (in seconds) for time consuming tasks like server startup, shutdown or model load. If the task exceeds the timeout, the operation will be terminated with an error. Max. GRPC message size (bytes) : this field controls the maximum allowed size for the GRPC calls to the server instance. Note Pay attention on the ports used for communicating with the Triton Server. The default ports are the 8000-8002, but these are typically used by Kura for debug purposes.","title":"Triton Server Container Service component"},{"location":"core-services/nvidia-triton-server-inference-engine/#triton-server-service-component-deprecated-since-520","text":"The Kura Triton Server component is the implementation of the inference engine APIs and provides methods for interacting with a local or remote Nvidia\u2122 Triton Server. As presented below, the component enables the user to configure a local server running on the gateway or to communicate to an external server to load specific models. The parameters used to configure the Triton Service are the following: Local Nvidia Triton Server : If enabled, a local native Nvidia Triton Server is started on the gateway. In this case, the model repository and backends path are mandatory. Moreover, the server address property is overridden and set to localhost. Be aware that the Triton Server has to be already installed on the system. Nvidia Triton Server address : the address of the Nvidia Triton Server. Nvidia Triton Server ports : the ports used to connect to the server for HTTP, GRPC, and Metrics services. Local model repository path : Only for a local instance, specify the path on the filesystem where the models are stored. Local model decryption password : Only for local instance, specify the password to be used for decrypting models stored in the model repository. If none is specified, models are supposed to be plaintext. Inference Models : a comma-separated list of inference model names that the server will load. The models have to be already present in the filesystem where the server is running. This option simply tells the server to load the given models from a local or remote repository. Local backends path : Only for a local instance, specify the path on the filesystem where the backends are stored. Optional configuration for the local backends : Only for local instance, a semi-colon separated list of configuration for the backends. i.e. tensorflow,version=2;tensorflow,allow-soft-placement=false Timeout (in seconds) for time consuming tasks : Timeout (in seconds) for time consuming tasks like server startup, shutdown or model load. If the task exceeds the timeout, the operation will be terminated with an error. Max. GRPC message size (bytes) : this field controls the maximum allowed size for the GRPC calls to the server instance. Note Pay attention on the ports used for communicating with the Triton Server. The default ports are the 8000-8002, but these are tipically used by Kura for debug purposes.","title":"Triton Server Service component [deprecated since 5.2.0]"},{"location":"core-services/nvidia-triton-server-inference-engine/#configuration-for-a-local-native-triton-server-with-triton-server-service-component-deprecated-since-520","text":"Note Requirement : tritonserver executable needs to be available in the path to the kurad user. Be sure to have a working Triton Server installation before configuring the local native Triton Server instance through Kura UI. When the Local Nvidia Triton Server option is set to true, a local instance of the Nvidia\u2122 Triton Server is started on the gateway. The following configuration is required: Local Nvidia Triton Server : true Nvidia Triton Server address : localhost Nvidia Triton Server ports : mandatory Local model repository path : mandatory Inference Models : mandatory. Note that the models have to be already present on the filesystem. Local backends path : mandatory The typical command used to start the Triton Server is like this: tritonserver --model-repository = \\ --backend-directory = \\ --backend-config = \\ --http-port = \\ --grpc-port = \\ --metrics-port = \\ --model-control-mode = explicit \\ --load-model = \\ --load-model = \\ ...","title":"Configuration for a local native Triton Server with Triton Server Service component [deprecated since 5.2.0]"},{"location":"core-services/nvidia-triton-server-inference-engine/#configuration-for-a-local-triton-server-running-in-a-docker-container-with-triton-server-service-component-deprecated-since-520","text":"If the Nvidia\u2122 Triton Server is running as a Docker container in the gateway, the following configuration is required: Local Nvidia Triton Server : false Nvidia Triton Server address : localhost Nvidia Triton Server ports : \\ Inference Models : \\. The models have to be already present on the filesystem. In order to correctly load the models at runtime, configure the server with the --model-control-mode=explicit option. The typical command used for running the docker container is as follows. Note the forward of the ports to not interfere with Kura. docker run --rm \\ -p4000:8000 \\ -p4001:8001 \\ -p4002:8002 \\ --shm-size = 150m \\ -v path/to/models:/models \\ nvcr.io/nvidia/tritonserver: [ version ] \\ tritonserver --model-repository = /models --model-control-mode = explicit","title":"Configuration for a local Triton Server running in a Docker container with Triton Server Service component [deprecated since 5.2.0]"},{"location":"core-services/nvidia-triton-server-inference-engine/#configuration-for-a-remote-triton-server-with-triton-server-service-component-deprecated-since-520","text":"When the Nvidia\u2122 Triton Server is running on a remote server, the following configuration is needed: Local Nvidia Triton Server : false Nvidia Triton Server address : mandatory Nvidia Triton Server ports : mandatory ** Inference Models**: mandatory. The models have to be already present on the filesystem.","title":"Configuration for a remote Triton Server with Triton Server Service component [deprecated since 5.2.0]"},{"location":"core-services/nvidia-triton-server-inference-engine/#ai-model-encryption-support","text":"For ensuring inference integrity and providing copyright protection of deep-learning models on edge devices, Kura provides decryption capabilities for trained models to be served through the Triton Server.","title":"AI Model Encryption Support"},{"location":"core-services/nvidia-triton-server-inference-engine/#how-it-works","text":"Prerequisites : a deep-learning trained model (or more) exists with the corresponding necessary configuration for running on the Triton Server without encryption. A folder containing the required files (model, configuration etc) has been tested on a Triton Server. Restrictions : if model encryption is used, the following restrictions apply: model encryption support is only available for a local Triton Server instance all models in the folder containing the encrypted models must be encrypted all models must be encrypted with OpenPGP-compliant AES 256 cipher algorithm all models must be encrypted with the same password Once the development of the deep-learning model is complete, the developer who wants to deploy the model on the edge device in a secure manner can proceed with encrypting the Triton model using the procedure detailed below. After encrypting the model he/she can transfer the file on the edge device using his/her preferred method. Kura will keep the stored model protected at all times and have the model decrypted in runtime only for use by the Inference Server Runtime. As soon as the model is correctly loaded into memory the decrypted model will be removed from the filesystem. As an additional security measure, the Model Repository containing the decrypted models will be stored in a temporary subfolder and will feature restrictive permission such that only Kura, the Inference Server and the root user will be able to access it.","title":"How it works"},{"location":"core-services/nvidia-triton-server-inference-engine/#encryption-procedure","text":"Given a trained model inside the folder tf_autoencoder_fp32 (for example) with the following layout (see the official documentation for details): tf_autoencoder_fp32 \u251c\u2500\u2500 1 \u2502 \u2514\u2500\u2500 model.savedmodel \u2502 \u251c\u2500\u2500 assets \u2502 \u251c\u2500\u2500 keras_metadata.pb \u2502 \u251c\u2500\u2500 saved_model.pb \u2502 \u2514\u2500\u2500 variables \u2502 \u251c\u2500\u2500 variables.data-00000-of-00001 \u2502 \u2514\u2500\u2500 variables.index \u2514\u2500\u2500 config.pbtxt Compress the model into a zip archive with the following command: zip -vr tf_autoencoder_fp32.zip tf_autoencoder_fp32/ then encrypt it with the AES 256 algorithm using the following gpg command: gpg --armor --symmetric --cipher-algo AES256 tf_autoencoder_fp32.zip The resulting archive tf_autoencoder_fp32.zip.asc can be transferred to the Local Model Repository Path on the target machine and will be decrypted by Kura.","title":"Encryption procedure"},{"location":"core-services/position-service/","text":"Position Service The PositionService provides the geographic position of the gateway if a GPS component is available and enabled. When this service is enabled and provides a valid geographic position, this position is published in the gateway birth certificate with its location. The GPS connection parameters must be defined in order to allow the service to receive the GPS frames. The PositionService supports direct access to gps device or the connection to that through gpsd. For a device that is not connected to a GPS, it is possible to define a static position by entering latitude, longitude, and altitude. In this case, the position is returned by the PositionService as if it were an actual GPS position. This may be useful when a gateway is installed in a known place and does not move. To use this service, select the PositionService option located in the Services area as shown in the screen capture below. This service provides the following configuration parameters: enabled - defines whether or not this service is enabled or disabled. (Required field.) static - specifies true or false whether to use a static position instead of a GPS. (Required field.) provider - species which position provider use, can be gpsd or serial. gpsd - gpsd service daemon if is available on the system. serial - direct access to gps device through serial or usb port. gpsd.host - host where gpsd service deamon is running. (required only if gpsd provider is selected.) gpsd.port - port where gpsd service is listening. (required only if gpsd provider is selected.) latitude - provides the static latitude value in degrees. longitude - provides the static longitude value in degrees. altitude - provides the static altitude value in meters. port - supplies the USB or serial port of the GPS device. baudRate - supplies the baud rate of the GPS device. bitsPerWord - sets the number of bits per word (databits) for the serial communication to the GPS device. stopbits - sets the number of stop bits for the serial communication to the GPS device. parity - sets the parity for the serial communication to the GPS device.","title":"Position Service"},{"location":"core-services/position-service/#position-service","text":"The PositionService provides the geographic position of the gateway if a GPS component is available and enabled. When this service is enabled and provides a valid geographic position, this position is published in the gateway birth certificate with its location. The GPS connection parameters must be defined in order to allow the service to receive the GPS frames. The PositionService supports direct access to gps device or the connection to that through gpsd. For a device that is not connected to a GPS, it is possible to define a static position by entering latitude, longitude, and altitude. In this case, the position is returned by the PositionService as if it were an actual GPS position. This may be useful when a gateway is installed in a known place and does not move. To use this service, select the PositionService option located in the Services area as shown in the screen capture below. This service provides the following configuration parameters: enabled - defines whether or not this service is enabled or disabled. (Required field.) static - specifies true or false whether to use a static position instead of a GPS. (Required field.) provider - species which position provider use, can be gpsd or serial. gpsd - gpsd service daemon if is available on the system. serial - direct access to gps device through serial or usb port. gpsd.host - host where gpsd service deamon is running. (required only if gpsd provider is selected.) gpsd.port - port where gpsd service is listening. (required only if gpsd provider is selected.) latitude - provides the static latitude value in degrees. longitude - provides the static longitude value in degrees. altitude - provides the static altitude value in meters. port - supplies the USB or serial port of the GPS device. baudRate - supplies the baud rate of the GPS device. bitsPerWord - sets the number of bits per word (databits) for the serial communication to the GPS device. stopbits - sets the number of stop bits for the serial communication to the GPS device. parity - sets the parity for the serial communication to the GPS device.","title":"Position Service"},{"location":"core-services/rest-service/","text":"REST Service Kura provides a built-in REST Service based on the osgi-jax-rs-connector project. By default, REST service providers register their services using the context path /services . The REST service provides the BASIC Authentication support and HTTPS client certificate authentication support. Starting from Kura 5.4.0, REST service provides built in session management support, the Session REST APIs can be used to establish a session. Using sessions is the recommended way for interacting with Kura REST APIs from a browser based application, for this use case it is also possible to disable the default session-less BASIC and certificate based authentication (see the Basic Authentication Enabled and Enable Certificate Authentication Whitout Session Management configuration parameters below). REST API access is available on all HTTP ports defined in the HTTP/HTTPS Configuration section, unless access is restricted to dedicated ports using the corresponding configuration parameter (see below). Certificate authentication support is only available on the HTTPS With Certificate Authentication Ports configured in HTTP/HTTPS Configuration section. Kura Identity names and passwords can be used for BASIC Authentication. Certificate authentication follows the same rules as Gateway Administration Console Authentication . Warning If the forced password change feature for a given identity is enabled, REST API password authentication will be blocked for that identity until the password is updated by the user or the feature is manually disabled. Certificate authentication will continue to be allowed even if the forced password change feature is enabled. JAX-RS roles are mapped to Kura permissions, the name of a permission associated with a JAX-RS role is the rest. prefix followed by the role name. For example the assets role is mapped to the rest.assets permission. REST related permissions can be assigned to an identity using the Gateway Administration Console in the Identities section. Rest Service configuration The available configuration parameters are the following: Allowed Ports : If set to a non empty list, REST API access will be allowed only on the specified ports. If set to an empty list, access will be allowed on all ports. Please make sure that the allowed ports are open in HttpService and Firewall configuration. (Default: empty) Password Authentication Enabled : Enables or disables the built-in password authentication support. (Default: true) Certificate Authentication Enabled : Enables or disables the built-in certificate authentication support. (Default: true) Session Based Authentication Enabled : If set to true, enables authentication using the dedicated /services/session/v1 endpoints and cookie based session management. (Default: true) Session Inactivity Interval (Seconds) : The session inactivity interval, sessions will expire if no request is performed for the amount of time specified by this parameter in seconds. This parameter is ignored if Session Based Authentication Enabled is set to false. (Default: 900) Basic Authentication Enabled : Allows to perform authentication by providing identity name and password as BASIC credentials in the request to any resource endpoint. Requires that the Password Authentication Enabled parameter is set to true. (Default: true) Enable Certificate Authentication Without Session Management : If set to true, calling /services/session/v1/certificate to create a session will not be necessary in order to perform certificate based authentication. Presenting a valid HTTPS client certificate and accessing resource endpoint directly is enough for authentication to succeed. Requires that the Certificate Authentication Enabled parameter is set to true. (Default: true) Custom authentication methods Starting from Kura 5.2.0 it is also possible to develop custom REST authentication method providers by registering an implementation of the org.eclipse.kura.rest.auth.AuthenticationProvider interface as an OSGi service. The org.eclipse.kura.example.rest.authentication.provider bundle in Kura repository provides an example on how to implement a custom authentication method. Assets REST APIs Kura exposes REST APIs for the Asset instances instantiated in the framework. Assets REST APIs are available in the context path /services/assets . Following, the supported REST endpoints. Method Path Allowed roles Encoding Request parameters Description GET / assets JSON None Returns the list of available assets GET /{pid} assets JSON None Returns the list of available channels for the selected asset (specified by the corresponding PID) GET /{pid}/_read assets JSON None Returns the read for all the READ channels in the selected Asset POST /{pid}/_read assets JSON The list of channels where the READ operation should be performed. Returns the result of the read operation for the specified channels POST /{pid}/_write assets JSON The list of channels and associated values that will be used for the WRITE operation. Performs the write operation for the specified channels returning the result of the operation.","title":"REST Service"},{"location":"core-services/rest-service/#rest-service","text":"Kura provides a built-in REST Service based on the osgi-jax-rs-connector project. By default, REST service providers register their services using the context path /services . The REST service provides the BASIC Authentication support and HTTPS client certificate authentication support. Starting from Kura 5.4.0, REST service provides built in session management support, the Session REST APIs can be used to establish a session. Using sessions is the recommended way for interacting with Kura REST APIs from a browser based application, for this use case it is also possible to disable the default session-less BASIC and certificate based authentication (see the Basic Authentication Enabled and Enable Certificate Authentication Whitout Session Management configuration parameters below). REST API access is available on all HTTP ports defined in the HTTP/HTTPS Configuration section, unless access is restricted to dedicated ports using the corresponding configuration parameter (see below). Certificate authentication support is only available on the HTTPS With Certificate Authentication Ports configured in HTTP/HTTPS Configuration section. Kura Identity names and passwords can be used for BASIC Authentication. Certificate authentication follows the same rules as Gateway Administration Console Authentication . Warning If the forced password change feature for a given identity is enabled, REST API password authentication will be blocked for that identity until the password is updated by the user or the feature is manually disabled. Certificate authentication will continue to be allowed even if the forced password change feature is enabled. JAX-RS roles are mapped to Kura permissions, the name of a permission associated with a JAX-RS role is the rest. prefix followed by the role name. For example the assets role is mapped to the rest.assets permission. REST related permissions can be assigned to an identity using the Gateway Administration Console in the Identities section.","title":"REST Service"},{"location":"core-services/rest-service/#rest-service-configuration","text":"The available configuration parameters are the following: Allowed Ports : If set to a non empty list, REST API access will be allowed only on the specified ports. If set to an empty list, access will be allowed on all ports. Please make sure that the allowed ports are open in HttpService and Firewall configuration. (Default: empty) Password Authentication Enabled : Enables or disables the built-in password authentication support. (Default: true) Certificate Authentication Enabled : Enables or disables the built-in certificate authentication support. (Default: true) Session Based Authentication Enabled : If set to true, enables authentication using the dedicated /services/session/v1 endpoints and cookie based session management. (Default: true) Session Inactivity Interval (Seconds) : The session inactivity interval, sessions will expire if no request is performed for the amount of time specified by this parameter in seconds. This parameter is ignored if Session Based Authentication Enabled is set to false. (Default: 900) Basic Authentication Enabled : Allows to perform authentication by providing identity name and password as BASIC credentials in the request to any resource endpoint. Requires that the Password Authentication Enabled parameter is set to true. (Default: true) Enable Certificate Authentication Without Session Management : If set to true, calling /services/session/v1/certificate to create a session will not be necessary in order to perform certificate based authentication. Presenting a valid HTTPS client certificate and accessing resource endpoint directly is enough for authentication to succeed. Requires that the Certificate Authentication Enabled parameter is set to true. (Default: true)","title":"Rest Service configuration"},{"location":"core-services/rest-service/#custom-authentication-methods","text":"Starting from Kura 5.2.0 it is also possible to develop custom REST authentication method providers by registering an implementation of the org.eclipse.kura.rest.auth.AuthenticationProvider interface as an OSGi service. The org.eclipse.kura.example.rest.authentication.provider bundle in Kura repository provides an example on how to implement a custom authentication method.","title":"Custom authentication methods"},{"location":"core-services/rest-service/#assets-rest-apis","text":"Kura exposes REST APIs for the Asset instances instantiated in the framework. Assets REST APIs are available in the context path /services/assets . Following, the supported REST endpoints. Method Path Allowed roles Encoding Request parameters Description GET / assets JSON None Returns the list of available assets GET /{pid} assets JSON None Returns the list of available channels for the selected asset (specified by the corresponding PID) GET /{pid}/_read assets JSON None Returns the read for all the READ channels in the selected Asset POST /{pid}/_read assets JSON The list of channels where the READ operation should be performed. Returns the result of the read operation for the specified channels POST /{pid}/_write assets JSON The list of channels and associated values that will be used for the WRITE operation. Performs the write operation for the specified channels returning the result of the operation.","title":"Assets REST APIs"},{"location":"core-services/simple-artemis-mqtt-broker/","text":"Simple Artemis MQTT Broker By default, this instance is disabled but, selecting the Simple Artemis MQTT Broker option in Services it is possible to enable a basic instance of an \u200bActiveMQ-7 broker with MQTT capabilities. The service has the following configuration fields: Enabled - (Required) - Enables the broker instance MQTT address - MQTT broker listener address. In order to allow access to the broker from processes running on external nodes, make sure to bind the server to an externally accessible address. Setting this parameter to 0.0.0.0 binds to all addresses. MQTT port - (Required) - MQTT broker port, make sure to open the specified port in the firewall configuration section if external access to the broker is required. User name - The username\u200b required to access to the broker Password of the user - The password required to connect. If the password is empty, no password will be required to connect.","title":"Simple Artemis MQTT Broker"},{"location":"core-services/simple-artemis-mqtt-broker/#simple-artemis-mqtt-broker","text":"By default, this instance is disabled but, selecting the Simple Artemis MQTT Broker option in Services it is possible to enable a basic instance of an \u200bActiveMQ-7 broker with MQTT capabilities. The service has the following configuration fields: Enabled - (Required) - Enables the broker instance MQTT address - MQTT broker listener address. In order to allow access to the broker from processes running on external nodes, make sure to bind the server to an externally accessible address. Setting this parameter to 0.0.0.0 binds to all addresses. MQTT port - (Required) - MQTT broker port, make sure to open the specified port in the firewall configuration section if external access to the broker is required. User name - The username\u200b required to access to the broker Password of the user - The password required to connect. If the password is empty, no password will be required to connect.","title":"Simple Artemis MQTT Broker"},{"location":"core-services/sqlite-db-service/","text":"SQLite Db Service Starting from version 5.3, Kura provides provides an integration of the SQLite database, based on the org.xerial:sqlite-jdbc wrapper . The database integration is not included in the official distribution, but it can be downloaded from Eclipse Marketplace as a deployment package. Warning Note about Raspberry PI: Recent versions of Raspberry Pi OS 32 bit on Raspberry PI 4 will use by default a 64 bit kernel with a 32 bit userspace. This can cause issues to applications that use the result of uname -m to decide which native libraries to load (see https://github.com/raspberrypi/firmware/issues/1795). This currently affects the Kura SQLite database connector. It should be possible to solve by switching to the 32 bit kernel setting arm_64bit=0 in /boot/config.txt and restarting the device. Supported Features Kura supports the following SQLite database features: Persistence modes : The implementation currently supports in-memory and file-based database instances. Multiple database instances : It is possible to create and configure multiple database instances from the Kura Administration UI, these instances can be selectively consumed by applications. Journaling modes : The implementation currently supports the WAL and rollback journal journaling modes. Periodic database defrag and checkpoint : The implementations currently supports periodic defrag (VACUUM) and periodic WAL checkpoint. Usage Creating a new SQLite database instance To create a new SQLite database instance, use the following procedure: Open the Administrative UI and press the + button in the side menu, under the Services section. A pop-up dialog should appear. Select org.eclipse.kura.db.SQLiteDbService from the Factory drop-down list, enter an arbitrary name for the new instance and click Apply . An entry for the newly created instance should appear in the side menu under Services , click on it to review its configuration. It is not possible to create different DB instances that manage the same database file. Configuration Parameters The SQLite DB provides the following configuration parameters: Database Mode : Defines the database mode. If In Memory is selected, the database will not be persisted on the filesystem, all data will be lost if Kura is restarted and/or the database instance is deleted. If Persisted is selected, the database will be stored on disk in the location specified by the Persisted Database Path parameter. Persisted Database Path : Defines the path to the database file (it must include the database file name). This parameter is only relevant for persisted databases. Encryption Key : Allows to specify a key/passphrase for encrypting the database file. This feature requires a SQLite binary with an encryption extension, and is only relevant for persisted databases. The key format can be specified using the Encryption Key Format parameter. If the value of this parameter is changed, the encryption key of the database will be updated accordingly. This parameter can be left empty to create an unencrypted database or to decrypt an encrypted one. Note The sqlite-jdbc version distributed with Kura does not contain any encryption extension, encryption features will not be available out of the box. See sqlite-jdbc documentaton for instructions about how to use a security extension. Encryption Key Format : Allows to specify the format of the Encryption Key parameter value. The possible values are ASCII (an ASCII string), Hex SSE (the key is an hexadecimal string to be used with the SSE extension) or Hex SQLCipher (the key is an hexadecimal string to be used with the SQLCipher extension). Journal Mode : The database journal mode. The following options are available: Rollback Journal : The database instance will use the rollback journal for more details. More specifically, the DELETE argument will be passed to the pragma journal_mode command. WAL : The database instance will use WAL mode . This is the default mode. The WAL mode description page contains a comparison of the two modes. Defrag enabled : Enables or disables the database defragmentation. Use the Defrag Interval parameter to specify the interval. Defrag interval (seconds) : The implementation supports running periodic defragmentation using the VACUUM command . This parameter specifies the interval in minutes between two successive checkpoints, set to zero to disable. This parameter is only relevant for persisted databases. Warning The total disk space used by SQLite database files might temporarily increase during defragmentation and/or if transactions that modify a lot of data are performed (including deletion). In particular: Defragmentation is implemented by copying all non-free database pages to a new file and then deleting the original file. If transactions that involve a lot of data are performed, in case of rollback journal the old content of the modified pages will be stored in the journal until the transaction is completed, and in WAL mode the new content of modified pages will be stored to the WAL file until the next checkpoint is performed. It is recommended to perform some tests to determine the maximum database files size that will be used by the application and ensure that the size of the partition containing the database is at least twice as the expected db size. Checkpoint enabled : Enables or disables checkpoints in WAL journal mode. Use the WAL Checkpoint Interval parameter to specify the interval. WAL Checkpoint Interval (Seconds) : The implementation supports running periodic periodic WAL checkpoints . Checkpoints will be performed in TRUNCATE mode. This parameter specifies the interval in seconds between two consecutive checkpoints, set to zero to disable. This parameter is only relevant for persisted databases in WAL Journal Mode. In WAL mode a checkpoint will be performed after a periodic defragmentation regardless of the value of this parameter. Connection pool max size : The implementation manages connections using a connection pool. This parameter defines the maximum number of connections for the pool. If a new connection is requested Delete Database Files On Failure : If set to true, the database files will be deleted in case of failure in opening a persisted database. This is intended as a last resort measure for keeping the database service operational, especially in the case when it is used as a cloud connection message store. Debug Shell Access Enabled : Enables or disables the interaction with this database instance using the sqlitedbg:excuteQuery OSGi console command. (see #debug-shell) Selecting a database instance for existing components A database instance is identified by its Kura service PID . The PID for instances created using the Web UI is the string entered in the Name field at step 2 of the previous section. The built-in components that use database functionalities allow to specify which instance to use in their configuration. These components are the DataService component of the cloud stack, the Wire Record Store and Wire Record Query wire components. The configuration of each component contains a property that allows to specify the Kura Service PID of the desired instance. Warning Using SQLite database instances through the deprecated DbFilter and DbStore components is not supported. Usage through Wires It is possible to store and extract Wire Records into/from a SQLite database instance using the Wire Record Store and Wire Record Query wire components. When a Wire Record is received by a Wire Record Store attached to a SQLite based database instance, the data will be stored in a table whose name is the current value of the Record Collection Name configuration parameter of the Wire Component. Each property contained in a Wire Record will be appended to a column with the same name as the property key. A new column will be created if it doesn't already exists. Since it is not possible to establish a one to one mapping between SQLite storage classes and the data types available on the Wires, the implementation will assign a custom type name to the created columns in order to keep track of the inserted Wire Record property type. The custom types will be assigned according to the following table: Wires Data Type Column Type Name Storage Class Type Affinity BOOLEAN BOOLEAN INTEGER INTEGER INT INTEGER LONG BIGINT INTEGER FLOAT FLOAT REAL DOUBLE DOUBLE REAL STRING TEXT TEXT BYTE_ARRAY BLOB BLOB The custom column type makes it possible to preserve the original type when data is extracted with the Wire Record Query component. Please note that the resulting type may change in case of queries that build computed columns. Warning It is not recommended to store Wire Records having properties with the same key and different value type. If the value type changes, the target column will be dropped and recreated with the type derived from the last received record. All existing data in the target column will be lost. The purpose of this is to allow changing the type of a column with a Wire Graph configuration update. Debug shell It is possible to inspect the contents of the database file using the OSGi console with the following command: sqlitedbg:executeQuery dbServicePid 'query' or more simply executeQuery dbServicePid 'query' where dbServicePid is the user defined pid of the target database instance and query is an arbitrary SQL query to be executed (make sure to properly quote the query string with the ' character). The command will print the result set or changed row count on the console. It is only possible to access database instances whose Debug Shell Access Enabled configuration parameter is set to true . The default of this parameter is false . The OSGi console is disabled by default, it can be accessed by starting the framework with the /opt/eclipse/kura/bin/start_kura_debug.sh script and running the following command on the gateway: telnet localhost 5002 Warning This feature is intended for debug purposes only, the Debug Shell Access Enabled parameter as well as the OSGi console should not be left enabled on production systems.","title":"SQLite DB Service"},{"location":"core-services/sqlite-db-service/#sqlite-db-service","text":"Starting from version 5.3, Kura provides provides an integration of the SQLite database, based on the org.xerial:sqlite-jdbc wrapper . The database integration is not included in the official distribution, but it can be downloaded from Eclipse Marketplace as a deployment package. Warning Note about Raspberry PI: Recent versions of Raspberry Pi OS 32 bit on Raspberry PI 4 will use by default a 64 bit kernel with a 32 bit userspace. This can cause issues to applications that use the result of uname -m to decide which native libraries to load (see https://github.com/raspberrypi/firmware/issues/1795). This currently affects the Kura SQLite database connector. It should be possible to solve by switching to the 32 bit kernel setting arm_64bit=0 in /boot/config.txt and restarting the device.","title":"SQLite Db Service"},{"location":"core-services/sqlite-db-service/#supported-features","text":"Kura supports the following SQLite database features: Persistence modes : The implementation currently supports in-memory and file-based database instances. Multiple database instances : It is possible to create and configure multiple database instances from the Kura Administration UI, these instances can be selectively consumed by applications. Journaling modes : The implementation currently supports the WAL and rollback journal journaling modes. Periodic database defrag and checkpoint : The implementations currently supports periodic defrag (VACUUM) and periodic WAL checkpoint.","title":"Supported Features"},{"location":"core-services/sqlite-db-service/#usage","text":"","title":"Usage"},{"location":"core-services/sqlite-db-service/#creating-a-new-sqlite-database-instance","text":"To create a new SQLite database instance, use the following procedure: Open the Administrative UI and press the + button in the side menu, under the Services section. A pop-up dialog should appear. Select org.eclipse.kura.db.SQLiteDbService from the Factory drop-down list, enter an arbitrary name for the new instance and click Apply . An entry for the newly created instance should appear in the side menu under Services , click on it to review its configuration. It is not possible to create different DB instances that manage the same database file.","title":"Creating a new SQLite database instance"},{"location":"core-services/sqlite-db-service/#configuration-parameters","text":"The SQLite DB provides the following configuration parameters: Database Mode : Defines the database mode. If In Memory is selected, the database will not be persisted on the filesystem, all data will be lost if Kura is restarted and/or the database instance is deleted. If Persisted is selected, the database will be stored on disk in the location specified by the Persisted Database Path parameter. Persisted Database Path : Defines the path to the database file (it must include the database file name). This parameter is only relevant for persisted databases. Encryption Key : Allows to specify a key/passphrase for encrypting the database file. This feature requires a SQLite binary with an encryption extension, and is only relevant for persisted databases. The key format can be specified using the Encryption Key Format parameter. If the value of this parameter is changed, the encryption key of the database will be updated accordingly. This parameter can be left empty to create an unencrypted database or to decrypt an encrypted one. Note The sqlite-jdbc version distributed with Kura does not contain any encryption extension, encryption features will not be available out of the box. See sqlite-jdbc documentaton for instructions about how to use a security extension. Encryption Key Format : Allows to specify the format of the Encryption Key parameter value. The possible values are ASCII (an ASCII string), Hex SSE (the key is an hexadecimal string to be used with the SSE extension) or Hex SQLCipher (the key is an hexadecimal string to be used with the SQLCipher extension). Journal Mode : The database journal mode. The following options are available: Rollback Journal : The database instance will use the rollback journal for more details. More specifically, the DELETE argument will be passed to the pragma journal_mode command. WAL : The database instance will use WAL mode . This is the default mode. The WAL mode description page contains a comparison of the two modes. Defrag enabled : Enables or disables the database defragmentation. Use the Defrag Interval parameter to specify the interval. Defrag interval (seconds) : The implementation supports running periodic defragmentation using the VACUUM command . This parameter specifies the interval in minutes between two successive checkpoints, set to zero to disable. This parameter is only relevant for persisted databases. Warning The total disk space used by SQLite database files might temporarily increase during defragmentation and/or if transactions that modify a lot of data are performed (including deletion). In particular: Defragmentation is implemented by copying all non-free database pages to a new file and then deleting the original file. If transactions that involve a lot of data are performed, in case of rollback journal the old content of the modified pages will be stored in the journal until the transaction is completed, and in WAL mode the new content of modified pages will be stored to the WAL file until the next checkpoint is performed. It is recommended to perform some tests to determine the maximum database files size that will be used by the application and ensure that the size of the partition containing the database is at least twice as the expected db size. Checkpoint enabled : Enables or disables checkpoints in WAL journal mode. Use the WAL Checkpoint Interval parameter to specify the interval. WAL Checkpoint Interval (Seconds) : The implementation supports running periodic periodic WAL checkpoints . Checkpoints will be performed in TRUNCATE mode. This parameter specifies the interval in seconds between two consecutive checkpoints, set to zero to disable. This parameter is only relevant for persisted databases in WAL Journal Mode. In WAL mode a checkpoint will be performed after a periodic defragmentation regardless of the value of this parameter. Connection pool max size : The implementation manages connections using a connection pool. This parameter defines the maximum number of connections for the pool. If a new connection is requested Delete Database Files On Failure : If set to true, the database files will be deleted in case of failure in opening a persisted database. This is intended as a last resort measure for keeping the database service operational, especially in the case when it is used as a cloud connection message store. Debug Shell Access Enabled : Enables or disables the interaction with this database instance using the sqlitedbg:excuteQuery OSGi console command. (see #debug-shell)","title":"Configuration Parameters"},{"location":"core-services/sqlite-db-service/#selecting-a-database-instance-for-existing-components","text":"A database instance is identified by its Kura service PID . The PID for instances created using the Web UI is the string entered in the Name field at step 2 of the previous section. The built-in components that use database functionalities allow to specify which instance to use in their configuration. These components are the DataService component of the cloud stack, the Wire Record Store and Wire Record Query wire components. The configuration of each component contains a property that allows to specify the Kura Service PID of the desired instance. Warning Using SQLite database instances through the deprecated DbFilter and DbStore components is not supported.","title":"Selecting a database instance for existing components"},{"location":"core-services/sqlite-db-service/#usage-through-wires","text":"It is possible to store and extract Wire Records into/from a SQLite database instance using the Wire Record Store and Wire Record Query wire components. When a Wire Record is received by a Wire Record Store attached to a SQLite based database instance, the data will be stored in a table whose name is the current value of the Record Collection Name configuration parameter of the Wire Component. Each property contained in a Wire Record will be appended to a column with the same name as the property key. A new column will be created if it doesn't already exists. Since it is not possible to establish a one to one mapping between SQLite storage classes and the data types available on the Wires, the implementation will assign a custom type name to the created columns in order to keep track of the inserted Wire Record property type. The custom types will be assigned according to the following table: Wires Data Type Column Type Name Storage Class Type Affinity BOOLEAN BOOLEAN INTEGER INTEGER INT INTEGER LONG BIGINT INTEGER FLOAT FLOAT REAL DOUBLE DOUBLE REAL STRING TEXT TEXT BYTE_ARRAY BLOB BLOB The custom column type makes it possible to preserve the original type when data is extracted with the Wire Record Query component. Please note that the resulting type may change in case of queries that build computed columns. Warning It is not recommended to store Wire Records having properties with the same key and different value type. If the value type changes, the target column will be dropped and recreated with the type derived from the last received record. All existing data in the target column will be lost. The purpose of this is to allow changing the type of a column with a Wire Graph configuration update.","title":"Usage through Wires"},{"location":"core-services/sqlite-db-service/#debug-shell","text":"It is possible to inspect the contents of the database file using the OSGi console with the following command: sqlitedbg:executeQuery dbServicePid 'query' or more simply executeQuery dbServicePid 'query' where dbServicePid is the user defined pid of the target database instance and query is an arbitrary SQL query to be executed (make sure to properly quote the query string with the ' character). The command will print the result set or changed row count on the console. It is only possible to access database instances whose Debug Shell Access Enabled configuration parameter is set to true . The default of this parameter is false . The OSGi console is disabled by default, it can be accessed by starting the framework with the /opt/eclipse/kura/bin/start_kura_debug.sh script and running the following command on the gateway: telnet localhost 5002 Warning This feature is intended for debug purposes only, the Debug Shell Access Enabled parameter as well as the OSGi console should not be left enabled on production systems.","title":"Debug shell"},{"location":"core-services/watchdog-service/","text":"Watchdog Service The WatchdogService provides methods for starting, stopping, and updating a hardware watchdog if it is present on the system. Once started, the watchdog must be updated to prevent the system from rebooting. To use this service, select the WatchdogService option located in the Services area as shown in the screen capture below. This service provides the following configuration parameters: enabled - sets whether or not this service is enabled or disabled. (Required field) pingInterval - defines the maximum time interval between two watchdogs' refresh to prevent the system from rebooting. (Required field) Watchdog device path - sets the watchdog device path. (Required field) Reboot Cause File Path - sets the path to the file that will contain the reboot cause information. (Required field)","title":"Watchdog Service"},{"location":"core-services/watchdog-service/#watchdog-service","text":"The WatchdogService provides methods for starting, stopping, and updating a hardware watchdog if it is present on the system. Once started, the watchdog must be updated to prevent the system from rebooting. To use this service, select the WatchdogService option located in the Services area as shown in the screen capture below. This service provides the following configuration parameters: enabled - sets whether or not this service is enabled or disabled. (Required field) pingInterval - defines the maximum time interval between two watchdogs' refresh to prevent the system from rebooting. (Required field) Watchdog device path - sets the watchdog device path. (Required field) Reboot Cause File Path - sets the path to the file that will contain the reboot cause information. (Required field)","title":"Watchdog Service"},{"location":"gateway-configuration/cellular-configuration/","text":"Cellular Configuration If it is not configured, the cellular interface is presented on the interface list either by modem USB address, or if serial modem is used, by modem name. This 'fake' interface name is replaced by 'proper' interface name (e.g., ppp0) when the first modem configuration is submitted. The cellular interface should be configured by first enabling it in the TCP/IP tab, and then setting the Cellular tab. Note that the cellular interface can only be set as WAN using DHCP . The cellular interface configuration options are described below. Cellular Configuration The Cellular tab contains the following configuration parameters: Model : specifies the modem model. Network Technology : describes the network technology used by this modem. HSDPA EVDO Modem Identifier : provides a unique name for this modem. Interface # : provides a unique number for the modem interface (e.g., an interface # of 0 would name the modem interface ppp0). Dial String : instructs how the modem should attempt to connect. Typical dial strings are as follows: HSPA modem: atd*99***1# EVDO/CDMA modem: atd#777 APN : defines the modem access point name (HSPA modems only). Auth Type : specifies the authentication type (HSPA modems only). None Auto CHAP PAP Username : supplies the username; disabled if no authentication method is specified. Password : supplies the password; disabled if no authentication method is specified. Modem Reset Timeout : sets the modem reset timeout in minutes. If set to a non-zero value, the modem is reset after n consecutive minutes of unsuccessful connection attempts. If set to zero, the modem keeps trying to establish a PPP connection without resetting. The default value is 5 minutes. Reopen Connection on Termination : sets the persist option of the PPP daemon that specifies if PPP daemon should exit after connection is terminated. Note that the maxfail option still has an effect on persistent connections. Connection Attempts Retry Delay : Sets the holdoff parameter to instruct the PPP daemon on how many seconds to wait before re-initiating the link after it terminates. This option only has any effect if the persist option (Reopen Connection on Termination) is set to true. The holdoff period is not applied if the link was terminated because it was idle. The default value is 1 second. Connection Attempts : sets the maxfail option of the PPP daemon that limits the number of consecutive failed PPP connection attempts. The default value is 5 connection attempts. A value of zero means no limit. The PPP daemon terminates after the specified number of failed PPP connection attempts and restarts by the ModemMonitor thread. Disconnect if Idle : sets the idle option of the PPP daemon, which terminates the PPP connection if the link is idle for a specified number of seconds. The default value is 95 seconds. To disable this option, set it to zero. Active Filter : sets the active-filter option of the PPP daemon. This option specifies a packet filter (filter-expression) to be applied to data packets in order to determine which packets are regarded as link activity, and thereby, reset the idle timer. The filter-expression syntax is as described for tcpdump(1); however, qualifiers that do not apply to a PPP link, such as ether and arp , are not permitted. The default value is inbound . To disable the active-filter option, leave it blank. LCP Echo Interval : sets the lcp-echo-interval option of the PPP daemon. If set to a positive number, the modem sends LCP echo request to the peer at the specified number of seconds. To disable this option, set it to zero. This option may be used with the lcp-echo-failure option to detect that the peer is no longer connected. LCP Echo Failure : sets the lcp-echo-failure option of the PPP daemon. If set to a positive number, the modem presumes the peer to be dead if a specified number of LCP echo-requests are sent without receiving a valid LCP echo-reply. To disable this option, set it to zero. Enable GPS : enables GPS with the following conditions: One modem port will be dedicated to NMEA data stream. This port may not be used to send AT commands to the modem. PositionService should be enabled. Serial settings of PositionService should not be changed; it will be redirected to the modem GPS port automatically. Cellular Linux Configuration This section describes the changes applied by Kura at the Linux networking configuration. Please read the following note before proceeding with manual changes of the Linux networking configuration. Warning It is NOT recommended performing manual editing of the Linux networking configuration files when the gateway configuration is being managed through Kura. While Linux may correctly accept manual changes, Kura may not be able to interpret the new configuration resulting in an inconsistent state. When the cellular configuration is submitted, Kura generates peer and chat scripts used by the PPP daemon to establish a PPP connection. Examples of these scripts for HSPA and EVDO modems are shown below. Example Peer Script for HSPA Modem 921600 unit 0 logfile /var/log/HE910-D_2-1.5 debug connect 'chat:v:f /etc/ppp/scripts/chat_HE910-D_2-1.5' disconnect 'chat:v:f /etc/ppp/scripts/disconnect_HE910-D_2-1.5' modem lock noauth noipdefault defaultroute usepeerdns noproxyarp novj novjccomp nobsdcomp nodeflate nomagic idle 95 active-filter 'inbound' persist holdoff 1 maxfail 5 connect-delay 1000 Example Chat Script for HSPA Modem ABORT \"BUSY\" ABORT \"VOICE\" ABORT \"NO CARRIER\" ABORT \"NO DIALTONE\" ABORT \"NO DIAL TONE\" ABORT \"ERROR\" \"\" \"+++ath\" OK \"AT\" OK AT+CGDCONT = 1 , \"IP\" , \"c1.korem2m.com\" OK \"\\d\\d\\d\" \"\" \"atd-99---1#\" CONNECT \"\\c\" Example Peer Script for EVDO Modem 921600 unit 0 logfile /var/log/DE910-DUAL_1-1.5 debug connect 'chat:v:f /etc/ppp/scripts/chat_DE910-DUAL_1-1.5' disconnect 'chat:v:f /etc/ppp/scripts/disconnect_DE910-DUAL_1-1.5' crtscts lock noauth defaultroute usepeerdns idle 95 active-filter 'inbound' persist holdoff 1 maxfail 5 connect-delay 10000 Example Chat Script for EVDO Modem ABORT \"BUSY\" ABORT \"VOICE\" ABORT \"NO CARRIER\" ABORT \"NO DIALTONE\" ABORT \"NO DIAL TONE\" ABORT \"ERROR\" \"\" \"+++ath\" OK \"AT\" OK \"ATE1V1&F&D2&C1&C2S0=0\" OK \"ATE1V1\" OK \"ATS7=60\" OK \"\\d\\d\\d\" \"\" \"atd#777\" CONNECT \"\\c\"","title":"Cellular Configuration"},{"location":"gateway-configuration/cellular-configuration/#cellular-configuration","text":"If it is not configured, the cellular interface is presented on the interface list either by modem USB address, or if serial modem is used, by modem name. This 'fake' interface name is replaced by 'proper' interface name (e.g., ppp0) when the first modem configuration is submitted. The cellular interface should be configured by first enabling it in the TCP/IP tab, and then setting the Cellular tab. Note that the cellular interface can only be set as WAN using DHCP . The cellular interface configuration options are described below.","title":"Cellular Configuration"},{"location":"gateway-configuration/cellular-configuration/#cellular-configuration_1","text":"The Cellular tab contains the following configuration parameters: Model : specifies the modem model. Network Technology : describes the network technology used by this modem. HSDPA EVDO Modem Identifier : provides a unique name for this modem. Interface # : provides a unique number for the modem interface (e.g., an interface # of 0 would name the modem interface ppp0). Dial String : instructs how the modem should attempt to connect. Typical dial strings are as follows: HSPA modem: atd*99***1# EVDO/CDMA modem: atd#777 APN : defines the modem access point name (HSPA modems only). Auth Type : specifies the authentication type (HSPA modems only). None Auto CHAP PAP Username : supplies the username; disabled if no authentication method is specified. Password : supplies the password; disabled if no authentication method is specified. Modem Reset Timeout : sets the modem reset timeout in minutes. If set to a non-zero value, the modem is reset after n consecutive minutes of unsuccessful connection attempts. If set to zero, the modem keeps trying to establish a PPP connection without resetting. The default value is 5 minutes. Reopen Connection on Termination : sets the persist option of the PPP daemon that specifies if PPP daemon should exit after connection is terminated. Note that the maxfail option still has an effect on persistent connections. Connection Attempts Retry Delay : Sets the holdoff parameter to instruct the PPP daemon on how many seconds to wait before re-initiating the link after it terminates. This option only has any effect if the persist option (Reopen Connection on Termination) is set to true. The holdoff period is not applied if the link was terminated because it was idle. The default value is 1 second. Connection Attempts : sets the maxfail option of the PPP daemon that limits the number of consecutive failed PPP connection attempts. The default value is 5 connection attempts. A value of zero means no limit. The PPP daemon terminates after the specified number of failed PPP connection attempts and restarts by the ModemMonitor thread. Disconnect if Idle : sets the idle option of the PPP daemon, which terminates the PPP connection if the link is idle for a specified number of seconds. The default value is 95 seconds. To disable this option, set it to zero. Active Filter : sets the active-filter option of the PPP daemon. This option specifies a packet filter (filter-expression) to be applied to data packets in order to determine which packets are regarded as link activity, and thereby, reset the idle timer. The filter-expression syntax is as described for tcpdump(1); however, qualifiers that do not apply to a PPP link, such as ether and arp , are not permitted. The default value is inbound . To disable the active-filter option, leave it blank. LCP Echo Interval : sets the lcp-echo-interval option of the PPP daemon. If set to a positive number, the modem sends LCP echo request to the peer at the specified number of seconds. To disable this option, set it to zero. This option may be used with the lcp-echo-failure option to detect that the peer is no longer connected. LCP Echo Failure : sets the lcp-echo-failure option of the PPP daemon. If set to a positive number, the modem presumes the peer to be dead if a specified number of LCP echo-requests are sent without receiving a valid LCP echo-reply. To disable this option, set it to zero. Enable GPS : enables GPS with the following conditions: One modem port will be dedicated to NMEA data stream. This port may not be used to send AT commands to the modem. PositionService should be enabled. Serial settings of PositionService should not be changed; it will be redirected to the modem GPS port automatically.","title":"Cellular Configuration"},{"location":"gateway-configuration/cellular-configuration/#cellular-linux-configuration","text":"This section describes the changes applied by Kura at the Linux networking configuration. Please read the following note before proceeding with manual changes of the Linux networking configuration. Warning It is NOT recommended performing manual editing of the Linux networking configuration files when the gateway configuration is being managed through Kura. While Linux may correctly accept manual changes, Kura may not be able to interpret the new configuration resulting in an inconsistent state. When the cellular configuration is submitted, Kura generates peer and chat scripts used by the PPP daemon to establish a PPP connection. Examples of these scripts for HSPA and EVDO modems are shown below.","title":"Cellular Linux Configuration"},{"location":"gateway-configuration/cellular-configuration/#example-peer-script-for-hspa-modem","text":"921600 unit 0 logfile /var/log/HE910-D_2-1.5 debug connect 'chat:v:f /etc/ppp/scripts/chat_HE910-D_2-1.5' disconnect 'chat:v:f /etc/ppp/scripts/disconnect_HE910-D_2-1.5' modem lock noauth noipdefault defaultroute usepeerdns noproxyarp novj novjccomp nobsdcomp nodeflate nomagic idle 95 active-filter 'inbound' persist holdoff 1 maxfail 5 connect-delay 1000","title":"Example Peer Script for HSPA Modem"},{"location":"gateway-configuration/cellular-configuration/#example-chat-script-for-hspa-modem","text":"ABORT \"BUSY\" ABORT \"VOICE\" ABORT \"NO CARRIER\" ABORT \"NO DIALTONE\" ABORT \"NO DIAL TONE\" ABORT \"ERROR\" \"\" \"+++ath\" OK \"AT\" OK AT+CGDCONT = 1 , \"IP\" , \"c1.korem2m.com\" OK \"\\d\\d\\d\" \"\" \"atd-99---1#\" CONNECT \"\\c\"","title":"Example Chat Script for HSPA Modem"},{"location":"gateway-configuration/cellular-configuration/#example-peer-script-for-evdo-modem","text":"921600 unit 0 logfile /var/log/DE910-DUAL_1-1.5 debug connect 'chat:v:f /etc/ppp/scripts/chat_DE910-DUAL_1-1.5' disconnect 'chat:v:f /etc/ppp/scripts/disconnect_DE910-DUAL_1-1.5' crtscts lock noauth defaultroute usepeerdns idle 95 active-filter 'inbound' persist holdoff 1 maxfail 5 connect-delay 10000","title":"Example Peer Script for EVDO Modem"},{"location":"gateway-configuration/cellular-configuration/#example-chat-script-for-evdo-modem","text":"ABORT \"BUSY\" ABORT \"VOICE\" ABORT \"NO CARRIER\" ABORT \"NO DIALTONE\" ABORT \"NO DIAL TONE\" ABORT \"ERROR\" \"\" \"+++ath\" OK \"AT\" OK \"ATE1V1&F&D2&C1&C2S0=0\" OK \"ATE1V1\" OK \"ATS7=60\" OK \"\\d\\d\\d\" \"\" \"atd#777\" CONNECT \"\\c\"","title":"Example Chat Script for EVDO Modem"},{"location":"gateway-configuration/cloud-connections/","text":"Cloud Connections The Cloud Connections section of the Kura Gateway Administration Console allows to create and manage cloud connections. By default, Kura starts with a single cloud connection, as depicted in the following image: The cloud services page allows to: - create a new cloud connection; - delete an existing cloud connection; - connect a selected cloud stack to the configured cloud platform; - disconnect the selected cloud stack from the connected cloud platform; - refresh the existing cloud connections. When clicking on the New button, a dialog is displayed as depicted in the image below: The user can select one of the existing cloud connection factories and give it a name (depending on the implementation, a name format can be suggested or forced). Selecting a created Cloud Connection it is possible to associate a new publisher/subscriber by clicking the New Pub/Sub button. As for the connection creation case, the user can select one of the existing publisher/subscriber factories and give it a name.","title":"Cloud Connections"},{"location":"gateway-configuration/cloud-connections/#cloud-connections","text":"The Cloud Connections section of the Kura Gateway Administration Console allows to create and manage cloud connections. By default, Kura starts with a single cloud connection, as depicted in the following image: The cloud services page allows to: - create a new cloud connection; - delete an existing cloud connection; - connect a selected cloud stack to the configured cloud platform; - disconnect the selected cloud stack from the connected cloud platform; - refresh the existing cloud connections. When clicking on the New button, a dialog is displayed as depicted in the image below: The user can select one of the existing cloud connection factories and give it a name (depending on the implementation, a name format can be suggested or forced). Selecting a created Cloud Connection it is possible to associate a new publisher/subscriber by clicking the New Pub/Sub button. As for the connection creation case, the user can select one of the existing publisher/subscriber factories and give it a name.","title":"Cloud Connections"},{"location":"gateway-configuration/cloud-service-configuration/","text":"Cloud Service Configuration The CloudService provides an easy-to-use API layer for the M2M application to communicate with a remote server. It operates as a decorator for the DataService , providing add-on features over the management of the DataTransport layer. In addition to simple publish/subscribe, the Cloud Connection API simplifies the implementation of more complex interaction flows like request/response or remote resource management. The Cloud Connection abstracts the developers from the complexity of the transport protocol and payload format used in the communication. The Cloud Connection allows a single connection to a remote server to be shared across more than one application in the gateway, providing the necessary topic partitioning. Its functions include: Adds application topic prefixes to allow a single remote server connection to be shared across applications. Defines a payload data model and provides default encoding/decoding serializers. Publishes life-cycle messages when the device and applications start and stop. To use this service, select the CloudService option located in the Cloud Services area as shown in the screen capture below. The CloudService provides the following configuration parameters: device.display-name : defines the device display name given by the system. (Required field). device.custom-name : defines the custom device display name if the device.display-name parameter is set to \"Custom\". topic.control-prefix : defines the topic prefix used for system and device management messages. encode.gzip : defines if the message payloads are sent compressed. republish.mqtt.birth.cert.on.gps.lock : when set to true, forces a republish of the MQTT Birth Certificate when a GPS correct position lock is received. The device is then registered with its real coordinates. (Required field). republish.mqtt.birth.cert.on.modem.detect : when set to true, forces a republish of the MQTT Birth Certificate when the service receives a modem detection event. (Required field). enable.default.subscriptions : manages the default subscriptions to the gateway management MQTT topics. When disabled, the gateway will not be remotely manageable. payload.encoding : specifies the encoding for the messages sent by the specific CloudService instance. Kura Protobuf - when this option is selected, the Kura Protobuf encoding will be used Simple JSON - the simple JSON encoding will be used instead. More information is available here . An example below. { \"sentOn\" : 1491298822 , \"position\" : { \"latitude\" : 45.234 , \"longitude\" : -7.3456 , \"altitude\" : 1.0 , \"heading\" : 5.4 , \"precision\" : 0.1 , \"speed\" : 23.5 , \"timestamp\" : 1191292288 , \"satellites\" : 3 , \"status\" : 2 }, \"metrics\" : { \"code\" : \"A23D44567Q\" , \"distance\" : 0.26456E+4 , \"temperature\" : 27.5 , \"count\" : 12354 , \"timestamp\" : 23412334545 , \"enable\" : true , \"rawBuffer\" : \"cGlwcG8gcGx1dG8gcGFwZXJpbm8=\" }, \"body\" : \"UGlwcG8sIHBsdXRvLCBwYXBlcmlubywgcXVpLCBxdW8gZSBxdWEu\" } The default CloudService implementations publishes the following lifecycle messages : BIRTH message : sent immediately when device is connected to the cloud platform; DISCONNECT message : sent immediately before device is disconnected from the cloud platform; delayed BIRTH message : sent when new cloud application handler becomes available, a DP is installed or removed, GPS position is locked (can be disabled), or when modem status changes (can be disabled). These messages are cached for 30 seconds before sending. If no other message of such type arrives the message is sent; otherwise the BIRTH is cached and the timeout restarts. This is to avoid sending multiple messages when the framework starts.","title":"Cloud Service Configuration"},{"location":"gateway-configuration/cloud-service-configuration/#cloud-service-configuration","text":"The CloudService provides an easy-to-use API layer for the M2M application to communicate with a remote server. It operates as a decorator for the DataService , providing add-on features over the management of the DataTransport layer. In addition to simple publish/subscribe, the Cloud Connection API simplifies the implementation of more complex interaction flows like request/response or remote resource management. The Cloud Connection abstracts the developers from the complexity of the transport protocol and payload format used in the communication. The Cloud Connection allows a single connection to a remote server to be shared across more than one application in the gateway, providing the necessary topic partitioning. Its functions include: Adds application topic prefixes to allow a single remote server connection to be shared across applications. Defines a payload data model and provides default encoding/decoding serializers. Publishes life-cycle messages when the device and applications start and stop. To use this service, select the CloudService option located in the Cloud Services area as shown in the screen capture below. The CloudService provides the following configuration parameters: device.display-name : defines the device display name given by the system. (Required field). device.custom-name : defines the custom device display name if the device.display-name parameter is set to \"Custom\". topic.control-prefix : defines the topic prefix used for system and device management messages. encode.gzip : defines if the message payloads are sent compressed. republish.mqtt.birth.cert.on.gps.lock : when set to true, forces a republish of the MQTT Birth Certificate when a GPS correct position lock is received. The device is then registered with its real coordinates. (Required field). republish.mqtt.birth.cert.on.modem.detect : when set to true, forces a republish of the MQTT Birth Certificate when the service receives a modem detection event. (Required field). enable.default.subscriptions : manages the default subscriptions to the gateway management MQTT topics. When disabled, the gateway will not be remotely manageable. payload.encoding : specifies the encoding for the messages sent by the specific CloudService instance. Kura Protobuf - when this option is selected, the Kura Protobuf encoding will be used Simple JSON - the simple JSON encoding will be used instead. More information is available here . An example below. { \"sentOn\" : 1491298822 , \"position\" : { \"latitude\" : 45.234 , \"longitude\" : -7.3456 , \"altitude\" : 1.0 , \"heading\" : 5.4 , \"precision\" : 0.1 , \"speed\" : 23.5 , \"timestamp\" : 1191292288 , \"satellites\" : 3 , \"status\" : 2 }, \"metrics\" : { \"code\" : \"A23D44567Q\" , \"distance\" : 0.26456E+4 , \"temperature\" : 27.5 , \"count\" : 12354 , \"timestamp\" : 23412334545 , \"enable\" : true , \"rawBuffer\" : \"cGlwcG8gcGx1dG8gcGFwZXJpbm8=\" }, \"body\" : \"UGlwcG8sIHBsdXRvLCBwYXBlcmlubywgcXVpLCBxdW8gZSBxdWEu\" } The default CloudService implementations publishes the following lifecycle messages : BIRTH message : sent immediately when device is connected to the cloud platform; DISCONNECT message : sent immediately before device is disconnected from the cloud platform; delayed BIRTH message : sent when new cloud application handler becomes available, a DP is installed or removed, GPS position is locked (can be disabled), or when modem status changes (can be disabled). These messages are cached for 30 seconds before sending. If no other message of such type arrives the message is sent; otherwise the BIRTH is cached and the timeout restarts. This is to avoid sending multiple messages when the framework starts.","title":"Cloud Service Configuration"},{"location":"gateway-configuration/data-service-configuration/","text":"Data Service Configuration The DataService provides the ability to connect to a remote broker, publish messages, subscribe to topics, receive messages on the subscribed topics, and disconnect from the remote message broker. The DataService delegates to the MqttDataTransport service the implementation of the transport protocol that is used to interact with the remote server. The DataService also adds the capability of storing published messages in a persistent store function and sending them over the wire at a later time. The purpose of this feature is to relieve service users from implementing their own persistent store. Service users may publish messages independently on the DataService connection status. Info Starting from Kura 5.3.0, the DataService allows to bind to custom persistent stores. A custom persistent store can be defined by creating an implementation the new org.eclipse.kura.message.store.provider.MessageStoreProvider service interface and registering it as an OSGi service. In order to overcome the potential latencies introduced by buffering messages, the DataService allows a priority level to be assigned to\u200b each published message. Depending on the store configuration, there are certain guarantees that stored messages are not lost due to sudden crashes or power outages. To use this service, select the DataService option located in the Cloud Connections area as shown in the screen capture below. The DataService offers methods and configuration options to manage the connection to the remote server including the following (all required) parameters described below. Connect Auto-on-startup - When set to true, the service tries to auto-connect to the remote server on start-up and restore the connection every time the device is disconnected. These attempts are made at the frequency defined in the Connect Retry-interval parameter until the connection is established. Using the Connect/Disconnect button disables this function. Connect Retry-interval - Frequency in seconds to retry a connection of the Data Publishers after a disconnect. Enable Recovery On Connection Failure - Enables the recovery feature on connection failure. If the device is not able to connect to a remote cloud platform, the service will wait for a specified amount of connection retries. If the recovery fails, the device will be rebooted. Being based on the Watchdog service, it needs to be activated as well. Connection Recovery Max Failure - Number of failures in Data Publishers connection before forcing a reboot. Disconnect Quiesce-timeout - Allows the delivery of in-flight messages to be completed before disconnecting from the broker when a disconnection from the broker is being forced. Message Store Provider Service PID - The Kura service pid of the Message Store instance to be used. The pid of the default instance is org.eclipse.kura.db.H2DbService. The Message Store instance must implement the org.eclipse.kura.message.store.provider.MessageStoreProvider interface. Store Housekeeper-interval - Defines the interval in seconds used to run the Data Store housekeeper task. Store Purge-age - defines the age in seconds of completed messages (either published with QoS = 0 or confirmed with QoS > 0) after which they are deleted (minimum 5). Store Capacity - Defines the maximum number of messages persisted in the Data Store. In-flight-messages parameters - Define the management of messages that have been published and not yet confirmed, including: In-flight-messages Republish-on-new-session - Whether to republish in-flight messages on a new MQTT session. In-flight-messages Max-number - The maximum number of in-flight messages. In-flight-messages Congestion-timeout - Timeouts the in-flight messages congestion condition. The service will force a disconnect attempting to reconnect (0 to disable). Connection Monitors The DataService offers methods and configuration options to monitor the connection to the remote server and, eventually, cause a system reboot to recover from transient network problems. This feature, if enabled, leverages the watchdog service and reboots the gateway if the maximum number of configured connection attempts has been made. A reboot is not requested if the connection to the remote broker succeeds but an authentication error , an invalid client id or an authorization error is thrown by the remote cloud platform and causes a connection drop. The image below shows the parameters that need to be tuned in order to enable this connection monitor feature. To configure this functionality, the System Administrator needs to specify the following configuration elements: Enable Recovery On Connection Failure : when enabled, activates the recovery feature on connection failure: if the device is not able to connect to a remote cloud platform, the service will wait for a specified amount of connection retries. If the recovery fails, the device will be rebooted. Being based on the Watchdog service, it needs to be activated as well. Connection Recovery Max Failure : related to the previous parameter. It specifies the number of failures before a reboot is requested. !!! warning To be fully working, this feature needs the enabling of the Watchdog Service. Message Publishing Backoff Delay In order to have a finer control on the data flow, when a device reconnects to a remote cloud platform, Kura integrates into the Data Service a Backoff delay feature that limits the rate of messages sent. This feature, enabled by default, integrates the Token Bucket concept to limit the bursts of messages sent to a remote cloud platform. In the image below, the parameters that need to be tuned, in the Data Service, to take advantage of this feature: Enable Rate Limit - Enables the token bucket message rate limiting. Rate Limit Average - he average message publish rate in number of messages per unit of time (e.g. 10 messages per MINUTE). Danger The maximum allowed message rate is 1 message per millisecond , so the following limitations are applied: 86400000 per DAY 3600000 per HOUR 60000 messages per MINUTE 1000 messages per SECOND Rate Limit Time Unit - The time unit for the Rate Limit Average. Rate Limit Burst Size - The token bucket burst size. The default setup limits the data flow to 1 message per second with a bucket size of 1 token . Warning This feature needs to be properly tuned by the System Administrator in order to prevent delays in the remote cloud platform due to messages stacked at the edge. If not sure of the number of messages that your gateways will try to push to the remote platform, we suggest to disable this feature. Connection schedule Starting from Kura 5.3.0, the Data Service supports a configurable time based connection schedule. If this functionality is enabled, the Data Service will connect at specific time instants represented by a configurable Cron expression, keep the connection open until it becomes idle and then disconnect until the next instant that matches the expression. More in detail, the connection logic is as follows: The DataService parses the confgiured Cron expression and schedules a connection attempt at the next instant that matches the expression. When the connection instant is reached, the logic continues from step 2. The Data Service will start the auto connect logic. One or more connection attempts will be performed until the connection is established honoring the connect.retry-interval parameter. The Data Service starts a timer that ticks after connection.schedule.inactivity.interval.seconds seconds. When the timer ticks the connection will be closed, and the logic resumed from step 1. The timer is reset delaying the disconnection when a message is published or confirmed (for QoS >= 1). The connection will not be closed if there are messages with QoS >= 1 that have not been confirmed yet. If an unexpected connection drop occurs in this phase, the logic will resume from step 2. The Data Service will attempt to detect large time shifts in system clock, if a time shift is detected, the logic will switch to step 1, rescheduling the next connection attempt. The relevant configuration parameters are the following: Enable Connection Schedule : Enables or disables the connection schedule feature. Please note that in order to enable the connection logic, the Connect Auto-on-startup parameter must be set to true as well. Connection Schedule CRON Expression : A CRON expression that specifies the instants when the gateway should perform a connection attempt. This parameter is only used if Enable Connection Schedule is set to true. The default expression schedules a connection every day at midnight. Allow priority message to overide connection schedule - Allows messages beyond a specified priority to force a connection and be sent regardless of connection schedule. Message schedule priority override threshold - A message with a priority equal to or less than this threshold will cause the framework to automatically re-connect and send regardless of the connection schedule. Connection Schedule Disconnect Inactivity Interval Second : Specifies an inactivity timeout in seconds. If the timeout expires, the cloud connection will be automatically closed. This parameter is only used if Enable Connection Schedule is set to true. Payload size limiting Starting from Kura 5.3.0, the DataService allows to limit the maximum payload size for published messages. Attempts to publish a payload larger than the configured threshold will fail with a KuraStoreException. The threshold can be configured with the following parameter: Maximum Payload Size : The maximum allowed size in bytes for the message payload. In order to keep backwards compatibility, the default value for the parameter is set to 16777216 bytes, which is the maximum allowed size by the current H2DbService implementation.","title":"Data Service Configuration"},{"location":"gateway-configuration/data-service-configuration/#data-service-configuration","text":"The DataService provides the ability to connect to a remote broker, publish messages, subscribe to topics, receive messages on the subscribed topics, and disconnect from the remote message broker. The DataService delegates to the MqttDataTransport service the implementation of the transport protocol that is used to interact with the remote server. The DataService also adds the capability of storing published messages in a persistent store function and sending them over the wire at a later time. The purpose of this feature is to relieve service users from implementing their own persistent store. Service users may publish messages independently on the DataService connection status. Info Starting from Kura 5.3.0, the DataService allows to bind to custom persistent stores. A custom persistent store can be defined by creating an implementation the new org.eclipse.kura.message.store.provider.MessageStoreProvider service interface and registering it as an OSGi service. In order to overcome the potential latencies introduced by buffering messages, the DataService allows a priority level to be assigned to\u200b each published message. Depending on the store configuration, there are certain guarantees that stored messages are not lost due to sudden crashes or power outages. To use this service, select the DataService option located in the Cloud Connections area as shown in the screen capture below. The DataService offers methods and configuration options to manage the connection to the remote server including the following (all required) parameters described below. Connect Auto-on-startup - When set to true, the service tries to auto-connect to the remote server on start-up and restore the connection every time the device is disconnected. These attempts are made at the frequency defined in the Connect Retry-interval parameter until the connection is established. Using the Connect/Disconnect button disables this function. Connect Retry-interval - Frequency in seconds to retry a connection of the Data Publishers after a disconnect. Enable Recovery On Connection Failure - Enables the recovery feature on connection failure. If the device is not able to connect to a remote cloud platform, the service will wait for a specified amount of connection retries. If the recovery fails, the device will be rebooted. Being based on the Watchdog service, it needs to be activated as well. Connection Recovery Max Failure - Number of failures in Data Publishers connection before forcing a reboot. Disconnect Quiesce-timeout - Allows the delivery of in-flight messages to be completed before disconnecting from the broker when a disconnection from the broker is being forced. Message Store Provider Service PID - The Kura service pid of the Message Store instance to be used. The pid of the default instance is org.eclipse.kura.db.H2DbService. The Message Store instance must implement the org.eclipse.kura.message.store.provider.MessageStoreProvider interface. Store Housekeeper-interval - Defines the interval in seconds used to run the Data Store housekeeper task. Store Purge-age - defines the age in seconds of completed messages (either published with QoS = 0 or confirmed with QoS > 0) after which they are deleted (minimum 5). Store Capacity - Defines the maximum number of messages persisted in the Data Store. In-flight-messages parameters - Define the management of messages that have been published and not yet confirmed, including: In-flight-messages Republish-on-new-session - Whether to republish in-flight messages on a new MQTT session. In-flight-messages Max-number - The maximum number of in-flight messages. In-flight-messages Congestion-timeout - Timeouts the in-flight messages congestion condition. The service will force a disconnect attempting to reconnect (0 to disable).","title":"Data Service Configuration"},{"location":"gateway-configuration/data-service-configuration/#connection-monitors","text":"The DataService offers methods and configuration options to monitor the connection to the remote server and, eventually, cause a system reboot to recover from transient network problems. This feature, if enabled, leverages the watchdog service and reboots the gateway if the maximum number of configured connection attempts has been made. A reboot is not requested if the connection to the remote broker succeeds but an authentication error , an invalid client id or an authorization error is thrown by the remote cloud platform and causes a connection drop. The image below shows the parameters that need to be tuned in order to enable this connection monitor feature. To configure this functionality, the System Administrator needs to specify the following configuration elements: Enable Recovery On Connection Failure : when enabled, activates the recovery feature on connection failure: if the device is not able to connect to a remote cloud platform, the service will wait for a specified amount of connection retries. If the recovery fails, the device will be rebooted. Being based on the Watchdog service, it needs to be activated as well. Connection Recovery Max Failure : related to the previous parameter. It specifies the number of failures before a reboot is requested. !!! warning To be fully working, this feature needs the enabling of the Watchdog Service.","title":"Connection Monitors"},{"location":"gateway-configuration/data-service-configuration/#message-publishing-backoff-delay","text":"In order to have a finer control on the data flow, when a device reconnects to a remote cloud platform, Kura integrates into the Data Service a Backoff delay feature that limits the rate of messages sent. This feature, enabled by default, integrates the Token Bucket concept to limit the bursts of messages sent to a remote cloud platform. In the image below, the parameters that need to be tuned, in the Data Service, to take advantage of this feature: Enable Rate Limit - Enables the token bucket message rate limiting. Rate Limit Average - he average message publish rate in number of messages per unit of time (e.g. 10 messages per MINUTE). Danger The maximum allowed message rate is 1 message per millisecond , so the following limitations are applied: 86400000 per DAY 3600000 per HOUR 60000 messages per MINUTE 1000 messages per SECOND Rate Limit Time Unit - The time unit for the Rate Limit Average. Rate Limit Burst Size - The token bucket burst size. The default setup limits the data flow to 1 message per second with a bucket size of 1 token . Warning This feature needs to be properly tuned by the System Administrator in order to prevent delays in the remote cloud platform due to messages stacked at the edge. If not sure of the number of messages that your gateways will try to push to the remote platform, we suggest to disable this feature.","title":"Message Publishing Backoff Delay"},{"location":"gateway-configuration/data-service-configuration/#connection-schedule","text":"Starting from Kura 5.3.0, the Data Service supports a configurable time based connection schedule. If this functionality is enabled, the Data Service will connect at specific time instants represented by a configurable Cron expression, keep the connection open until it becomes idle and then disconnect until the next instant that matches the expression. More in detail, the connection logic is as follows: The DataService parses the confgiured Cron expression and schedules a connection attempt at the next instant that matches the expression. When the connection instant is reached, the logic continues from step 2. The Data Service will start the auto connect logic. One or more connection attempts will be performed until the connection is established honoring the connect.retry-interval parameter. The Data Service starts a timer that ticks after connection.schedule.inactivity.interval.seconds seconds. When the timer ticks the connection will be closed, and the logic resumed from step 1. The timer is reset delaying the disconnection when a message is published or confirmed (for QoS >= 1). The connection will not be closed if there are messages with QoS >= 1 that have not been confirmed yet. If an unexpected connection drop occurs in this phase, the logic will resume from step 2. The Data Service will attempt to detect large time shifts in system clock, if a time shift is detected, the logic will switch to step 1, rescheduling the next connection attempt. The relevant configuration parameters are the following: Enable Connection Schedule : Enables or disables the connection schedule feature. Please note that in order to enable the connection logic, the Connect Auto-on-startup parameter must be set to true as well. Connection Schedule CRON Expression : A CRON expression that specifies the instants when the gateway should perform a connection attempt. This parameter is only used if Enable Connection Schedule is set to true. The default expression schedules a connection every day at midnight. Allow priority message to overide connection schedule - Allows messages beyond a specified priority to force a connection and be sent regardless of connection schedule. Message schedule priority override threshold - A message with a priority equal to or less than this threshold will cause the framework to automatically re-connect and send regardless of the connection schedule. Connection Schedule Disconnect Inactivity Interval Second : Specifies an inactivity timeout in seconds. If the timeout expires, the cloud connection will be automatically closed. This parameter is only used if Enable Connection Schedule is set to true.","title":"Connection schedule"},{"location":"gateway-configuration/data-service-configuration/#payload-size-limiting","text":"Starting from Kura 5.3.0, the DataService allows to limit the maximum payload size for published messages. Attempts to publish a payload larger than the configured threshold will fail with a KuraStoreException. The threshold can be configured with the following parameter: Maximum Payload Size : The maximum allowed size in bytes for the message payload. In order to keep backwards compatibility, the default value for the parameter is set to 16777216 bytes, which is the maximum allowed size by the current H2DbService implementation.","title":"Payload size limiting"},{"location":"gateway-configuration/data-transport-service-configuration/","text":"Data Transport Service Configuration The DataTransport service provides the ability to connect to a remote broker, publish messages, subscribe to topics, receive messages on the subscribed topics, and disconnect from the remote message broker. To use this service, select the MqttDataTransport option located in the Cloud Connections area as shown in the screen captures below. The MqttDataTransport service provides the following configuration parameters: broker-url : defines the URL of the MQTT broker to connect to. For the Everyware Cloud sandbox, this address is either mqtt://broker-sbx.everyware.io:1883/ or mqtts://broker-sbx.everyware.io:8883/ for an encrypted connection. (Required field). topic.context.account-name : defines the name of the account to which the device belongs. username and password : define the username and password that have been assigned to the device by the account administrator (generally username is account-name_broker). (Required field). client-id : defines the identifier of the MQTT client representing the device when connecting to the MQTT broker. If left empty, it is automatically determined by the client software as the MAC address of the main network interface (in general numbers and uppercase letters without ':'). This identifier has to be unique within your account. keep-alive : defines the \"keep alive\" interval measured in seconds. It specifies the maximum amount of time that should pass without communication between the client and the server. The client will ensure that at least one message travels across the network within each keep alive period. In the absence of a data-related message during this time period, the client will send a very small MQTT \"ping\" message that the server will acknowledge. The keep alive interval enables the client to detect when the server is no longer available without having to wait for the long TCP/IP timeout. (Required field). Warning The keep-alive interval may \"conflict\" with the TCP idle timeout set at the TCP/IP level. As a best practice the TCP idle timeout should be at least 1,5 times the keep-alive time interval. If the TCP idle timeout is less or equal the keep-alive, the MQTT connection may be dropped due to the TCP idle timeout expiration. timeout : sets the timeout used for all interactions with the MQTT broker. (Required field). clean-session : controls the behavior of both the client and the server at the time of connection and disconnection. When this parameter is set to true, the state information is discarded at connection and disconnection; when set to false, the state information is maintained. (Required field). lwt parameters: define the MQTT \"Last Will and Testament\" (LWT) settings for the client. In the event that the client unexpectedly loses its connection to the server, the server publishes the LWT message (lwt.payload) to the LWT topic on behalf of the client. This allows other clients (subscribed to the LWT topic) to be made aware that the client has disconnected. LWT parameters that may be configured include: lwt.topic lwt.payload lwt.qos lwt.retain in-flight.persistence : defines the storage type where in-flight messages are persisted across reconnections. They may be stored in memory, or in a file on the disk. (Required field). protocol-version : defines the MQTT Protocol version to be used. This value may be 3.1 or 3.1.1. SSL parameters: define the SSL specific settings for the client. SSL parameters that can be configured include: ssl.default.protocol ssl.hostname.verification ssl.default.cipherSuites ssl.certificate.alias","title":"Data Transport Service Configuration"},{"location":"gateway-configuration/data-transport-service-configuration/#data-transport-service-configuration","text":"The DataTransport service provides the ability to connect to a remote broker, publish messages, subscribe to topics, receive messages on the subscribed topics, and disconnect from the remote message broker. To use this service, select the MqttDataTransport option located in the Cloud Connections area as shown in the screen captures below. The MqttDataTransport service provides the following configuration parameters: broker-url : defines the URL of the MQTT broker to connect to. For the Everyware Cloud sandbox, this address is either mqtt://broker-sbx.everyware.io:1883/ or mqtts://broker-sbx.everyware.io:8883/ for an encrypted connection. (Required field). topic.context.account-name : defines the name of the account to which the device belongs. username and password : define the username and password that have been assigned to the device by the account administrator (generally username is account-name_broker). (Required field). client-id : defines the identifier of the MQTT client representing the device when connecting to the MQTT broker. If left empty, it is automatically determined by the client software as the MAC address of the main network interface (in general numbers and uppercase letters without ':'). This identifier has to be unique within your account. keep-alive : defines the \"keep alive\" interval measured in seconds. It specifies the maximum amount of time that should pass without communication between the client and the server. The client will ensure that at least one message travels across the network within each keep alive period. In the absence of a data-related message during this time period, the client will send a very small MQTT \"ping\" message that the server will acknowledge. The keep alive interval enables the client to detect when the server is no longer available without having to wait for the long TCP/IP timeout. (Required field). Warning The keep-alive interval may \"conflict\" with the TCP idle timeout set at the TCP/IP level. As a best practice the TCP idle timeout should be at least 1,5 times the keep-alive time interval. If the TCP idle timeout is less or equal the keep-alive, the MQTT connection may be dropped due to the TCP idle timeout expiration. timeout : sets the timeout used for all interactions with the MQTT broker. (Required field). clean-session : controls the behavior of both the client and the server at the time of connection and disconnection. When this parameter is set to true, the state information is discarded at connection and disconnection; when set to false, the state information is maintained. (Required field). lwt parameters: define the MQTT \"Last Will and Testament\" (LWT) settings for the client. In the event that the client unexpectedly loses its connection to the server, the server publishes the LWT message (lwt.payload) to the LWT topic on behalf of the client. This allows other clients (subscribed to the LWT topic) to be made aware that the client has disconnected. LWT parameters that may be configured include: lwt.topic lwt.payload lwt.qos lwt.retain in-flight.persistence : defines the storage type where in-flight messages are persisted across reconnections. They may be stored in memory, or in a file on the disk. (Required field). protocol-version : defines the MQTT Protocol version to be used. This value may be 3.1 or 3.1.1. SSL parameters: define the SSL specific settings for the client. SSL parameters that can be configured include: ssl.default.protocol ssl.hostname.verification ssl.default.cipherSuites ssl.certificate.alias","title":"Data Transport Service Configuration"},{"location":"gateway-configuration/device-information/","text":"Device Information The Device section provides several information about the gateway where Kura is running on. This section can be accessed by selecting the Device option located in the System area. Profile The Profile tab shows several information about the gateway, organized under the Device, Hardware, Software and Java Information. Bundles This tab lists all the bundles installed on Kura, with details about the name, version, id, state and signature status. The signature value will be true if the corresponding bundle is signed, false otherwise. The buttons in the upper part of the tab allows the user to manage the listed bundles: Start Bundle : starts a bundle that is in Resolved or Installed state; Stop Bundle : stops a bundle that is in Active state; Refresh : reloads the bundles states list. Containers The Containers tab lists the containers and images that are currently managed by the Container Orchestration Service . From this tab, the user can start and stop containers and delete images. Threads The Threads tab shows a list of the threads that are currently running in the JVM. System Packages The System Packages tab shows the list of all the Linux packages installed on the OS. The package is detailed with the name, version and type (DEB/RPM/APK). System Properties The System Properties tab shows a list of relevant properties including OS and JVM parameters. Command A detailed description of this tab is presented in the Command Service page. System Logs The System Logs tab allows downloading a compressed file containing all the relevant log files from the gateway. The download button creates and downloads a compressed file with the following items: all the files in /var/log or the content of the folder defined by the kura.log.download.sources property; the content of the journal for the Kura process ( kura-journal.log ); the content of the journal for the whole system ( system-journal.log ). In addition to this feature, the page also allows the real-time displaying of system logs, if the framework has the availability of one or more components that implement the LogProvider API. The UI also provides a useful button to open a new Kura instance in a new browser window. A reference implementation of the LogProvider API is provided in the org.eclipse.kura.log.filesystem.provider bundle. This bundle exposes in the framework a factory that can be used to read filesystem files. By default, Eclipse Kura creates two log providers at startup: one that reads from /var/log/kura.log and the other that reads from /var/log/kura-audit.log . The collected logs are stored in a cache server-side and are collected from the point in time where the log providers get attached to the UI (usually, from the login or after a refresh of the browser's window). When the section \"System Logs\" is accessed, the new log entries are polled from the server's cache and stored client-side.","title":"Device Information"},{"location":"gateway-configuration/device-information/#device-information","text":"The Device section provides several information about the gateway where Kura is running on. This section can be accessed by selecting the Device option located in the System area.","title":"Device Information"},{"location":"gateway-configuration/device-information/#profile","text":"The Profile tab shows several information about the gateway, organized under the Device, Hardware, Software and Java Information.","title":"Profile"},{"location":"gateway-configuration/device-information/#bundles","text":"This tab lists all the bundles installed on Kura, with details about the name, version, id, state and signature status. The signature value will be true if the corresponding bundle is signed, false otherwise. The buttons in the upper part of the tab allows the user to manage the listed bundles: Start Bundle : starts a bundle that is in Resolved or Installed state; Stop Bundle : stops a bundle that is in Active state; Refresh : reloads the bundles states list.","title":"Bundles"},{"location":"gateway-configuration/device-information/#containers","text":"The Containers tab lists the containers and images that are currently managed by the Container Orchestration Service . From this tab, the user can start and stop containers and delete images.","title":"Containers"},{"location":"gateway-configuration/device-information/#threads","text":"The Threads tab shows a list of the threads that are currently running in the JVM.","title":"Threads"},{"location":"gateway-configuration/device-information/#system-packages","text":"The System Packages tab shows the list of all the Linux packages installed on the OS. The package is detailed with the name, version and type (DEB/RPM/APK).","title":"System Packages"},{"location":"gateway-configuration/device-information/#system-properties","text":"The System Properties tab shows a list of relevant properties including OS and JVM parameters.","title":"System Properties"},{"location":"gateway-configuration/device-information/#command","text":"A detailed description of this tab is presented in the Command Service page.","title":"Command"},{"location":"gateway-configuration/device-information/#system-logs","text":"The System Logs tab allows downloading a compressed file containing all the relevant log files from the gateway. The download button creates and downloads a compressed file with the following items: all the files in /var/log or the content of the folder defined by the kura.log.download.sources property; the content of the journal for the Kura process ( kura-journal.log ); the content of the journal for the whole system ( system-journal.log ). In addition to this feature, the page also allows the real-time displaying of system logs, if the framework has the availability of one or more components that implement the LogProvider API. The UI also provides a useful button to open a new Kura instance in a new browser window. A reference implementation of the LogProvider API is provided in the org.eclipse.kura.log.filesystem.provider bundle. This bundle exposes in the framework a factory that can be used to read filesystem files. By default, Eclipse Kura creates two log providers at startup: one that reads from /var/log/kura.log and the other that reads from /var/log/kura-audit.log . The collected logs are stored in a cache server-side and are collected from the point in time where the log providers get attached to the UI (usually, from the login or after a refresh of the browser's window). When the section \"System Logs\" is accessed, the new log entries are polled from the server's cache and stored client-side.","title":"System Logs"},{"location":"gateway-configuration/ethernet-configuration/","text":"Ethernet Configuration As described in the Network Configuration section, Ethernet interfaces have two configuration tabs: TCP/IP and DHCP & NAT . Each Ethernet interface may be configured either as LAN or WAN; it may also be disabled. If the interface is designated as LAN and is manually configured, the DHCP & NAT tab is enabled to allow DHCP server and/or 'many-to-one' NAT setup; otherwise, the DHCP & NAT tab is disabled. For more information on TCP/IP and DHCP & NAT settings, please refer to the Network Configuration section.","title":"Ethernet Configuration"},{"location":"gateway-configuration/ethernet-configuration/#ethernet-configuration","text":"As described in the Network Configuration section, Ethernet interfaces have two configuration tabs: TCP/IP and DHCP & NAT . Each Ethernet interface may be configured either as LAN or WAN; it may also be disabled. If the interface is designated as LAN and is manually configured, the DHCP & NAT tab is enabled to allow DHCP server and/or 'many-to-one' NAT setup; otherwise, the DHCP & NAT tab is disabled. For more information on TCP/IP and DHCP & NAT settings, please refer to the Network Configuration section.","title":"Ethernet Configuration"},{"location":"gateway-configuration/firewall-configuration/","text":"Firewall Configuration Kura offers easy management of the Linux firewall iptables and ip6tables included in an IoT Gateway. Additionally, Kura provides the ability to manage network access security to an IoT Gateway for both IPv4 and IPv6 through the following: Open Ports (local service rules) Port Forwarding IP Forwarding and Masquerading (NAT service rules) 'Automatic' NAT service rules Open Ports, Port Forwarding, and IP Forwarding and Masquerading are configured via respective Firewall configuration tabs. 'Automatic' NAT is enabled for each local (LAN) interface using the DHCP & NAT tab of the respective interface configuration. While the IPv4 Firewall configuration capability is present on all IoT Gateways, the IPv6 Firewall is present only on devices that support IPv6 Networking. Firewall Linux Configuration This section describes the changes applied by Kura at the Linux networking configuration. Please read the following note before proceeding with manual changes of the Linux networking configuration. Warning It is NOT recommended performing manual editing of the Linux networking configuration files when the gateway configuration is being managed through Kura. While Linux may correctly accept manual changes, Kura may not be able to interpret the new configuration resulting in an inconsistent state. When a new firewall configuration is submitted, Kura immediately applies it using the iptables service provided by the OS. Moreover, the rules are stored in the filesystem and a new Kura snapshot is generated containing the new configuration. At the next startup, the firewall service in the OS will re-apply them and Kura will check the firewall configuration against the one contained in the last snapshot. In this way, the user can update the snapshot with the needed rules and apply them to the system using the webUI or modify the snapshot_0.xml before the first start of Kura. In order to allow a better coexistence between Kura and external applications that need to modify firewall rules, Kura writes its rules to a set of custom iptables chains. They are input-kura , output-kura , forward-kura , forward-kura-pf and forward-kura-ipf for the filter table and input-kura , output-kura , prerouting-kura , prerouting-kura-pf , postrouting-kura , postrouting-kura-pf and postrouting-kura-ipf for the nat table. The custom chains are then put in their respective standard iptables chains, as shown in the following: iptables -t filter -I INPUT -j input-kura iptables -t filter -I OUTPUT -j output-kura iptables -t filter -I FORWARD -j forward-kura iptables -t filter -I forward-kura -j forward-kura-pf iptables -t filter -I forward-kura -j forward-kura-ipf iptables -t nat -I PREROUTING -j prerouting-kura iptables -t nat -I prerouting-kura -j prerouting-kura-pf iptables -t nat -I INPUT -j input-kura iptables -t nat -I OUTPUT -j output-kura iptables -t nat -I POSTROUTING -j postrouting-kura iptables -t nat -I postrouting-kura -j postrouting-kura-pf iptables -t nat -I postrouting-kura -j postrouting-kura-ipf The same custom chains are used in the IPv6 case. Even if many firewall rules can be handled by Kura, it could be that some rules cannot be filled through the Web Console. In this case, custom firewall rules may be added to the /etc/init.d/firewall_cust script manually. These rules are applied/reapplied every time the firewall service starts, that is at the gateway startup. These custom rules should not be applied to the Kura custom chains, but to the standard ones. Open Ports If Kura is running on a gateway, all TCP/UDP ports are closed by default unless they are listed in the Open Ports IPv4 or Open Ports IPv6 tab of the Firewall section in the Gateway Administration Console, or in the /etc/sysconfig/iptables script. Therefore, if a user needs to connect to a specific port on a gateway, it is insufficient to have an application listening on the desired port; the port also needs to be opened in the firewall. To open a port using the Gateway Administration Console, select the Firewall option located in the System area. The Firewall configuration display appears in the main window. With the Open Ports IPv4 or Open Ports IPV6 tab selected, click the New button. The New Open Port Entry form appears. The New Open Port Entry form contains the following configuration parameters: Port : specifies the port to be opened. (Required field.) Protocol : defines the protocol (tcp or udp). (Required field.) Permitted Network : only allows packets originated by a host on this network. Permitted Interface Name : only allows packets arrived on this interface. Unpermitted Interface Name : blocks packets arrived on this interface. Permitted MAC Address : only allows packets originated by this host. Source Port Range : only allows packets with source port in the defined range. Complete the New Open Port Entry form and click the Submit button when finished. Once the form is submitted, a new port entry will appear. Click the Apply button for the change to take effect. The firewall rules related to the open ports section are stored in the input-kura custom chain of the IPv4/IPv6 filter table. Port Forwarding Port forwarding rules are needed to establish connectivity from the WAN side to a specific port on a host that resides on a LAN behind the gateway. In this case, a routing solution may be avoided since the connection is made to a specified external port on a gateway, and packets are forwarded to an internal port on the destination host; therefore, it is not necessary to add the external port to the list of open ports. To add a port forwarding rule, select the Port Forwarding IPv4 or Port Forwarding IPv6 tab on the Firewall display and click the New button. The Port Forward Entry form appears. The Port Forward Entry form contains the following configuration parameters: Input Interface : specifies the interface through which a packet is going to be received. (Required field). Output Interface : specifies the interface through which a packet is going to be forwarded to its destination. (Required field). LAN Address : supplies the IP address of destination host. (Required field). Protocol : defines the protocol (tcp or udp). (Required field). External Port : provides the external destination port on gateway unit. (Required field). Internal Port : provides the port on a destination host. (Required field). Enable Masquerading : defines whether masquerading is used (yes or no). If enabled, the gateway replaces the IP address of the originating host with the IP address of its own output (LAN) interface. This is needed when the destination host does not have a back route to the originating host (or default gateway route) via the gateway unit. The masquerading option is provided with port forwarding to limit gateway forwarding only to the destination port. (Required field). Permitted Network : only forwards if the packet is originated from a host on this network. Permitted MAC Address : only forwards if the packet is originated by this host. Source Port Range : only forwards if the packet's source port is within the defined range. Complete the Port Forward Entry form and click the Apply button for the desired port forwarding rules to take effect. The firewall rules related to the port forwarding section are stored in the forward-kura-pf custom chain of the IPv4/IPv6 filter table and in the postrouting-kura-pf and prerouting-kura-pf chains of the IPv4/IPv6 nat table. Port Forwarding example This section describes an example of port forwarding rules applied to the IPv4 case. The initial setup is described below. A couple of RaspberryPi that shares the same LAN over Ethernet. The first RaspberryPi running Kura is configured as follows: The eth0 interface static with IP address of 172.16.0.5. There is no default gateway. The second RaspberryPi running Kura is configured as follows: The eth0 interface LAN/static with IP address of 172.16.0.1/24 and no NAT. The wlan0 interface is WAN/DHCP client. A laptop is connected to the same network of the wlan0 of the second RaspberryPi and can ping its wlan0 interface. The purpose of the second RaspberryPi configuration is to enable access to the Administration Console running on the first one (port 80) by connecting to the second RaspberryPi's port 8080 over the wlan. This scenario assumes that IP addresses are assigned as follows: Second RaspberryPi wlan0 - 10.200.12.6 Laptop wlan0 - 10.200.12.10 The following port forwarding entries are added to the second RaspberryPi configuration as described above using the Port Forward Entry form: Input Interface - wlan0 Output Interface - eth0 LAN Address - 172.16.0.5 Protocol - tcp External Port - 8080 Internal Port - 80 Masquerade - yes The Permitted Network , Permitted MAC Address , and Source Port Range fields are left blank. The following iptables rules are applied and added to the /etc/sysconfig/iptables file: iptables -t nat -A prerouting-kura-pf -i wlan0 -p tcp -s 0 .0.0.0/0 --dport 8080 -j DNAT --to 172 .16.0.5:80 iptables -t nat -A postrouting-kura-pf -o eth0 -p tcp -d 172 .16.0.5 -j MASQUERADE iptables -A forward-kura-pf -i wlan0 -o eth0 -p tcp -s 0 .0.0.0/0 --dport 80 -d 172 .16.0.5 -j ACCEPT iptables -A forward-kura-pf -i eth0 -o wlan0 -p tcp -s 172 .16.0.5 -m state --state RELATED,ESTABLISHED -j ACCEPT The following iptables commands may be used to verify that the new rules have been applied: sudo iptables -v -n -L sudo iptables -v -n -L -t nat At this point, it is possible to try to connect to http://10.200.12.6 and to http://10.200.12.6:8080 from the laptop. Note that when a connection is made to the device on port 80, it is to the Kura configuration page on the device itself (the second RaspberryPi). When the gateway is connected on port 8080, you are forwarded to the Kura Gateway Administration Console on the first RaspberryPi. The destination host can only be reached by connecting to the gateway on port 8080. Another way to connect to the Kura Gateway Administration Console on the first RaspberryPi would be to add an IP Forwarding/Masquerading entry as described in the next section. IP Forwarding/Masquerading The advantage of the Automatic NAT method is its simplicity. However, this approach does not handle reverse NATing, and it cannot be used for interfaces that are not listed in the Gateway Administration Console (such as VPN tun0 interface). To set up generic (one-to-many) NATing, select the IP Forwarding/Masquerading IPv4 or IP Forwarding/Masquerading IPv6 tab on the Firewall display. Press the New button and the IP Forwarding/Masquerading form appears. The IP Forwarding/Masquerading form contains the following configuration parameters: Input Interface : specifies the interface through which a packet is going to be received. (Required field). Output Interface : specifies the interface through which a packet is going to be forwarded to its destination. (Required field). Protocol : defines the protocol of the rule to check (all, tcp, or udp). (Required field). Source Network/Host : identifies the source network or host name (CIDR notation). Set to IPv4 0.0.0.0/0 or IPv6 ::/0 if empty. Destination Network/Host : identifies the destination network or host name (CIDR notation). Set to IPv4 0.0.0.0/0 or IPv6 ::/0 if empty. Enable Masquerading : defines whether masquerading is used (yes or no). If set to 'yes', masquerading is enabled. If set to 'no', only FORWARDING rules are be added. (Required field). The rules will be added to the forward-kura-ipf chain in the IPv4/IPv6 filter table and in the postrouting-kura-ipf one in the IPv4/IPv6 nat table. As a use-case scenario, consider the same setup as in port forwarding, but with cellular interface disabled and eth1 interface configured as WAN/DHCP client. In this case, the interfaces of the gateway are configured as follows: eth0 : LAN/Static/No NAT 172.16.0.1/24 eth1 : WAN/DHCP 10.11.5.4/24 To reach the gateway sitting on the 172.16.0.5/24 from a specific host on the 10.11.0.0/16 network, set up the following Reverse NAT entry: Input Interface: eth1 (WAN interface) Output Interface: eth0 (LAN interface) Protocol: all Source Network/Host: 10.11.5.21/32 Destination Network/Host: 172.16.0.5/32 Enable Masquerading: yes This case applies the following iptables rules: iptables -t nat -A postrouting-kura-ipf -p tcp -s 10 .11.5.21/32 -d 172 .16.0.5/32 -o eth0 -j MASQUERADE iptables -A forward-kura-ipf -p tcp -s 172 .16.0.5/32 -i eth0 -o eth1 -m state --state RELATED,ESTABLISHED -j ACCEPT iptables -A forward-kura-ipf -p tcp -s 10 .11.5.21/32 -d 172 .16.0.5/32 -i eth1 -o eth0 -m tcp -j ACCEPT Additionally, a route to the 172.16.0.0/24 network needs to be configured on a connecting laptop as shown below: sudo route add -net 172 .16.0.0 netmask 255 .255.255.0 gw 10 .11.5.4 Since masquerading is enabled, there is no need to specify the back route on the destination host. Note that with this setup, the gateway only forwards packets originating on the 10.11.5.21 laptop to the 172.16.0.5 destination. If the Source Network/Host and Destination Network/Host fields are empty, iptables rules appear as follows: iptables -t nat -A postrouting-kura-ipf -p tcp -s 0 .0.0.0/0 -d 0 .0.0.0/0 -o eth0 -j MASQUERADE iptables -A forward-kura-ipf -p tcp -s 0 .0.0.0/0 -i eth0 -o eth1 -m state --state RELATED,ESTABLISHED -j ACCEPT iptables -A forward-kura-ipf -p tcp -s 0 .0.0.0/0 -d 0 .0.0.0/0 -i eth1 -o eth0 -j ACCEPT The gateway forwards packets from any external host (connected to eth1) to any destination on the local network (eth0 interface).","title":"Firewall Configuration"},{"location":"gateway-configuration/firewall-configuration/#firewall-configuration","text":"Kura offers easy management of the Linux firewall iptables and ip6tables included in an IoT Gateway. Additionally, Kura provides the ability to manage network access security to an IoT Gateway for both IPv4 and IPv6 through the following: Open Ports (local service rules) Port Forwarding IP Forwarding and Masquerading (NAT service rules) 'Automatic' NAT service rules Open Ports, Port Forwarding, and IP Forwarding and Masquerading are configured via respective Firewall configuration tabs. 'Automatic' NAT is enabled for each local (LAN) interface using the DHCP & NAT tab of the respective interface configuration. While the IPv4 Firewall configuration capability is present on all IoT Gateways, the IPv6 Firewall is present only on devices that support IPv6 Networking.","title":"Firewall Configuration"},{"location":"gateway-configuration/firewall-configuration/#firewall-linux-configuration","text":"This section describes the changes applied by Kura at the Linux networking configuration. Please read the following note before proceeding with manual changes of the Linux networking configuration. Warning It is NOT recommended performing manual editing of the Linux networking configuration files when the gateway configuration is being managed through Kura. While Linux may correctly accept manual changes, Kura may not be able to interpret the new configuration resulting in an inconsistent state. When a new firewall configuration is submitted, Kura immediately applies it using the iptables service provided by the OS. Moreover, the rules are stored in the filesystem and a new Kura snapshot is generated containing the new configuration. At the next startup, the firewall service in the OS will re-apply them and Kura will check the firewall configuration against the one contained in the last snapshot. In this way, the user can update the snapshot with the needed rules and apply them to the system using the webUI or modify the snapshot_0.xml before the first start of Kura. In order to allow a better coexistence between Kura and external applications that need to modify firewall rules, Kura writes its rules to a set of custom iptables chains. They are input-kura , output-kura , forward-kura , forward-kura-pf and forward-kura-ipf for the filter table and input-kura , output-kura , prerouting-kura , prerouting-kura-pf , postrouting-kura , postrouting-kura-pf and postrouting-kura-ipf for the nat table. The custom chains are then put in their respective standard iptables chains, as shown in the following: iptables -t filter -I INPUT -j input-kura iptables -t filter -I OUTPUT -j output-kura iptables -t filter -I FORWARD -j forward-kura iptables -t filter -I forward-kura -j forward-kura-pf iptables -t filter -I forward-kura -j forward-kura-ipf iptables -t nat -I PREROUTING -j prerouting-kura iptables -t nat -I prerouting-kura -j prerouting-kura-pf iptables -t nat -I INPUT -j input-kura iptables -t nat -I OUTPUT -j output-kura iptables -t nat -I POSTROUTING -j postrouting-kura iptables -t nat -I postrouting-kura -j postrouting-kura-pf iptables -t nat -I postrouting-kura -j postrouting-kura-ipf The same custom chains are used in the IPv6 case. Even if many firewall rules can be handled by Kura, it could be that some rules cannot be filled through the Web Console. In this case, custom firewall rules may be added to the /etc/init.d/firewall_cust script manually. These rules are applied/reapplied every time the firewall service starts, that is at the gateway startup. These custom rules should not be applied to the Kura custom chains, but to the standard ones.","title":"Firewall Linux Configuration"},{"location":"gateway-configuration/firewall-configuration/#open-ports","text":"If Kura is running on a gateway, all TCP/UDP ports are closed by default unless they are listed in the Open Ports IPv4 or Open Ports IPv6 tab of the Firewall section in the Gateway Administration Console, or in the /etc/sysconfig/iptables script. Therefore, if a user needs to connect to a specific port on a gateway, it is insufficient to have an application listening on the desired port; the port also needs to be opened in the firewall. To open a port using the Gateway Administration Console, select the Firewall option located in the System area. The Firewall configuration display appears in the main window. With the Open Ports IPv4 or Open Ports IPV6 tab selected, click the New button. The New Open Port Entry form appears. The New Open Port Entry form contains the following configuration parameters: Port : specifies the port to be opened. (Required field.) Protocol : defines the protocol (tcp or udp). (Required field.) Permitted Network : only allows packets originated by a host on this network. Permitted Interface Name : only allows packets arrived on this interface. Unpermitted Interface Name : blocks packets arrived on this interface. Permitted MAC Address : only allows packets originated by this host. Source Port Range : only allows packets with source port in the defined range. Complete the New Open Port Entry form and click the Submit button when finished. Once the form is submitted, a new port entry will appear. Click the Apply button for the change to take effect. The firewall rules related to the open ports section are stored in the input-kura custom chain of the IPv4/IPv6 filter table.","title":"Open Ports"},{"location":"gateway-configuration/firewall-configuration/#port-forwarding","text":"Port forwarding rules are needed to establish connectivity from the WAN side to a specific port on a host that resides on a LAN behind the gateway. In this case, a routing solution may be avoided since the connection is made to a specified external port on a gateway, and packets are forwarded to an internal port on the destination host; therefore, it is not necessary to add the external port to the list of open ports. To add a port forwarding rule, select the Port Forwarding IPv4 or Port Forwarding IPv6 tab on the Firewall display and click the New button. The Port Forward Entry form appears. The Port Forward Entry form contains the following configuration parameters: Input Interface : specifies the interface through which a packet is going to be received. (Required field). Output Interface : specifies the interface through which a packet is going to be forwarded to its destination. (Required field). LAN Address : supplies the IP address of destination host. (Required field). Protocol : defines the protocol (tcp or udp). (Required field). External Port : provides the external destination port on gateway unit. (Required field). Internal Port : provides the port on a destination host. (Required field). Enable Masquerading : defines whether masquerading is used (yes or no). If enabled, the gateway replaces the IP address of the originating host with the IP address of its own output (LAN) interface. This is needed when the destination host does not have a back route to the originating host (or default gateway route) via the gateway unit. The masquerading option is provided with port forwarding to limit gateway forwarding only to the destination port. (Required field). Permitted Network : only forwards if the packet is originated from a host on this network. Permitted MAC Address : only forwards if the packet is originated by this host. Source Port Range : only forwards if the packet's source port is within the defined range. Complete the Port Forward Entry form and click the Apply button for the desired port forwarding rules to take effect. The firewall rules related to the port forwarding section are stored in the forward-kura-pf custom chain of the IPv4/IPv6 filter table and in the postrouting-kura-pf and prerouting-kura-pf chains of the IPv4/IPv6 nat table.","title":"Port Forwarding"},{"location":"gateway-configuration/firewall-configuration/#port-forwarding-example","text":"This section describes an example of port forwarding rules applied to the IPv4 case. The initial setup is described below. A couple of RaspberryPi that shares the same LAN over Ethernet. The first RaspberryPi running Kura is configured as follows: The eth0 interface static with IP address of 172.16.0.5. There is no default gateway. The second RaspberryPi running Kura is configured as follows: The eth0 interface LAN/static with IP address of 172.16.0.1/24 and no NAT. The wlan0 interface is WAN/DHCP client. A laptop is connected to the same network of the wlan0 of the second RaspberryPi and can ping its wlan0 interface. The purpose of the second RaspberryPi configuration is to enable access to the Administration Console running on the first one (port 80) by connecting to the second RaspberryPi's port 8080 over the wlan. This scenario assumes that IP addresses are assigned as follows: Second RaspberryPi wlan0 - 10.200.12.6 Laptop wlan0 - 10.200.12.10 The following port forwarding entries are added to the second RaspberryPi configuration as described above using the Port Forward Entry form: Input Interface - wlan0 Output Interface - eth0 LAN Address - 172.16.0.5 Protocol - tcp External Port - 8080 Internal Port - 80 Masquerade - yes The Permitted Network , Permitted MAC Address , and Source Port Range fields are left blank. The following iptables rules are applied and added to the /etc/sysconfig/iptables file: iptables -t nat -A prerouting-kura-pf -i wlan0 -p tcp -s 0 .0.0.0/0 --dport 8080 -j DNAT --to 172 .16.0.5:80 iptables -t nat -A postrouting-kura-pf -o eth0 -p tcp -d 172 .16.0.5 -j MASQUERADE iptables -A forward-kura-pf -i wlan0 -o eth0 -p tcp -s 0 .0.0.0/0 --dport 80 -d 172 .16.0.5 -j ACCEPT iptables -A forward-kura-pf -i eth0 -o wlan0 -p tcp -s 172 .16.0.5 -m state --state RELATED,ESTABLISHED -j ACCEPT The following iptables commands may be used to verify that the new rules have been applied: sudo iptables -v -n -L sudo iptables -v -n -L -t nat At this point, it is possible to try to connect to http://10.200.12.6 and to http://10.200.12.6:8080 from the laptop. Note that when a connection is made to the device on port 80, it is to the Kura configuration page on the device itself (the second RaspberryPi). When the gateway is connected on port 8080, you are forwarded to the Kura Gateway Administration Console on the first RaspberryPi. The destination host can only be reached by connecting to the gateway on port 8080. Another way to connect to the Kura Gateway Administration Console on the first RaspberryPi would be to add an IP Forwarding/Masquerading entry as described in the next section.","title":"Port Forwarding example"},{"location":"gateway-configuration/firewall-configuration/#ip-forwardingmasquerading","text":"The advantage of the Automatic NAT method is its simplicity. However, this approach does not handle reverse NATing, and it cannot be used for interfaces that are not listed in the Gateway Administration Console (such as VPN tun0 interface). To set up generic (one-to-many) NATing, select the IP Forwarding/Masquerading IPv4 or IP Forwarding/Masquerading IPv6 tab on the Firewall display. Press the New button and the IP Forwarding/Masquerading form appears. The IP Forwarding/Masquerading form contains the following configuration parameters: Input Interface : specifies the interface through which a packet is going to be received. (Required field). Output Interface : specifies the interface through which a packet is going to be forwarded to its destination. (Required field). Protocol : defines the protocol of the rule to check (all, tcp, or udp). (Required field). Source Network/Host : identifies the source network or host name (CIDR notation). Set to IPv4 0.0.0.0/0 or IPv6 ::/0 if empty. Destination Network/Host : identifies the destination network or host name (CIDR notation). Set to IPv4 0.0.0.0/0 or IPv6 ::/0 if empty. Enable Masquerading : defines whether masquerading is used (yes or no). If set to 'yes', masquerading is enabled. If set to 'no', only FORWARDING rules are be added. (Required field). The rules will be added to the forward-kura-ipf chain in the IPv4/IPv6 filter table and in the postrouting-kura-ipf one in the IPv4/IPv6 nat table. As a use-case scenario, consider the same setup as in port forwarding, but with cellular interface disabled and eth1 interface configured as WAN/DHCP client. In this case, the interfaces of the gateway are configured as follows: eth0 : LAN/Static/No NAT 172.16.0.1/24 eth1 : WAN/DHCP 10.11.5.4/24 To reach the gateway sitting on the 172.16.0.5/24 from a specific host on the 10.11.0.0/16 network, set up the following Reverse NAT entry: Input Interface: eth1 (WAN interface) Output Interface: eth0 (LAN interface) Protocol: all Source Network/Host: 10.11.5.21/32 Destination Network/Host: 172.16.0.5/32 Enable Masquerading: yes This case applies the following iptables rules: iptables -t nat -A postrouting-kura-ipf -p tcp -s 10 .11.5.21/32 -d 172 .16.0.5/32 -o eth0 -j MASQUERADE iptables -A forward-kura-ipf -p tcp -s 172 .16.0.5/32 -i eth0 -o eth1 -m state --state RELATED,ESTABLISHED -j ACCEPT iptables -A forward-kura-ipf -p tcp -s 10 .11.5.21/32 -d 172 .16.0.5/32 -i eth1 -o eth0 -m tcp -j ACCEPT Additionally, a route to the 172.16.0.0/24 network needs to be configured on a connecting laptop as shown below: sudo route add -net 172 .16.0.0 netmask 255 .255.255.0 gw 10 .11.5.4 Since masquerading is enabled, there is no need to specify the back route on the destination host. Note that with this setup, the gateway only forwards packets originating on the 10.11.5.21 laptop to the 172.16.0.5 destination. If the Source Network/Host and Destination Network/Host fields are empty, iptables rules appear as follows: iptables -t nat -A postrouting-kura-ipf -p tcp -s 0 .0.0.0/0 -d 0 .0.0.0/0 -o eth0 -j MASQUERADE iptables -A forward-kura-ipf -p tcp -s 0 .0.0.0/0 -i eth0 -o eth1 -m state --state RELATED,ESTABLISHED -j ACCEPT iptables -A forward-kura-ipf -p tcp -s 0 .0.0.0/0 -d 0 .0.0.0/0 -i eth1 -o eth0 -j ACCEPT The gateway forwards packets from any external host (connected to eth1) to any destination on the local network (eth0 interface).","title":"IP Forwarding/Masquerading"},{"location":"gateway-configuration/gateway-administration-console-authentication/","text":"Gateway Administration Console Authentication The Gateway Administration Console supports multiple login identities with associated permissions and HTTPS client side authentication with certificates. The identity and permission configuration and credentials is stored externally the UserAdmin service (see Authentication and Authorization for more details). Permissions The Gateway Administration Console defines the following permissions, that allow to restrict the operations that an identity is allowed to perform: kura.cloud.connection.admin : Allows to manage cloud connections using Cloud Connections tab. kura.packages.admin : Allows to install deployment packages using the Packages tab. kura.device : Allows to interact with the Device and Status tabs. kura.network.admin : Allows to manage network connectivity and firewall configuration using the Network and Firewall tabs. kura.wires.admin : Allows to manage Wire Graph and Driver and Asset configurations using the Wires and Drivers and Assets tabs. kura.admin : This permission implies all other permissions, including the ones defined by external applications. Default identities Kura provides the following identities by default: Name Password Permissions admin admin kura.admin appadmin appadmin kura.cloud.connection.admin, kura.packages.admin, kura.wires.admin netadmin netadmin kura.cloud.connection.admin, kura.device, kura.network.admin It is possible to modify/remove the default identity configuration. Login The login screen can be accessed by entering the https://${device.ip} URL in a browser window, where ${device.ip} is the IP address. Replace https with http if HTTPS support has been disabled on the gateway. Identity name and password In order to login with identity name and password, select Password as authentication method and enter the credentials. Note Password authentication method might not be available if it has been disabled by the administrator using the Security -> Web Console section. Forced password change on login Kura supports forcing an identity to change the password at login, before accessing the Administration Console. This functionality is enabled by default after a fresh installation. At login the following prompt will appear forcing the user to define a new password. This functionality can be configured by an admin identity using the Identities section of the Administration Console. The forced password change can also be disabled by editing the snapshot_0.xml file removing the kura.need.password.change property for the desired identity in the org.eclipse.kura.internal.useradmin.store.RoleRepositoryStoreImpl configuration before Kura first boot. If this functionality is enabled, REST API username and password authentication is will be disabled for the specific identity until the password is updated, REST API certificate authentication will still work. Certificate authentication In order to perform HTTPS certificate authentication, select the Certificate authentication method and click Login , the browser may prompt to select the certificate to use. Note Certificate authentication method might not be available if no HTTPS with client authentication ports have been configured or if it has been explicitly disabled by the administrator using the Security -> Web Console section. Identity and Permission management The Gateway Administration Console allows the management of identity and permission configuration in a dedicated view, accessible by navigating to the Identities section: The section above allows to: Create new identities New identities can be created by clicking the New Identity button. Remove existing identities Existing identities can be removed by selecting the corresponding entry in the list and pressing the Delete Identity button. Manage password authentication Password authentication can be enabled or disabled by changing the Password authentication enabled parameter. Changing this parameter will not modify the existing stored password. Enabling password authentication for a new identity requires to define a new password. The password can be set/modified by clicking the Change password button. Assign or remove permissions Permissions can be assigned or removed by ticking the corresponding entries in the Permissions table. No changes will be applied to the gateway until the Apply button is pressed. Certificate based authentication The Gateway Administration Console supports HTTPS certificate based client side authentication. The authentication process works as follows: One or more Https client certificate must be added to keystore, this can be done using the Certificate Management section. The user must provide a certificate or certificate chain signed by one of the CAs added as Https client certificate . The common name field of the leaf certificate provided by the user must be the name of the identity that should be used for the session. HTTPS with certificate based authentication must be enabled in the HTTP/HTTPS Configuration section. Log in with certificate can be performed by selecting the Certificate authentication method in Gateway Administration Console login screen or by connecting directly to the HTTPS port with client side authentication specified in gateway configuration.","title":"Gateway Administration Console Authentication"},{"location":"gateway-configuration/gateway-administration-console-authentication/#gateway-administration-console-authentication","text":"The Gateway Administration Console supports multiple login identities with associated permissions and HTTPS client side authentication with certificates. The identity and permission configuration and credentials is stored externally the UserAdmin service (see Authentication and Authorization for more details).","title":"Gateway Administration Console Authentication"},{"location":"gateway-configuration/gateway-administration-console-authentication/#permissions","text":"The Gateway Administration Console defines the following permissions, that allow to restrict the operations that an identity is allowed to perform: kura.cloud.connection.admin : Allows to manage cloud connections using Cloud Connections tab. kura.packages.admin : Allows to install deployment packages using the Packages tab. kura.device : Allows to interact with the Device and Status tabs. kura.network.admin : Allows to manage network connectivity and firewall configuration using the Network and Firewall tabs. kura.wires.admin : Allows to manage Wire Graph and Driver and Asset configurations using the Wires and Drivers and Assets tabs. kura.admin : This permission implies all other permissions, including the ones defined by external applications.","title":"Permissions"},{"location":"gateway-configuration/gateway-administration-console-authentication/#default-identities","text":"Kura provides the following identities by default: Name Password Permissions admin admin kura.admin appadmin appadmin kura.cloud.connection.admin, kura.packages.admin, kura.wires.admin netadmin netadmin kura.cloud.connection.admin, kura.device, kura.network.admin It is possible to modify/remove the default identity configuration.","title":"Default identities"},{"location":"gateway-configuration/gateway-administration-console-authentication/#login","text":"The login screen can be accessed by entering the https://${device.ip} URL in a browser window, where ${device.ip} is the IP address. Replace https with http if HTTPS support has been disabled on the gateway.","title":"Login"},{"location":"gateway-configuration/gateway-administration-console-authentication/#identity-name-and-password","text":"In order to login with identity name and password, select Password as authentication method and enter the credentials. Note Password authentication method might not be available if it has been disabled by the administrator using the Security -> Web Console section.","title":"Identity name and password"},{"location":"gateway-configuration/gateway-administration-console-authentication/#forced-password-change-on-login","text":"Kura supports forcing an identity to change the password at login, before accessing the Administration Console. This functionality is enabled by default after a fresh installation. At login the following prompt will appear forcing the user to define a new password. This functionality can be configured by an admin identity using the Identities section of the Administration Console. The forced password change can also be disabled by editing the snapshot_0.xml file removing the kura.need.password.change property for the desired identity in the org.eclipse.kura.internal.useradmin.store.RoleRepositoryStoreImpl configuration before Kura first boot. If this functionality is enabled, REST API username and password authentication is will be disabled for the specific identity until the password is updated, REST API certificate authentication will still work.","title":"Forced password change on login"},{"location":"gateway-configuration/gateway-administration-console-authentication/#certificate-authentication","text":"In order to perform HTTPS certificate authentication, select the Certificate authentication method and click Login , the browser may prompt to select the certificate to use. Note Certificate authentication method might not be available if no HTTPS with client authentication ports have been configured or if it has been explicitly disabled by the administrator using the Security -> Web Console section.","title":"Certificate authentication"},{"location":"gateway-configuration/gateway-administration-console-authentication/#identity-and-permission-management","text":"The Gateway Administration Console allows the management of identity and permission configuration in a dedicated view, accessible by navigating to the Identities section: The section above allows to:","title":"Identity and Permission management"},{"location":"gateway-configuration/gateway-administration-console-authentication/#create-new-identities","text":"New identities can be created by clicking the New Identity button.","title":"Create new identities"},{"location":"gateway-configuration/gateway-administration-console-authentication/#remove-existing-identities","text":"Existing identities can be removed by selecting the corresponding entry in the list and pressing the Delete Identity button.","title":"Remove existing identities"},{"location":"gateway-configuration/gateway-administration-console-authentication/#manage-password-authentication","text":"Password authentication can be enabled or disabled by changing the Password authentication enabled parameter. Changing this parameter will not modify the existing stored password. Enabling password authentication for a new identity requires to define a new password. The password can be set/modified by clicking the Change password button.","title":"Manage password authentication"},{"location":"gateway-configuration/gateway-administration-console-authentication/#assign-or-remove-permissions","text":"Permissions can be assigned or removed by ticking the corresponding entries in the Permissions table. No changes will be applied to the gateway until the Apply button is pressed.","title":"Assign or remove permissions"},{"location":"gateway-configuration/gateway-administration-console-authentication/#certificate-based-authentication","text":"The Gateway Administration Console supports HTTPS certificate based client side authentication. The authentication process works as follows: One or more Https client certificate must be added to keystore, this can be done using the Certificate Management section. The user must provide a certificate or certificate chain signed by one of the CAs added as Https client certificate . The common name field of the leaf certificate provided by the user must be the name of the identity that should be used for the session. HTTPS with certificate based authentication must be enabled in the HTTP/HTTPS Configuration section. Log in with certificate can be performed by selecting the Certificate authentication method in Gateway Administration Console login screen or by connecting directly to the HTTPS port with client side authentication specified in gateway configuration.","title":"Certificate based authentication"},{"location":"gateway-configuration/gateway-administration-console/","text":"Gateway Administration Console Accessing the Kura Gateway Administration Console Kura provides a web-based, user interface for the administration and management of your IoT gateway. The Kura Gateway Administration Console enables you to monitor the gateway status, manage the network configuration, and manage the installed application and services. Access to the Kura Gateway Administration Console requires that a unit running Eclipse Kura is reachable via its Ethernet primary interface. Connections on HTTP port 443 for these interfaces are allowed by default through the built-in firewall. The Kura Gateway Administration Console can be accessed by typing the IP address of the gateway into the browser's URL bar. Once the URL is submitted, the user is required to log in and is then redirected to the Administration Console (e.g., https://192.168.2.8/admin/console ) shown in the screen capture below. The default login name and password is admin/admin . Warning It is recommended to change the default password after initial setup and before deployment, as well as limiting access to the Administration Console to a trusted local network interface using appropriate firewall rules. Password change Once logged in, the user can modify its password (recommended after the first login). To access the option, click on the button near the username in the header section. A dropdown menu appears with the logout and the password modification options. When clicking on \"Change password\", the following dialog will appear: After confirming the changes, the user will be logged out. Accessing the Kura Gateway Administration Console over a Cellular Link In order to connect to the Gateway Administration Console via a cellular interface, the following requirements must be met: The service plan must allow for a static, public IP address to be assigned to the cellular interface. The used ports must not be blocked by the provider. The user must add Open Port entries for the cellular interface. This may be done either through the Firewall tab. If some of the used ports are blocked by the service provider, there is an option to reconfigure the gateway to use another port (i.e., 8080). In order to do so, the following requirements must be met: The HttpService configuration must be changed to use the new ports. The new ports must be open in the firewall for all network interfaces. HTTPS related warnings Most browsers will probably warn the user that the connection is not secure when Gateway Administration Console is accessed using HTTPS. In order to remove the warning, the browser must be able to verify the identity of the gateway as an HTTPS server. The verification process will fail with default server certificate provided by Kura because it is self-signed and it is not suitable for hostname verification. Fixing this might require to configure the browser to trust the certificate provided by the gateway and/or using a server certificate signed by a CA trusted by the browser and assigning a DNS name to the gateway in order to pass hostname verification. System Use Notification Banner For security reasons, it may be needed to display to the user a banner that describes the intended system use before authenticating. The system use notification message is customisable by authorised personnel in the Security section of the ESF Wen UI, in the Web Console tab.","title":"Gateway Administration Console"},{"location":"gateway-configuration/gateway-administration-console/#gateway-administration-console","text":"","title":"Gateway Administration Console"},{"location":"gateway-configuration/gateway-administration-console/#accessing-the-kura-gateway-administration-console","text":"Kura provides a web-based, user interface for the administration and management of your IoT gateway. The Kura Gateway Administration Console enables you to monitor the gateway status, manage the network configuration, and manage the installed application and services. Access to the Kura Gateway Administration Console requires that a unit running Eclipse Kura is reachable via its Ethernet primary interface. Connections on HTTP port 443 for these interfaces are allowed by default through the built-in firewall. The Kura Gateway Administration Console can be accessed by typing the IP address of the gateway into the browser's URL bar. Once the URL is submitted, the user is required to log in and is then redirected to the Administration Console (e.g., https://192.168.2.8/admin/console ) shown in the screen capture below. The default login name and password is admin/admin . Warning It is recommended to change the default password after initial setup and before deployment, as well as limiting access to the Administration Console to a trusted local network interface using appropriate firewall rules.","title":"Accessing the Kura Gateway Administration Console"},{"location":"gateway-configuration/gateway-administration-console/#password-change","text":"Once logged in, the user can modify its password (recommended after the first login). To access the option, click on the button near the username in the header section. A dropdown menu appears with the logout and the password modification options. When clicking on \"Change password\", the following dialog will appear: After confirming the changes, the user will be logged out.","title":"Password change"},{"location":"gateway-configuration/gateway-administration-console/#accessing-the-kura-gateway-administration-console-over-a-cellular-link","text":"In order to connect to the Gateway Administration Console via a cellular interface, the following requirements must be met: The service plan must allow for a static, public IP address to be assigned to the cellular interface. The used ports must not be blocked by the provider. The user must add Open Port entries for the cellular interface. This may be done either through the Firewall tab. If some of the used ports are blocked by the service provider, there is an option to reconfigure the gateway to use another port (i.e., 8080). In order to do so, the following requirements must be met: The HttpService configuration must be changed to use the new ports. The new ports must be open in the firewall for all network interfaces.","title":"Accessing the Kura Gateway Administration Console over a Cellular Link"},{"location":"gateway-configuration/gateway-administration-console/#https-related-warnings","text":"Most browsers will probably warn the user that the connection is not secure when Gateway Administration Console is accessed using HTTPS. In order to remove the warning, the browser must be able to verify the identity of the gateway as an HTTPS server. The verification process will fail with default server certificate provided by Kura because it is self-signed and it is not suitable for hostname verification. Fixing this might require to configure the browser to trust the certificate provided by the gateway and/or using a server certificate signed by a CA trusted by the browser and assigning a DNS name to the gateway in order to pass hostname verification.","title":"HTTPS related warnings"},{"location":"gateway-configuration/gateway-administration-console/#system-use-notification-banner","text":"For security reasons, it may be needed to display to the user a banner that describes the intended system use before authenticating. The system use notification message is customisable by authorised personnel in the Security section of the ESF Wen UI, in the Web Console tab.","title":"System Use Notification Banner"},{"location":"gateway-configuration/gateway-status/","text":"Gateway Status The status of the gateway may be viewed from the Status window, which is accessed by selecting the Status option located in the System area. The Status window provides a summary of the key information regarding the status of the gateway including its IoT Cloud connection and network configuration. The values reported in the page can be reloaded using the Refresh button. This will read the current values from the system and update the page. Since the update procedure can take time, the update can be performed at most every 30 seconds. Cloud Services This section provides a summary of the IoT Cloud connection status including the following details: Account - defines the name of the account used by the MqttDataTransport service when an MQTT connection is opened. Broker URL - defines the URL of the MQTT broker. Client ID - specifies the client identifier used by the MqttDataTransport service when an MQTT connection is opened. Service Status - provides the status of the DataService and DataTransport connection. Valid values are CONNECTED or DISCONNECTED. Username - supplies the name of the user used by the MqttDataTransport service when an MQTT connection is opened. Ethernet, Wireless, and Cellular Settings This section provides information about the currently configured network interfaces. Position Status This section provides the GPS status and latest known position (if applicable) including the following details: Longitude - longitude as reported by the PositionService in radians. Latitude - latitude as reported by the PositionService in radians. Altitude - altitude as reported by the PositionService in meters. Warning The status reported in the page may not be synchronized with the real state of the system. In this case, use the Refresh button to updated the values in the page.","title":"Gateway Status"},{"location":"gateway-configuration/gateway-status/#gateway-status","text":"The status of the gateway may be viewed from the Status window, which is accessed by selecting the Status option located in the System area. The Status window provides a summary of the key information regarding the status of the gateway including its IoT Cloud connection and network configuration. The values reported in the page can be reloaded using the Refresh button. This will read the current values from the system and update the page. Since the update procedure can take time, the update can be performed at most every 30 seconds.","title":"Gateway Status"},{"location":"gateway-configuration/gateway-status/#cloud-services","text":"This section provides a summary of the IoT Cloud connection status including the following details: Account - defines the name of the account used by the MqttDataTransport service when an MQTT connection is opened. Broker URL - defines the URL of the MQTT broker. Client ID - specifies the client identifier used by the MqttDataTransport service when an MQTT connection is opened. Service Status - provides the status of the DataService and DataTransport connection. Valid values are CONNECTED or DISCONNECTED. Username - supplies the name of the user used by the MqttDataTransport service when an MQTT connection is opened.","title":"Cloud Services"},{"location":"gateway-configuration/gateway-status/#ethernet-wireless-and-cellular-settings","text":"This section provides information about the currently configured network interfaces.","title":"Ethernet, Wireless, and Cellular Settings"},{"location":"gateway-configuration/gateway-status/#position-status","text":"This section provides the GPS status and latest known position (if applicable) including the following details: Longitude - longitude as reported by the PositionService in radians. Latitude - latitude as reported by the PositionService in radians. Altitude - altitude as reported by the PositionService in meters. Warning The status reported in the page may not be synchronized with the real state of the system. In this case, use the Refresh button to updated the values in the page.","title":"Position Status"},{"location":"gateway-configuration/keys-and-certificates/","text":"Keys and Certificates The framework manages directly different key pairs and trusted certificates from different keystores. To simplify the management of such complex objects, the framework provides a dedicated section of its Administrative Web UI, a set of REST APIs for local management and a request handler (KEYS-V1 and KEYS-V2) for cloud remote interaction. Web UI The Certificates List tab in the Security section of the Kura Web UI provides a simple way for the user to get the list of all the managed keys and certificates of the framework: The page allows the user to add a new Keypair or trusted certificate or to delete an existing element. Every key pair or trusted certificate is listed by its alias, identified by the corresponding type and further identified by the keystore that is managing that element. If the user needs to add a new entry to one of the managed KeystoreService instances, can click on the Add button on the top left part of the page. The user will be guided through a process that will allow to identify the type of entry to add: It can be either a: Private/Public Key Pair Trusted Certificate If the user decides to add a key pair, then the wizard will provide a page like the following: Here the user can specify: - Key Store : the KeystoreService instance that will store and maintain the key pair - Storage Alias : the alias that will be used to identify the key pair - Private Key : the private key part of the key pair - Certificate : the public key part of the key pair After clicking on the Apply button, the new entry will be stored in the selected Keystore and listed along the other entries managed by the framework. The following cryptographic algorithms are supported for Key Pairs : - RSA - DSA Instead, if the user wants to load a Trusted Certificate, the Ui will change as follows: Here the user can specify: - Key Store : the KeystoreService instance that will store and maintain the trusted certificate - Storage Alias : the alias that will be used to identify the trusted certificate - Certificate : the trusted certificate The following cryptographic algorithms are supported for Trusted Certificates : - RSA - DSA - EC REST APIs keystores/v1 The org.eclipse.kura.core.keystore bundle exposes a REST endpoint under the /services/keystores/v1 path. The Kura REST APIs for Keys and Certificates support the following calls and are allowed to any user with rest.keystores permission. Method Path Roles allowed Encoding Request parameters Description GET / keystores JSON None Returns the list of all the KeystoreService instances. GET /entries keystores JSON None Returns the list of all the entries managed by the KeystoreService instances. GET /entries?keystoreServicePid={keystoreServicePid} keystores JSON keystoreServicePid Returns the list of all the entries managed by the specified KeystoreService instance. GET /entries?alias={alias} keystores JSON alias Returns the list of all the entries specified by the defined alias and managed in all the available KeystoreService instances in the framework. GET /entries/entry?keystoreServicePid={keystoreServicePid}&alias={alias} keystores JSON keystoreServicePid and alias Returns the entry identified by the specified keystoreServicePid and alias. POST /entries/csr keystores JSON The reference to the key pair in a specified KeystoreService instance that will be used to generate the CSR. The request has to be associated with additional parameters that identify the algorithm used to compute and sign the CSR and the DN or the corresponding public key that needs to be countersigned. Generates a CSR for the specified key pair in the specified KeystoreService instance, based on the parameters provided in the request. POST /entries/certificate keystores JSON The reference to the KeystoreService instance and the alias that will be used for storage. A type filed identifies the type of key that needs to be managed. This request allows the user to upload a TrustedCertificate. POST /entries/keypair keystores JSON To generate a new KeyPair directly in the device, the request format need to follow the references in the following paragraphs. This request allows the user to generate a new KeyPair into the device. DELETE /entries keystores JSON A JSON identifying the resource to delete. The format of the request is described in in one of the following sections. Deletes the entry in the specified KeystoreService instance. List All the KeystoreServices Request : URL - https:///services/keystores/v1 Response : [ { \"keystoreServicePid\" : \"org.eclipse.kura.core.keystore.SSLKeystore\" , \"type\" : \"jks\" , \"size\" : 4 }, { \"keystoreServicePid\" : \"org.eclipse.kura.crypto.CryptoService\" , \"type\" : \"jks\" , \"size\" : 3 }, { \"keystoreServicePid\" : \"org.eclipse.kura.core.keystore.HttpsKeystore\" , \"type\" : \"jks\" , \"size\" : 1 }, { \"keystoreServicePid\" : \"org.eclipse.kura.core.keystore.DMKeystore\" , \"type\" : \"jks\" , \"size\" : 1 } ] Get all the Managed Entries Request : URL - https:///services/keystores/v1/entries Response : [ { \"subjectDN\" : \"OU=Go Daddy Class 2 Certification Authority, O=\\\"The Go Daddy Group, Inc.\\\", C=US\" , \"issuer\" : \"OU=Go Daddy Class 2 Certification Authority,O=The Go Daddy Group\\\\, Inc.,C=US\" , \"startDate\" : \"Tue, 29 Jun 2004 17:06:20 GMT\" , \"expirationDate\" : \"Thu, 29 Jun 2034 17:06:20 GMT\" , \"algorithm\" : \"SHA1withRSA\" , \"size\" : 2048 , \"keystoreServicePid\" : \"org.eclipse.kura.core.keystore.SSLKeystore\" , \"alias\" : \"ca-godaddyclass2ca\" , \"type\" : \"TRUSTED_CERTIFICATE\" }, { \"algorithm\" : \"RSA\" , \"size\" : 4096 , \"keystoreServicePid\" : \"org.eclipse.kura.core.keystore.HttpsKeystore\" , \"alias\" : \"localhost\" , \"type\" : \"PRIVATE_KEY\" } ] Get All the Entries by KeystoreService Request : URL - https:///services/keystores/v1/entries?keystoreServicePid=org.eclipse.kura.core.keystore.HttpsKeystore Response : [ { \"algorithm\" : \"RSA\" , \"size\" : 4096 , \"certificateChain\" : [ \"-----BEGIN CERTIFICATE-----\\n\\n-----END CERTIFICATE-----\" ], \"keystoreServicePid\" : \"org.eclipse.kura.core.keystore.HttpsKeystore\" , \"alias\" : \"localhost\" , \"type\" : \"PRIVATE_KEY\" } ] Get All the Entries by Alias Request : URL - https:///services/keystores/v1/entries?alias=localhost Response : [ { \"algorithm\" : \"RSA\" , \"size\" : 4096 , \"certificateChain\" : [ \"-----BEGIN CERTIFICATE-----\\n\\n-----END CERTIFICATE-----\" ], \"keystoreServicePid\" : \"org.eclipse.kura.core.keystore.HttpsKeystore\" , \"alias\" : \"localhost\" , \"type\" : \"PRIVATE_KEY\" } ] Get Specific Entry Request : URL - https:///services/keystores/v1/entries/entry?keystoreServicePid=org.eclipse.kura.core.keystore.HttpsKeystore&alias=localhost Response : { \"algorithm\" : \"RSA\" , \"size\" : 4096 , \"certificateChain\" : [ \"-----BEGIN CERTIFICATE-----\\n-----END CERTIFICATE-----\" ], \"keystoreServicePid\" : \"org.eclipse.kura.core.keystore.HttpsKeystore\" , \"alias\" : \"localhost\" , \"type\" : \"PRIVATE_KEY\" } Get the CSR for a KeyPair Request : URL - https:///services/keystores/v1/entries/csr keystoreServicePid=org.eclipse.kura.core.keystore.HttpsKeystore&alias=localhost` Request body : { \"keystoreServicePid\" : \"org.eclipse.kura.core.keystore.HttpsKeystore\" , \"alias\" : \"localhost\" , \"signatureAlgorithm\" : \"SHA256withRSA\" , \"attributes\" : \"CN=Kura, OU=IoT, O=Eclipse, C=US\" } Store Trusted Certificate Request : URL - https:///services/keystores/v1/entries/certificate Request body : { \"keystoreServicePid\" : \"MyKeystore\" , \"alias\" : \"myCertTest99\" , \"certificate\" : \"-----BEGIN CERTIFICATE----- -----END CERTIFICATE-----\" } Generate KeyPair Request : URL - https:///services/keystores/v1/entries/keypair Request body : { \"keystoreServicePid\" : \"MyKeystore\" , \"alias\" : \"keypair1\" , \"algorithm\" : \"RSA\" , \"size\" : 1024 , \"signatureAlgorithm\" : \"SHA256WithRSA\" , \"attributes\" : \"CN=Kura, OU=IoT, O=Eclipse, C=US\" } Delete Entry Request : URL - https:///services/keystores/v1/entries Request body : { \"keystoreServicePid\" : \"MyKeystore\" , \"alias\" : \"mycerttestec\" } KEYS-V1 Request Handler Mapping the previously defined REST APIs, the framework exposed to the remote cloud platforms a request handler named KEYS-V1 that allows the remote user to list and manage the keystores, the keys and the certificates in the framework. The request handler exposes also the capability to generate on the edge a CSR that can be countersigned remotely by a trusted CA. keystores/v2 Starting from Kura 5.4.0, the keystores/v2 REST API is also available, it supports all of the request endpoints of keystores/v1 plus an additional endpoint that allows to upload and modify private key entries: Method Path Roles allowed Encoding Request parameters Description POST /entries/privatekey keystores JSON To upload a new private key entry directly in the device, the request format need to follow the references in the following paragraphs. This request allows the user to upload a new private key entry into the device or to modify the certificate chain of an existing one. Uploading a Private Key Entry Request : URL - https:///services/keystores/v2/entries/privatekey Request body : The request should include the private key in unencrypted PEM format and the certificate chain in PEM format, the first certificate in the certificateChain list must use the public key associated with the private key supplied as the privateKey parameter. The device will overwrite the entry with the provided alias if it already exists. WARINING: Please use this endpoint through a secure connection. { \"keystoreServicePid\" : \"MyKeystore\" , \"alias\" : \"keypair1\" , \"privateKey\" : \"-----BEGIN RSA PRIVATE KEY-----\\n...\\n-----END RSA PRIVATE KEY-----\" , \"certificateChain\" :[ \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\" , \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\" , ] } Updating a Private Key Entry Request : URL - https:///services/keystores/v2/entries/privatekey Request body : In order to update the certificate chain associated to a specific private key entry it is possible to use the same format as previous request and omit the privateKey parameter. In this case the certificate chain of the existing entry will be replaced with the one specified in the request and the existing private key will be retained. This request can be useful for example to create a CSR on the device, sign it externally and then updating the corresponding entry with the resulting certificate. { \"keystoreServicePid\" : \"MyKeystore\" , \"alias\" : \"keypair1\" , \"certificateChain\" :[ \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\" , \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\" , ] }","title":"Keys and Certificates"},{"location":"gateway-configuration/keys-and-certificates/#keys-and-certificates","text":"The framework manages directly different key pairs and trusted certificates from different keystores. To simplify the management of such complex objects, the framework provides a dedicated section of its Administrative Web UI, a set of REST APIs for local management and a request handler (KEYS-V1 and KEYS-V2) for cloud remote interaction.","title":"Keys and Certificates"},{"location":"gateway-configuration/keys-and-certificates/#web-ui","text":"The Certificates List tab in the Security section of the Kura Web UI provides a simple way for the user to get the list of all the managed keys and certificates of the framework: The page allows the user to add a new Keypair or trusted certificate or to delete an existing element. Every key pair or trusted certificate is listed by its alias, identified by the corresponding type and further identified by the keystore that is managing that element. If the user needs to add a new entry to one of the managed KeystoreService instances, can click on the Add button on the top left part of the page. The user will be guided through a process that will allow to identify the type of entry to add: It can be either a: Private/Public Key Pair Trusted Certificate If the user decides to add a key pair, then the wizard will provide a page like the following: Here the user can specify: - Key Store : the KeystoreService instance that will store and maintain the key pair - Storage Alias : the alias that will be used to identify the key pair - Private Key : the private key part of the key pair - Certificate : the public key part of the key pair After clicking on the Apply button, the new entry will be stored in the selected Keystore and listed along the other entries managed by the framework. The following cryptographic algorithms are supported for Key Pairs : - RSA - DSA Instead, if the user wants to load a Trusted Certificate, the Ui will change as follows: Here the user can specify: - Key Store : the KeystoreService instance that will store and maintain the trusted certificate - Storage Alias : the alias that will be used to identify the trusted certificate - Certificate : the trusted certificate The following cryptographic algorithms are supported for Trusted Certificates : - RSA - DSA - EC","title":"Web UI"},{"location":"gateway-configuration/keys-and-certificates/#rest-apis","text":"","title":"REST APIs"},{"location":"gateway-configuration/keys-and-certificates/#keystoresv1","text":"The org.eclipse.kura.core.keystore bundle exposes a REST endpoint under the /services/keystores/v1 path. The Kura REST APIs for Keys and Certificates support the following calls and are allowed to any user with rest.keystores permission. Method Path Roles allowed Encoding Request parameters Description GET / keystores JSON None Returns the list of all the KeystoreService instances. GET /entries keystores JSON None Returns the list of all the entries managed by the KeystoreService instances. GET /entries?keystoreServicePid={keystoreServicePid} keystores JSON keystoreServicePid Returns the list of all the entries managed by the specified KeystoreService instance. GET /entries?alias={alias} keystores JSON alias Returns the list of all the entries specified by the defined alias and managed in all the available KeystoreService instances in the framework. GET /entries/entry?keystoreServicePid={keystoreServicePid}&alias={alias} keystores JSON keystoreServicePid and alias Returns the entry identified by the specified keystoreServicePid and alias. POST /entries/csr keystores JSON The reference to the key pair in a specified KeystoreService instance that will be used to generate the CSR. The request has to be associated with additional parameters that identify the algorithm used to compute and sign the CSR and the DN or the corresponding public key that needs to be countersigned. Generates a CSR for the specified key pair in the specified KeystoreService instance, based on the parameters provided in the request. POST /entries/certificate keystores JSON The reference to the KeystoreService instance and the alias that will be used for storage. A type filed identifies the type of key that needs to be managed. This request allows the user to upload a TrustedCertificate. POST /entries/keypair keystores JSON To generate a new KeyPair directly in the device, the request format need to follow the references in the following paragraphs. This request allows the user to generate a new KeyPair into the device. DELETE /entries keystores JSON A JSON identifying the resource to delete. The format of the request is described in in one of the following sections. Deletes the entry in the specified KeystoreService instance.","title":"keystores/v1"},{"location":"gateway-configuration/keys-and-certificates/#list-all-the-keystoreservices","text":"Request : URL - https:///services/keystores/v1 Response : [ { \"keystoreServicePid\" : \"org.eclipse.kura.core.keystore.SSLKeystore\" , \"type\" : \"jks\" , \"size\" : 4 }, { \"keystoreServicePid\" : \"org.eclipse.kura.crypto.CryptoService\" , \"type\" : \"jks\" , \"size\" : 3 }, { \"keystoreServicePid\" : \"org.eclipse.kura.core.keystore.HttpsKeystore\" , \"type\" : \"jks\" , \"size\" : 1 }, { \"keystoreServicePid\" : \"org.eclipse.kura.core.keystore.DMKeystore\" , \"type\" : \"jks\" , \"size\" : 1 } ]","title":"List All the KeystoreServices"},{"location":"gateway-configuration/keys-and-certificates/#get-all-the-managed-entries","text":"Request : URL - https:///services/keystores/v1/entries Response : [ { \"subjectDN\" : \"OU=Go Daddy Class 2 Certification Authority, O=\\\"The Go Daddy Group, Inc.\\\", C=US\" , \"issuer\" : \"OU=Go Daddy Class 2 Certification Authority,O=The Go Daddy Group\\\\, Inc.,C=US\" , \"startDate\" : \"Tue, 29 Jun 2004 17:06:20 GMT\" , \"expirationDate\" : \"Thu, 29 Jun 2034 17:06:20 GMT\" , \"algorithm\" : \"SHA1withRSA\" , \"size\" : 2048 , \"keystoreServicePid\" : \"org.eclipse.kura.core.keystore.SSLKeystore\" , \"alias\" : \"ca-godaddyclass2ca\" , \"type\" : \"TRUSTED_CERTIFICATE\" }, { \"algorithm\" : \"RSA\" , \"size\" : 4096 , \"keystoreServicePid\" : \"org.eclipse.kura.core.keystore.HttpsKeystore\" , \"alias\" : \"localhost\" , \"type\" : \"PRIVATE_KEY\" } ]","title":"Get all the Managed Entries"},{"location":"gateway-configuration/keys-and-certificates/#get-all-the-entries-by-keystoreservice","text":"Request : URL - https:///services/keystores/v1/entries?keystoreServicePid=org.eclipse.kura.core.keystore.HttpsKeystore Response : [ { \"algorithm\" : \"RSA\" , \"size\" : 4096 , \"certificateChain\" : [ \"-----BEGIN CERTIFICATE-----\\n\\n-----END CERTIFICATE-----\" ], \"keystoreServicePid\" : \"org.eclipse.kura.core.keystore.HttpsKeystore\" , \"alias\" : \"localhost\" , \"type\" : \"PRIVATE_KEY\" } ]","title":"Get All the Entries by KeystoreService"},{"location":"gateway-configuration/keys-and-certificates/#get-all-the-entries-by-alias","text":"Request : URL - https:///services/keystores/v1/entries?alias=localhost Response : [ { \"algorithm\" : \"RSA\" , \"size\" : 4096 , \"certificateChain\" : [ \"-----BEGIN CERTIFICATE-----\\n\\n-----END CERTIFICATE-----\" ], \"keystoreServicePid\" : \"org.eclipse.kura.core.keystore.HttpsKeystore\" , \"alias\" : \"localhost\" , \"type\" : \"PRIVATE_KEY\" } ]","title":"Get All the Entries by Alias"},{"location":"gateway-configuration/keys-and-certificates/#get-specific-entry","text":"Request : URL - https:///services/keystores/v1/entries/entry?keystoreServicePid=org.eclipse.kura.core.keystore.HttpsKeystore&alias=localhost Response : { \"algorithm\" : \"RSA\" , \"size\" : 4096 , \"certificateChain\" : [ \"-----BEGIN CERTIFICATE-----\\n-----END CERTIFICATE-----\" ], \"keystoreServicePid\" : \"org.eclipse.kura.core.keystore.HttpsKeystore\" , \"alias\" : \"localhost\" , \"type\" : \"PRIVATE_KEY\" }","title":"Get Specific Entry"},{"location":"gateway-configuration/keys-and-certificates/#get-the-csr-for-a-keypair","text":"Request : URL - https:///services/keystores/v1/entries/csr keystoreServicePid=org.eclipse.kura.core.keystore.HttpsKeystore&alias=localhost` Request body : { \"keystoreServicePid\" : \"org.eclipse.kura.core.keystore.HttpsKeystore\" , \"alias\" : \"localhost\" , \"signatureAlgorithm\" : \"SHA256withRSA\" , \"attributes\" : \"CN=Kura, OU=IoT, O=Eclipse, C=US\" }","title":"Get the CSR for a KeyPair"},{"location":"gateway-configuration/keys-and-certificates/#store-trusted-certificate","text":"Request : URL - https:///services/keystores/v1/entries/certificate Request body : { \"keystoreServicePid\" : \"MyKeystore\" , \"alias\" : \"myCertTest99\" , \"certificate\" : \"-----BEGIN CERTIFICATE----- -----END CERTIFICATE-----\" }","title":"Store Trusted Certificate"},{"location":"gateway-configuration/keys-and-certificates/#generate-keypair","text":"Request : URL - https:///services/keystores/v1/entries/keypair Request body : { \"keystoreServicePid\" : \"MyKeystore\" , \"alias\" : \"keypair1\" , \"algorithm\" : \"RSA\" , \"size\" : 1024 , \"signatureAlgorithm\" : \"SHA256WithRSA\" , \"attributes\" : \"CN=Kura, OU=IoT, O=Eclipse, C=US\" }","title":"Generate KeyPair"},{"location":"gateway-configuration/keys-and-certificates/#delete-entry","text":"Request : URL - https:///services/keystores/v1/entries Request body : { \"keystoreServicePid\" : \"MyKeystore\" , \"alias\" : \"mycerttestec\" }","title":"Delete Entry"},{"location":"gateway-configuration/keys-and-certificates/#keys-v1-request-handler","text":"Mapping the previously defined REST APIs, the framework exposed to the remote cloud platforms a request handler named KEYS-V1 that allows the remote user to list and manage the keystores, the keys and the certificates in the framework. The request handler exposes also the capability to generate on the edge a CSR that can be countersigned remotely by a trusted CA.","title":"KEYS-V1 Request Handler"},{"location":"gateway-configuration/keys-and-certificates/#keystoresv2","text":"Starting from Kura 5.4.0, the keystores/v2 REST API is also available, it supports all of the request endpoints of keystores/v1 plus an additional endpoint that allows to upload and modify private key entries: Method Path Roles allowed Encoding Request parameters Description POST /entries/privatekey keystores JSON To upload a new private key entry directly in the device, the request format need to follow the references in the following paragraphs. This request allows the user to upload a new private key entry into the device or to modify the certificate chain of an existing one.","title":"keystores/v2"},{"location":"gateway-configuration/keys-and-certificates/#uploading-a-private-key-entry","text":"Request : URL - https:///services/keystores/v2/entries/privatekey Request body : The request should include the private key in unencrypted PEM format and the certificate chain in PEM format, the first certificate in the certificateChain list must use the public key associated with the private key supplied as the privateKey parameter. The device will overwrite the entry with the provided alias if it already exists. WARINING: Please use this endpoint through a secure connection. { \"keystoreServicePid\" : \"MyKeystore\" , \"alias\" : \"keypair1\" , \"privateKey\" : \"-----BEGIN RSA PRIVATE KEY-----\\n...\\n-----END RSA PRIVATE KEY-----\" , \"certificateChain\" :[ \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\" , \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\" , ] }","title":"Uploading a Private Key Entry"},{"location":"gateway-configuration/keys-and-certificates/#updating-a-private-key-entry","text":"Request : URL - https:///services/keystores/v2/entries/privatekey Request body : In order to update the certificate chain associated to a specific private key entry it is possible to use the same format as previous request and omit the privateKey parameter. In this case the certificate chain of the existing entry will be replaced with the one specified in the request and the existing private key will be retained. This request can be useful for example to create a CSR on the device, sign it externally and then updating the corresponding entry with the resulting certificate. { \"keystoreServicePid\" : \"MyKeystore\" , \"alias\" : \"keypair1\" , \"certificateChain\" :[ \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\" , \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\" , ] }","title":"Updating a Private Key Entry"},{"location":"gateway-configuration/keystores-management/","text":"Keystores Management The framework manages different types of cryptographic keys and certificates. In order to simplify the interaction with those objects, Kura provides a KeystoreService API and a specific section in the Kura Web UI that lists all the available KeystoreService instances. From the Security section, a user with Security permissions can access the Keystore Configuration section. A list of all the framework managed keystores will be available to the user with the Service PID that will be used by other components to reference the selected keystore. Associated to the Service PID, the UI shows the Factory PID that identifies the specific KeystoreService API implementation that is providing the service to the framework. In order to modify the configuration of a specific keystore service instance, the user can select one of the available rows, obtaining the corresponding keystore service configuration. The following KeystoreService factories are available: FilesystemKeystoreServiceImpl The org.eclipse.kura.core.keystore.FilesystemKeystoreServiceImpl factory provides a KeystoreService implementation that stores the private keys and certificates as a file. The user can customise the following options: Keystore Path : identifies the path in the filesystem. If the keystore file does not exists, a new file will be created. The value cannot be empty. Keystore Password : the corresponding keystore password. Randomize Password : a boolean flag that allows the user to specify if the keystore password needs to be randomised at the next framework boot. If set true , the framework will try to access the identified keystore and randomise the password. The new password will be persisted in the framework snapshot. Once successfully randomised, the flag will be automatically set to false by the framework. PKCS11KeystoreServiceImpl The org.eclipse.kura.core.keystore.PKCS11KeystoreServiceImpl factory provides a KeystoreService implementation that allows to access a PKCS11 token through the SunPKCS11 implementation. At the moment this type of KeystoreService provides read only access to the underlying token, operations such as adding or removing entries will fail. It is possible to use the entries provided by a PKCS11KeystoreServiceImpl for SSL authentication. The available configuration options closely match the parameters provided by the SunPKCS11 implementation, see the official documentation for more details. In particular, the official documentation contains a section that explains how the PKCS11 objects are mapped to Java KeyStore entries. The only required parameter is the PKCS11 Implementation Library Path parameter. It is usually also necessary to specify the token user pin as the Pin parameter. The configuration parameters are mapped to the SunPKCS11 provider parameters in the following way: Kura Parameter SunPKCS11 Parameter Notes Slot slot Slot List Index slotListIndex Enabled Mechanisms enabledMechanisms The curly braces must be omitted Disabled Mechanisms disabledMechanisms The curly braces must be omitted. Attributes attributes The value of this field will be appended to the provider configuration.","title":"Keystores Management"},{"location":"gateway-configuration/keystores-management/#keystores-management","text":"The framework manages different types of cryptographic keys and certificates. In order to simplify the interaction with those objects, Kura provides a KeystoreService API and a specific section in the Kura Web UI that lists all the available KeystoreService instances. From the Security section, a user with Security permissions can access the Keystore Configuration section. A list of all the framework managed keystores will be available to the user with the Service PID that will be used by other components to reference the selected keystore. Associated to the Service PID, the UI shows the Factory PID that identifies the specific KeystoreService API implementation that is providing the service to the framework. In order to modify the configuration of a specific keystore service instance, the user can select one of the available rows, obtaining the corresponding keystore service configuration. The following KeystoreService factories are available:","title":"Keystores Management"},{"location":"gateway-configuration/keystores-management/#filesystemkeystoreserviceimpl","text":"The org.eclipse.kura.core.keystore.FilesystemKeystoreServiceImpl factory provides a KeystoreService implementation that stores the private keys and certificates as a file. The user can customise the following options: Keystore Path : identifies the path in the filesystem. If the keystore file does not exists, a new file will be created. The value cannot be empty. Keystore Password : the corresponding keystore password. Randomize Password : a boolean flag that allows the user to specify if the keystore password needs to be randomised at the next framework boot. If set true , the framework will try to access the identified keystore and randomise the password. The new password will be persisted in the framework snapshot. Once successfully randomised, the flag will be automatically set to false by the framework.","title":"FilesystemKeystoreServiceImpl"},{"location":"gateway-configuration/keystores-management/#pkcs11keystoreserviceimpl","text":"The org.eclipse.kura.core.keystore.PKCS11KeystoreServiceImpl factory provides a KeystoreService implementation that allows to access a PKCS11 token through the SunPKCS11 implementation. At the moment this type of KeystoreService provides read only access to the underlying token, operations such as adding or removing entries will fail. It is possible to use the entries provided by a PKCS11KeystoreServiceImpl for SSL authentication. The available configuration options closely match the parameters provided by the SunPKCS11 implementation, see the official documentation for more details. In particular, the official documentation contains a section that explains how the PKCS11 objects are mapped to Java KeyStore entries. The only required parameter is the PKCS11 Implementation Library Path parameter. It is usually also necessary to specify the token user pin as the Pin parameter. The configuration parameters are mapped to the SunPKCS11 provider parameters in the following way: Kura Parameter SunPKCS11 Parameter Notes Slot slot Slot List Index slotListIndex Enabled Mechanisms enabledMechanisms The curly braces must be omitted Disabled Mechanisms disabledMechanisms The curly braces must be omitted. Attributes attributes The value of this field will be appended to the provider configuration.","title":"PKCS11KeystoreServiceImpl"},{"location":"gateway-configuration/network-configuration/","text":"Network Configuration To configure the gateway network interfaces using the Gateway Administration Console, select the Network option located in the System area. With this option selected, the Network display appears with a list of available interfaces. Configuration tabs for the selected interface appear on the right side of the screen. By default, the loopback (lo) interface is selected when the network interfaces are displayed. Choose the desired network interface (e.g., eth0, eth1, wlan0, ppp0) and apply the necessary configuration changes using the tabs on the right. Submit the modified configuration by clicking the Apply button. In case of typing errors, the Reset button can be used to reload the prior configuration on the screen. Since the network configuration shown on the screen may not be synchronized with the current state of the system, it can be updated pressing the Refresh button. This can be used also to force the reload of specific parameters like the RSSI or dynamic IP addresses. The refresh procedure reads all the needed parameters from the system and can take several seconds before updating. Tip It is recommended that the TCP/IP tab is configured first since it defines how the interface is going to be used. TCP/IP Configuration The TCP/IP tab contains the following configuration parameters: Status Disabled: disables the selected interface (i.e., administratively down). Enabled for LAN: designates the interface for a local network. It can be set as a DHCP server for hosts on the local network and can serve as a default gateway for those hosts; however, it cannot be set as an actual gateway interface for this device. That is, packets must be routed from this interface to another interface that is configured as WAN. The interface is automatically brought up at boot. Enabled for WAN: designates the interface as a gateway to an external network. The interface is automatically brought up at boot. Not Managed: the interface will be ignored by Kura. Layer 2 Only: only the Layer 2 portion of the interface will be configured. The interface is automatically brought up at boot. Configure Manually: allows manual entry of the IP Address and Netmask fields, if the interface is configured as LAN; allows manual entry of the IP Address , Netmask , Gateway , and DNS Servers fields, if the interface is designated as WAN. Using DHCP: configures the interface as a DHCP client obtaining the IP address from a network DHCP server. IP Address - defines the IP address of the interface, if manually configured. Subnet Mask - defines the subnet mask of the interface, if manually configured. Gateway - specifies the default gateway for the unit. (Required field if the interface is designated as WAN and manually configured.) DNS Servers - provides a list of DNS servers, if the interface is designated as WAN and is manually configured. Search Domains - Not implemented. If the network interface is Enabled for LAN and manually configured (i.e., not a DHCP client), the DHCP & NAT tab allows the DHCP server to be configured and/or NAT (IP forwarding with masquerading) to be enabled. More details about the Not Managed interface Status When a network interface is configured as Not Managed , Kura will ignore it and the configuration will not be touched. The user can configure the interface with the network tools provided by the OS, allowing unusual network setups. Regarding DNS, both Kura and the external tools store the DNS addresses in the /etc/resolv.conf file. So, if multiple interfaces are configured to get the DNS information and store it in the same file, the device can be misconfigured. To avoid that, the following table presents who is responsible to update the DNS file depending on the network interfaces configurations. Is there at least an interface set as WAN ? Is there at least one interface set as Not Managed ? Does Kura manage resolv.conf? NO NO YES NO YES NO YES NO YES YES YES YES So, the only way to configure the DNS addresses with external tools, is to configure at least one interface as Not Managed and not to set any interface as Enabled For Wan using Kura. If at least one WAN interface is configured by Kura, it will take the control of the /etc/resolv.conf/ file. Finally, if any interface is configured in Enabled For Wan or Not Managed mode, Kura will empty the file. To avoid device misconfigurations when Not Managed interfaces are used, don't use the dns-nameservers directive in the /etc/network/interfaces file. Please add the DNS addresses directly to the /etc/resolv.conf file. DHCP & NAT Configuration The DHCP & NAT tab contains the following configuration parameters: Router Mode DHCP and NAT: indicates that both DHCP server and NAT are enabled. DHCP Only: indicates that DHCP server is enabled and NAT is disabled. NAT Only: indicates that NAT is enabled and DHCP server is disabled. Off: indicates that both DHCP server and NAT are disabled. DHCP Beginning Address : specifies the first address of DHCP pool (i.e., first available client IP address). DHCP Ending Address : specifies the last address of DHCP pool (i.e., last IP address that can be assigned to a client). DHCP Subnet Mask : defines the subnet mask that is assigned to a client. DHCP Default Lease Time : sets the default time (in minutes) that the client retains the provided IP address. It must be greater than 0. DHCP Max Lease Time : sets the maximum time (in minutes) that the client retains the provided IP address. It must be greater than 0. Pass DNS Servers through DHCP : enables DNS Proxy (i.e., passing DNS servers through DHCP). If NAT is enabled and there is another interface designated as WAN (e.g., ppp0), the following iptables rules are added to the custom automatic NAT service rules _* section of the /etc/init.d/firewall script: # custom automatic NAT service rules (if NAT option is enabled for LAN interface) iptables -t nat -A POSTROUTING -o ppp0 -j MASQUERADE iptables -A FORWARD -i ppp0 -o eth0 -m state --state RELATED,ESTABLISHED -j ACCEPT iptables -A FORWARD -i eth0 -o ppp0 -j ACCEPT Also, IP forwarding is enabled in the kernel as follows: # allow fowarding if any masquerade is defined echo 1 > /proc/sys/net/ipv4/ip_forward The rules shown above create an Overloaded _ (i.e., many-to-one) NAT. This type of network address translation maps multiple IP addresses on the LAN side to a single IP address on the WAN side, allowing internet access from hosts on a local network via a gateway (WAN) interface. Note that for NAT rules to be added, it is insufficient to enable NATing through the DHCP & NAT * tab of the LAN interface; there must also be another interface designated as WAN. Network Linux Configuration When applying a new network configuration, Kura changes the configuration files of the Linux networking subsystem. Please read the following note before proceeding with manual changes of the Linux networking configuration. Warning It is NOT recommended performing manual editing of the Linux networking configuration files when the gateway configuration is being managed through Kura. While Linux may correctly accept manual changes, Kura may not be able to interpret the new configuration resulting in an inconsistent state. Network Configuration properties The Network configuration can be modified using the Kura Gateway Administration Console, as described above, the Configuration Service or appling a proper snapshot . The following table describes all the properties related to the Network Configuration. The network configuration pid is org.eclipse.kura.net.admin.NetworkConfigurationService . Common properties Name Type Description net.interfaces String Comma-separated list of the interface names in the device net.interface..type String The type of the network interface; possible values are: ETHERNET, WIFI, MODEM and LOOPBACK net.interface..config.wifi.mode String For wifi interfaces, specify the modality; possible values are INFRA and MASTER net.interface..config.nat.enabled Boolean Enable the NAT feature IPv4 properties Name Type Description net.interface..config.ip4.status String The status of the interface for the IPv4 configuration; possibile values are: netIPv4StatusDisabled, netIPv4StatusUnmanaged, netIPv4StatusL2Only, netIPv4StatusEnabledLAN, netIPv4StatusEnabledWAN, netIPv4StatusUnknown net.interface..config.ip4.wan.priority Integer (NetworkManager only) Priority used to determine which interface select as primary WAN. Allowed values range from -1 to 2147483647, inclusive. See Network Failover for further details net.interface..config.ip4.address String The IPv4 address assigned to the network interface net.interface..config.ip4.prefix Short The IPv4 netmask assigned to the network interface net.interface..config.ip4.gateway String The IPv4 address of the default gateway net.interface..config.ip4.dnsServers String Comma-separated list of dns servers IPv4 DHCP Server properties Name Type Description net.interface..config.dhcpServer4.enabled Boolean Specify if the DHCP server is enabled net.interface..config.dhcpServer4.rangeStart String First IP address available for clients net.interface..config.dhcpServer4.rangeEnd String Last IP address available for clients net.interface..config.dhcpServer4.defaultLeaseTime Integer The default lease time net.interface..config.dhcpServer4.maxLeaseTime Integer The maximum lease time net.interface..config.dhcpServer4.prefix Short The netmask for the available IP addresses net.interface..config.dhcpServer4.passDns Boolean Specify if the DNS server addresses has to be passed through DHCP IPv4 DHCP Client properties Name Type Description net.interface..config.dhcpClient4.enabled Boolean Specify if the DHCP client is enabled IPv6 properties Name Type Description net.interface..config.ip6.status String The status of the interface for the IPv6 configuration; possibile values are: netIPv6StatusDisabled, netIPv6StatusUnmanaged, netIPv6StatusL2Only, netIPv6StatusEnabledLAN, netIPv6StatusEnabledWAN, netIPv6StatusUnknown net.interface..config.ip6.wan.priority Integer (NetworkManager only) Priority used to determine which interface select as primary WAN. Allowed values range from -1 to 2147483647, inclusive. See Network Failover for further details net.interface..config.ip6.address.method String The IPv6 configuration method; possible values are: AUTO, DHCP, MANUAL. net.interface..config.ip6.address String The IPv6 address assigned to the network interface net.interface..config.ip6.prefix Short The IPv6 netmask assigned to the network interface net.interface..config.ip6.gateway String The IPv6 address of the default gateway net.interface..config.ip6.dnsServers String Comma-separated list of dns servers net.interface..config.ip6.addr.gen.mode String The IPv6 address generation mode; possible values are EUI64, STABLE_PRIVACY; net.interface..config.ip6.privacy String The IPv6 Privacy Extensions for SLAAC; possible values are DISABLED, ENABLED_PUBLIC_ADD, ENABLED_TEMP_ADD WiFi Master (Access Point) properties Name Type Description net.interface..config.wifi.master.driver String The driver used for the connection net.interface..config.wifi.master.passphrase Password The password for the access point net.interface..config.wifi.master.ssid String The SSID of the access point net.interface..config.wifi.master.securityType String The security protocol for the wireless network; possible values are SECURITY_NONE, SECURITY_WEP, SECURITY_WPA, SECURITY_WPA2, SECURITY_WPA_WPA2 net.interface..config.wifi.master.mode String The mode of the wireless connection; for the access point mode set it to MASTER net.interface..config.wifi.master.channel String The channel to be used for the access point net.interface..config.wifi.master.radioMode String Specify the 802.11 radio mode; possible values are RADIO_MODE_80211a, RADIO_MODE_80211b, RADIO_MODE_80211g, RADIO_MODE_80211nHT20, RADIO_MODE_80211_AC net.interface..config.wifi.master.ignoreSSID Boolean Specify if the SSID broadcast is ignored net.interface..config.wifi.master.groupCiphers String Group ciphers i.e. group/broadcast encryption algorithms which prevents connections to Wi-Fi networks that do not utilize one of the algorithms set, possible values are CCMP , TKIP , and CCMP_TKIP net.interface..config.wifi.master.pairwiseCiphers String Pairwise ciphers i.e. pairwise encryption algorithms which prevents connections to Wi-Fi networks that do not utilize one of the algorithms set, possible values are CCMP , TKIP , and CCMP_TKIP WiFi Infra (Station Mode) properties Name Type Description net.interface..config.wifi.infra.ssid String The SSID of the wireless network to connect to net.interface..config.wifi.infra.channel String The channel of the wireless network to connect to net.interface..config.wifi.infra.bgscan String Set the background scans; possible values have the form ::: where mode (String) is one of NONE, SIMPLE, or LEARN, shortInterval (Integer) sets the Bgscan short interval (secs), rssiThreshold (Integer) sets the Bgscan Signal strength threshold (dBm), and longInterval (Integer) sets the Bgscan long interval (secs) net.interface..config.wifi.infra.passphrase Password The password for the wireless network net.interface..config.wifi.infra.ignoreSSID Boolean Specify if a scan for SSID is required before attempting to associate net.interface..config.wifi.infra.mode String The mode of the wireless connection; for station mode set to INFRA net.interface..config.wifi.infra.pingAccessPoint Boolean Enable pinging the access point after connection is established net.interface..config.wifi.infra.driver String The driver used for the connection net.interface..config.wifi.infra.securityType String The security protocol for the wireless network; possible values are SECURITY_NONE, SECURITY_WEP, SECURITY_WPA, SECURITY_WPA2, SECURITY_WPA_WPA2 net.interface..config.wifi.infra.groupCiphers String Group ciphers i.e. group/broadcast encryption algorithms which prevents connections to Wi-Fi networks that do not utilize one of the algorithms set, possible values are CCMP , TKIP , and CCMP_TKIP net.interface..config.wifi.infra.pairwiseCiphers String Pairwise ciphers i.e. pairwise encryption algorithms which prevents connections to Wi-Fi networks that do not utilize one of the algorithms set, possible values are CCMP , TKIP , and CCMP_TKIP Cellular Modem properties Name Type Description net.interface..config.enabled Boolean Enable the interface net.interface..config.idle Integer The idle option of the PPP daemon net.interface..config.username String The username used for the connection net.interface..config.password Password The password used for the connection net.interface..config.pdpType String The PdP type; possible values are IP, PPP and IPv6 net.interface..config.maxFail Integer The maxfail option of the PPP daemon net.interface..config.authType String The authentication type; possible values are None, Auto, CHAP and PAP net.interface..config.lpcEchoInterval Integer The lcp-echo-interval option of the PPP daemon net.interface..config.activeFilter String The active-filter option of the PPP daemon net.interface..config.lpcEchoFailure Integer The lcp-echo-failure option of the PPP daemon net.interface..config.diversityEnabled Boolean Enable the LTE diversity antenna net.interface..config.resetTimeout Integer The modem reset timeout in minutes net.interface..config.gpsEnabled Boolean Enable the GPS device in the modem if available net.interface..config.persist Boolean The persist option of the PPP daemon net.interface..config.apn String The modem Access Point Name net.interface..config.dialString String The dial string used for connecting to the APN net.interface..config.holdoff Integer The holdoff option of the PPP daemon (in seconds) net.interface..config.pppNum Integer Assigned ppp interface number Network Configuration recipes This section presents some snapshot examples to perform basic operations on networking. The snippets can be modified adapting them to the required configuration (i.e. changing the interface name in the property to be applied). Warning Be aware that an inconsitent or wrong configuration can compromise the network functionality of the gateway. Try the new configuration on a test device before appling it in a production environment! Moreover, if a property is not present in the new snapshot, the old value is used for the configuration. So, the best practice is to set all the needed properties in the snapshot. Disable a network interface ETHERNET netIPv4StatusDisabled Configure an ethernet interface for WAN with DHCP client enabled and custom DNS server ETHERNET 1.2.3.4 true false netIPv4StatusEnabledWAN Configure an ethernet interface for LAN with DHCP server enabled and NAT disabled ETHERNET false netIPv4StatusEnabledLAN 192.168.4.110 true 900 24 true 192.168.4.100 900 192.168.4.1 24 false Configure a wireless interface as access point with DHCP server and NAT enabled WIFI netIPv4StatusEnabledLAN 24 172.16.1.1 false 172.16.1.100 900 900 172.16.1.110 24 true true true MASTER nl80211 ZW5hYmxlbWVwbGVhc2U= kura_gateway_19 SECURITY_WPA2 MASTER 11 RADIO_MODE_80211g false CCMP Configure a wireless interface as station mode with DHCP client enabled WIFI netIPv4StatusEnabledLAN true false INFRA MyWirelessNetwork MyPasswordBase64 false INFRA false nl80211 SECURITY_WPA2 Enable a cellular interface MODEM netIPv4StatusEnabledWAN true false 95 IP 5 NONE 0 true inbound 0 false 5 false true atd*99***2# web.omnitel.it ","title":"Network Configuration"},{"location":"gateway-configuration/network-configuration/#network-configuration","text":"To configure the gateway network interfaces using the Gateway Administration Console, select the Network option located in the System area. With this option selected, the Network display appears with a list of available interfaces. Configuration tabs for the selected interface appear on the right side of the screen. By default, the loopback (lo) interface is selected when the network interfaces are displayed. Choose the desired network interface (e.g., eth0, eth1, wlan0, ppp0) and apply the necessary configuration changes using the tabs on the right. Submit the modified configuration by clicking the Apply button. In case of typing errors, the Reset button can be used to reload the prior configuration on the screen. Since the network configuration shown on the screen may not be synchronized with the current state of the system, it can be updated pressing the Refresh button. This can be used also to force the reload of specific parameters like the RSSI or dynamic IP addresses. The refresh procedure reads all the needed parameters from the system and can take several seconds before updating. Tip It is recommended that the TCP/IP tab is configured first since it defines how the interface is going to be used.","title":"Network Configuration"},{"location":"gateway-configuration/network-configuration/#tcpip-configuration","text":"The TCP/IP tab contains the following configuration parameters: Status Disabled: disables the selected interface (i.e., administratively down). Enabled for LAN: designates the interface for a local network. It can be set as a DHCP server for hosts on the local network and can serve as a default gateway for those hosts; however, it cannot be set as an actual gateway interface for this device. That is, packets must be routed from this interface to another interface that is configured as WAN. The interface is automatically brought up at boot. Enabled for WAN: designates the interface as a gateway to an external network. The interface is automatically brought up at boot. Not Managed: the interface will be ignored by Kura. Layer 2 Only: only the Layer 2 portion of the interface will be configured. The interface is automatically brought up at boot. Configure Manually: allows manual entry of the IP Address and Netmask fields, if the interface is configured as LAN; allows manual entry of the IP Address , Netmask , Gateway , and DNS Servers fields, if the interface is designated as WAN. Using DHCP: configures the interface as a DHCP client obtaining the IP address from a network DHCP server. IP Address - defines the IP address of the interface, if manually configured. Subnet Mask - defines the subnet mask of the interface, if manually configured. Gateway - specifies the default gateway for the unit. (Required field if the interface is designated as WAN and manually configured.) DNS Servers - provides a list of DNS servers, if the interface is designated as WAN and is manually configured. Search Domains - Not implemented. If the network interface is Enabled for LAN and manually configured (i.e., not a DHCP client), the DHCP & NAT tab allows the DHCP server to be configured and/or NAT (IP forwarding with masquerading) to be enabled.","title":"TCP/IP Configuration"},{"location":"gateway-configuration/network-configuration/#more-details-about-the-not-managed-interface-status","text":"When a network interface is configured as Not Managed , Kura will ignore it and the configuration will not be touched. The user can configure the interface with the network tools provided by the OS, allowing unusual network setups. Regarding DNS, both Kura and the external tools store the DNS addresses in the /etc/resolv.conf file. So, if multiple interfaces are configured to get the DNS information and store it in the same file, the device can be misconfigured. To avoid that, the following table presents who is responsible to update the DNS file depending on the network interfaces configurations. Is there at least an interface set as WAN ? Is there at least one interface set as Not Managed ? Does Kura manage resolv.conf? NO NO YES NO YES NO YES NO YES YES YES YES So, the only way to configure the DNS addresses with external tools, is to configure at least one interface as Not Managed and not to set any interface as Enabled For Wan using Kura. If at least one WAN interface is configured by Kura, it will take the control of the /etc/resolv.conf/ file. Finally, if any interface is configured in Enabled For Wan or Not Managed mode, Kura will empty the file. To avoid device misconfigurations when Not Managed interfaces are used, don't use the dns-nameservers directive in the /etc/network/interfaces file. Please add the DNS addresses directly to the /etc/resolv.conf file.","title":"More details about the Not Managed interface Status"},{"location":"gateway-configuration/network-configuration/#dhcp-nat-configuration","text":"The DHCP & NAT tab contains the following configuration parameters: Router Mode DHCP and NAT: indicates that both DHCP server and NAT are enabled. DHCP Only: indicates that DHCP server is enabled and NAT is disabled. NAT Only: indicates that NAT is enabled and DHCP server is disabled. Off: indicates that both DHCP server and NAT are disabled. DHCP Beginning Address : specifies the first address of DHCP pool (i.e., first available client IP address). DHCP Ending Address : specifies the last address of DHCP pool (i.e., last IP address that can be assigned to a client). DHCP Subnet Mask : defines the subnet mask that is assigned to a client. DHCP Default Lease Time : sets the default time (in minutes) that the client retains the provided IP address. It must be greater than 0. DHCP Max Lease Time : sets the maximum time (in minutes) that the client retains the provided IP address. It must be greater than 0. Pass DNS Servers through DHCP : enables DNS Proxy (i.e., passing DNS servers through DHCP). If NAT is enabled and there is another interface designated as WAN (e.g., ppp0), the following iptables rules are added to the custom automatic NAT service rules _* section of the /etc/init.d/firewall script: # custom automatic NAT service rules (if NAT option is enabled for LAN interface) iptables -t nat -A POSTROUTING -o ppp0 -j MASQUERADE iptables -A FORWARD -i ppp0 -o eth0 -m state --state RELATED,ESTABLISHED -j ACCEPT iptables -A FORWARD -i eth0 -o ppp0 -j ACCEPT Also, IP forwarding is enabled in the kernel as follows: # allow fowarding if any masquerade is defined echo 1 > /proc/sys/net/ipv4/ip_forward The rules shown above create an Overloaded _ (i.e., many-to-one) NAT. This type of network address translation maps multiple IP addresses on the LAN side to a single IP address on the WAN side, allowing internet access from hosts on a local network via a gateway (WAN) interface. Note that for NAT rules to be added, it is insufficient to enable NATing through the DHCP & NAT * tab of the LAN interface; there must also be another interface designated as WAN.","title":"DHCP & NAT Configuration"},{"location":"gateway-configuration/network-configuration/#network-linux-configuration","text":"When applying a new network configuration, Kura changes the configuration files of the Linux networking subsystem. Please read the following note before proceeding with manual changes of the Linux networking configuration. Warning It is NOT recommended performing manual editing of the Linux networking configuration files when the gateway configuration is being managed through Kura. While Linux may correctly accept manual changes, Kura may not be able to interpret the new configuration resulting in an inconsistent state.","title":"Network Linux Configuration"},{"location":"gateway-configuration/network-configuration/#network-configuration-properties","text":"The Network configuration can be modified using the Kura Gateway Administration Console, as described above, the Configuration Service or appling a proper snapshot . The following table describes all the properties related to the Network Configuration. The network configuration pid is org.eclipse.kura.net.admin.NetworkConfigurationService .","title":"Network Configuration properties"},{"location":"gateway-configuration/network-configuration/#common-properties","text":"Name Type Description net.interfaces String Comma-separated list of the interface names in the device net.interface..type String The type of the network interface; possible values are: ETHERNET, WIFI, MODEM and LOOPBACK net.interface..config.wifi.mode String For wifi interfaces, specify the modality; possible values are INFRA and MASTER net.interface..config.nat.enabled Boolean Enable the NAT feature","title":"Common properties"},{"location":"gateway-configuration/network-configuration/#ipv4-properties","text":"Name Type Description net.interface..config.ip4.status String The status of the interface for the IPv4 configuration; possibile values are: netIPv4StatusDisabled, netIPv4StatusUnmanaged, netIPv4StatusL2Only, netIPv4StatusEnabledLAN, netIPv4StatusEnabledWAN, netIPv4StatusUnknown net.interface..config.ip4.wan.priority Integer (NetworkManager only) Priority used to determine which interface select as primary WAN. Allowed values range from -1 to 2147483647, inclusive. See Network Failover for further details net.interface..config.ip4.address String The IPv4 address assigned to the network interface net.interface..config.ip4.prefix Short The IPv4 netmask assigned to the network interface net.interface..config.ip4.gateway String The IPv4 address of the default gateway net.interface..config.ip4.dnsServers String Comma-separated list of dns servers","title":"IPv4 properties"},{"location":"gateway-configuration/network-configuration/#ipv4-dhcp-server-properties","text":"Name Type Description net.interface..config.dhcpServer4.enabled Boolean Specify if the DHCP server is enabled net.interface..config.dhcpServer4.rangeStart String First IP address available for clients net.interface..config.dhcpServer4.rangeEnd String Last IP address available for clients net.interface..config.dhcpServer4.defaultLeaseTime Integer The default lease time net.interface..config.dhcpServer4.maxLeaseTime Integer The maximum lease time net.interface..config.dhcpServer4.prefix Short The netmask for the available IP addresses net.interface..config.dhcpServer4.passDns Boolean Specify if the DNS server addresses has to be passed through DHCP","title":"IPv4 DHCP Server properties"},{"location":"gateway-configuration/network-configuration/#ipv4-dhcp-client-properties","text":"Name Type Description net.interface..config.dhcpClient4.enabled Boolean Specify if the DHCP client is enabled","title":"IPv4 DHCP Client properties"},{"location":"gateway-configuration/network-configuration/#ipv6-properties","text":"Name Type Description net.interface..config.ip6.status String The status of the interface for the IPv6 configuration; possibile values are: netIPv6StatusDisabled, netIPv6StatusUnmanaged, netIPv6StatusL2Only, netIPv6StatusEnabledLAN, netIPv6StatusEnabledWAN, netIPv6StatusUnknown net.interface.