diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..2fc6c2d --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,24 @@ +# Mbed Edge Examples pull request + +` +Please fill this pull request template to describe your pull request. +If it introduces API breaks please describe it in detail. +` + +## Description + +submitter: Please add a description of your PR here. + +## Test instructions + +Submitter: Please add instructions to test your PR here. + +If your pull request is a fix for a defect please write instructions +to reproduce the defect. + +## Check list + +### Changelog + + - [ ] `CHANGELOG.md` updated. + diff --git a/CHANGELOG.md b/CHANGELOG.md index f77f843..a09a7d9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog for Edge examples +## Release 0.21.0 + +* Update mbed-edge submodule to 0.21.0. +* Ubuntu references updated to 22.04 and 20.04 (18.04 dropped). +* Typo fixes. + ## Release 0.20.0 * Update mbed-edge submodule to 0.20.0. diff --git a/README.md b/README.md index ecae957..d7f1e42 100644 --- a/README.md +++ b/README.md @@ -30,10 +30,10 @@ This example tests the robustness and thread safeness of Protocol API C-API inte # Build and run the examples -1. Directly on Ubuntu 20.04 or 18.04, or +1. Directly on Ubuntu 22.04 or 20.04 or 1. Using Docker. -## Using Ubuntu 20.04 or 18.04: +## Using Ubuntu 22.04 or 20.04: 1. Dependencies @@ -46,16 +46,16 @@ This example tests the robustness and thread safeness of Protocol API C-API inte Install these (using `sudo` typically): ``` - $ apt install build-essential git libc6-dev - $ apt install libmosquitto-dev mosquitto-clients - $ apt install libglib2.0-dev + apt install build-essential git libc6-dev + apt install libmosquitto-dev mosquitto-clients + apt install libglib2.0-dev ``` 1. Preparing all the sources Please run the following to clone and update all the git modules. ``` - $ git submodule update --init --recursive + git submodule update --init --recursive ``` 1. Building @@ -64,20 +64,20 @@ This example tests the robustness and thread safeness of Protocol API C-API inte To make all examples without debug information and with default trace level, run ``` - $ make build-all-examples + make build-all-examples ``` It will build the examples to `build/bin` directory. To make all examples with debug information and debug trace level, run ``` - $ make build-all-examples-debug + make build-all-examples-debug ``` It will build the examples to `build-debug/bin` directory. To make all examples with ThreadSanitizer and debug trace level, run ``` - $ make build-all-examples-sanitize + make build-all-examples-sanitize ``` It will build the examples to `build-sanitize/bin` directory. @@ -85,13 +85,13 @@ This example tests the robustness and thread safeness of Protocol API C-API inte Running `make all` will generate `build`, `build-debug` and `build-sanitize` directories. Please note following: - mqttpt-example will not be built if the libmosquitto is not installed. + `mqttpt-example` will not be built if the `libmosquitto` is not installed. For more examples, see the rules in the Makefile. 1. Running the examples - Each of the examples has a README.md file that documents how to run the example. + Each of the examples has a `README.md` file that documents how to run the example. ## Using Docker diff --git a/blept-example/devices.c b/blept-example/devices.c index 0b60dc3..b8b86c0 100644 --- a/blept-example/devices.c +++ b/blept-example/devices.c @@ -1,6 +1,7 @@ /* * ---------------------------------------------------------------------------- * Copyright 2018 ARM Ltd. + * Copyright (c) 2023 Izuma Networks * * SPDX-License-Identifier: Apache-2.0 * @@ -34,7 +35,7 @@ #include #define LIFETIME \ - 300 // this setting currently has no effect. The translated endpoints are tracked withing the parent Edge device + 300 // this setting currently has no effect. The translated endpoints are tracked within the parent Edge device // lifetime. Please see BLE_MAX_BACK_OFF_TIME_SECS for related configuration. #define TRACE_GROUP "BLEC" diff --git a/blept-example/pt_ble.c b/blept-example/pt_ble.c index 84f3740..6bd9e91 100644 --- a/blept-example/pt_ble.c +++ b/blept-example/pt_ble.c @@ -1,7 +1,8 @@ /* * ---------------------------------------------------------------------------- * Copyright 2018 ARM Ltd. - * + * Copyright (c) 2023 Izuma Networks + * * SPDX-License-Identifier: Apache-2.0 * * Licensed under the Apache License, Version 2.0 (the "License"); @@ -59,7 +60,7 @@ #define BLE_DEVICE_ADDRESS_SIZE 18 #define BLE_DEVICE_NAME_MAX_LENGTH 33 #define MAX_PATH_LENGTH 256 -#define MAX_VALUE_STRING_LENGHT 10 +#define MAX_VALUE_STRING_LENGTH 10 #define TRACE_GROUP "BLE" #define BLE_VALUE_READ_INTERVAL 5000 #define BLE_RETRY_SLEEP_TIME_INITIAL_SECS 4 diff --git a/c-api-stress-tester/stress_tester.c b/c-api-stress-tester/stress_tester.c index a1a1430..2c1c41a 100644 --- a/c-api-stress-tester/stress_tester.c +++ b/c-api-stress-tester/stress_tester.c @@ -1,6 +1,7 @@ /* * ---------------------------------------------------------------------------- * Copyright 2018 ARM Ltd. + * Copyright 2023 (c) Izuma Networks * ---------------------------------------------------------------------------- */ #define _POSIX_C_SOURCE 200809L @@ -713,7 +714,7 @@ void *protocol_translator_api_start_func(void *ctx) pt_cbs.received_write_cb = (pt_received_write_handler) received_write_handler; pt_cbs.connection_shutdown_cb = (pt_connection_shutdown_cb) shutdown_cb_handler; pt_api_thread_t *api_data = pt_start_ctx->api_thread; - // Don't lock connection mutex here, because this funtion starts the eventloop. + // Don't lock connection mutex here, because this function starts the eventloop. if (0 != pt_client_start(pt_start_ctx->socket_path, pt_start_ctx->name, &pt_cbs, diff --git a/lib/mbed-edge b/lib/mbed-edge index 4c0c619..df99b7d 160000 --- a/lib/mbed-edge +++ b/lib/mbed-edge @@ -1 +1 @@ -Subproject commit 4c0c619bc2bc3f252c250d5f761e0c1675e0d7cf +Subproject commit df99b7d62295a883ade4c33602c4388207297b99 diff --git a/mqttpt-example/README.md b/mqttpt-example/README.md index ec2b934..1d763f8 100644 --- a/mqttpt-example/README.md +++ b/mqttpt-example/README.md @@ -49,13 +49,13 @@ hold the sensor value. Start edge-core: ``` -$ ./edge-core +./edge-core ``` Start the mqttpt-example: ``` -$ mqttpt-example +mqttpt-example ``` On Device Management, you should see the MQTT endpoints appear as new devices and they @@ -66,7 +66,7 @@ The mqttpt-example supports optional command-line parameters, for example to set For help, use: ``` -$ mqttpt-example --help +mqttpt-example --help ``` ### Crypto API @@ -76,13 +76,13 @@ To subscribe to certificate renewal notifications, do the following when the gat connected state: ``` -$ mqttgw_sim/mqtt_gw_crypto_api.sh set-certificates-list certificate_names +mqttgw_sim/mqtt_gw_crypto_api.sh set-certificates-list certificate_names ``` To renew a certificate, it must first be added to the certificate list with the `set-certificates-list` operation as described above. To renew a certificate, do the following: ``` -$ mqttgw_sim/mqtt_gw_crypto_api.sh renew-certificate certificate_name +mqttgw_sim/mqtt_gw_crypto_api.sh renew-certificate certificate_name ``` Only one certificate can be renewed at a time, and the certificate identified by `certificate_name` must exist on the device. It's supported to renew factory provisioned certificates, @@ -92,8 +92,8 @@ for example ones created by the FCU tool. Renewing developer certificates is not To test out fetching of the certificate or public key, do the following when the gateway is in the connected state: ``` -$ mqttgw_sim/mqtt_gw_crypto_api.sh get-certificate certificate_name -$ mqttgw_sim/mqtt_gw_crypto_api.sh get-public-key certificate_name +mqttgw_sim/mqtt_gw_crypto_api.sh get-certificate certificate_name +mqttgw_sim/mqtt_gw_crypto_api.sh get-public-key certificate_name ``` Only one certificate or public key can be fetched at the same time. The certificates identified by `certificate_name` @@ -102,8 +102,8 @@ must exist on the device. To test out the asymmetric signing and verifying, do the following: ``` -$ mqttgw_sim/mqtt_gw_crypto_api.sh asymmetric-sign private_key_name hash_digest -$ mqttgw_sim/mqtt_gw_crypto_api.sh asymmetric-verify private_key_name hash_digest signature +mqttgw_sim/mqtt_gw_crypto_api.sh asymmetric-sign private_key_name hash_digest +mqttgw_sim/mqtt_gw_crypto_api.sh asymmetric-verify private_key_name hash_digest signature ``` The certificates identified by `private_key_name` must exist on the device. `Hash-digest` is a string that has been @@ -124,7 +124,7 @@ hash_digest=$(echo $hash_digest |base64) To test out the ecdh key agreement, do the following: ``` -$ mqttgw_sim/mqtt_gw_crypto_api.sh ecdh-key-agreement private_key_name peer_public_key +mqttgw_sim/mqtt_gw_crypto_api.sh ecdh-key-agreement private_key_name peer_public_key ``` The certificates identified by `private_key_name` must exist on the device. Parameter `peer_public_key` is a public key @@ -133,7 +133,7 @@ that has been base64-encoded. To test out the random byte array generation, do the following: ``` -$ mqttgw_sim/mqtt_gw_crypto_api.sh ecdh-key-agreement generate-random size_of_array +mqttgw_sim/mqtt_gw_crypto_api.sh ecdh-key-agreement generate-random size_of_array ``` ### Device certificate renewal @@ -144,7 +144,7 @@ The MQTT protocol translator example demonstrates device certificate renewal or The device initiated certificate renewal or enrollment is performed using the `mqttgw_sim/mqtt_gw_crypto_api.sh` script: ``` -$ mqttgw_sim/mqtt_gw_crypto_api.sh device-cert-renew device_name certificate_name csr +mqttgw_sim/mqtt_gw_crypto_api.sh device-cert-renew device_name certificate_name csr ``` where `device_name` is the device that is performing the enrollment, `certificate_name` is the certificate to enroll and `csr` is the certificate signing request in DER format and base64 encoded. @@ -158,13 +158,13 @@ The renewal or enrollment operation can also be requested from the cloud, for th A test certificate signing request (CSR) can be generated with openssl: ``` -$ openssl ecparam -name prime256v1 -genkey -noout -out private.key # Create private key -$ openssl req -new -nodes -out csr.req -key private.key -subj "/CN=CUSTOM_CERT_TEST/O=TEST/L=Test/ST=Test/C=EN/OU=ARM" -sha256 -outform DER # Create CSR -$ base64 -w 0 csr.req > csr_b64.txt # Base64 encode the CSR +openssl ecparam -name prime256v1 -genkey -noout -out private.key # Create private key +openssl req -new -nodes -out csr.req -key private.key -subj "/CN=CUSTOM_CERT_TEST/O=TEST/L=Test/ST=Test/C=EN/OU=ARM" -sha256 -outform DER # Create CSR +base64 -w 0 csr.req > csr_b64.txt # Base64 encode the CSR ``` The generated CSR can then be used when performing the enrollment for example like this: ``` -$ mqttgw_sim/mqtt_gw_crypto_api.sh device-cert-renew device_name certificate_name $(cat csr_b64.txt) +mqttgw_sim/mqtt_gw_crypto_api.sh device-cert-renew device_name certificate_name $(cat csr_b64.txt) ``` diff --git a/mqttpt-example/mqttgw_sim/README.md b/mqttpt-example/mqttgw_sim/README.md index 6c4214b..5b5d916 100644 --- a/mqttpt-example/mqttgw_sim/README.md +++ b/mqttpt-example/mqttgw_sim/README.md @@ -4,33 +4,52 @@ This is an MQTT gateway simulator to test the `mqttpt-example` protocol translat ### Requirements Requires `mosquitto_pub` client for publishing the MQTT messages to MQTT broker. -`$ apt install mosquitto-clients` +``` +sudo apt install mosquitto-clients` +``` ### Usage 1. Run `edge-core` and `mqttpt-example` 2. Register MQTT gateway by running `mqtt_gw.sh` script. -`$ ./mqtt_gw.sh` +``` +./mqtt_gw.sh +``` + 3. Register device by running `mqtt_ep.sh` script. -`$ ./mqtt_ep.sh` +``` +./mqtt_ep.sh +``` 4. Update certificates `cert_id_1` and `cert_id_2` on the gateway -`$ ./mqtt_gw_crypto_api.sh --renew-certificates cert_id_1 cert_id_2` +``` +./mqtt_gw_crypto_api.sh --renew-certificates cert_id_1 cert_id_2 +``` + 5. Get certificate `cert_id_1` -`$ ./mqtt_gw_crypto_api.sh --get-certificate cert_id_1` +``` +./mqtt_gw_crypto_api.sh --get-certificate cert_id_1 +``` + 6. Get public key for `cert_id_1` -`$ ./mqtt_gw_crypto_api.sh --get-public-key cert_id_1` +``` +$ ./mqtt_gw_crypto_api.sh --get-public-key cert_id_1 +``` + Notice that the device script accepts parameters for device name, temperature and humidity. For example to register device `MY_DEVICE` and set temperature value to 20.1C and humidity value to 67.5%: -`$ ./mqtt_ep.sh -d MY_DEVICE -t 20.1 -h 67.5` +``` +./mqtt_ep.sh -d MY_DEVICE -t 20.1 -h 67.5 +``` + `mqtt_gw_crypto_api.sh` script can also be used to test rest of the crypto-features. Full list of the supported operations is diff --git a/mqttpt-example/mqttpt_example.c b/mqttpt-example/mqttpt_example.c index ba404d8..b365cbf 100644 --- a/mqttpt-example/mqttpt_example.c +++ b/mqttpt-example/mqttpt_example.c @@ -1,6 +1,7 @@ /* * ---------------------------------------------------------------------------- * Copyright 2018 ARM Ltd. + * Copyright (c) 2023 Izuma Networks * * SPDX-License-Identifier: Apache-2.0 * @@ -166,7 +167,7 @@ static void publish_to_mqtt(const char *topic, json_t *json_message) /* Success message format: * { - * "request_id": "id of the request that was succesful", + * "request_id": "id of the request that was successful", * "value": "response value for the request" * } */ diff --git a/pt-example/README.md b/pt-example/README.md index 4f327ef..33a4ef2 100644 --- a/pt-example/README.md +++ b/pt-example/README.md @@ -12,7 +12,7 @@ client API. This example creates three mediated devices and registers then to Device Management. There are two temperature sensors and one thermometer. The `cpu-temperature` device is created only if the underlying operating system -provides CPU temperature values from the `/sys/class/thermal/thermalzone[N]` file. +provides CPU temperature values from the `/sys/class/thermal/thermal_zone[N]` file. Otherwise the CPU temperature values are random values. The reset operation is supported for the `cpu-temperature` and it can be triggered by sending a `POST` operation from Device Management to that resource. Also diff --git a/simple-js-examples/README.md b/simple-js-examples/README.md index cc4a970..1775866 100644 --- a/simple-js-examples/README.md +++ b/simple-js-examples/README.md @@ -16,7 +16,7 @@ These example protocol translators demostrate the fota capabilities. The PT need | Vendor UUID | 10255 | 0 | 3 | | Class UUID | 10255 | 0 | 4 | -The edge-core uses these resources to receive the manifest, send the status as well as the result back to the cloud. The PT needs to implement the function that receives the vendorid, classid, version and firmware size using `manifest_meta_data` api. The PT then needs to verifies the vendor and class id. Upon successfull verification, the PT needs to send the download request to the edge-core using `download_asset` api. If the edge-core successfully downloaded the firmware, the PT receives the path of the downloaded binary, otherwise it gets the error. The PT then needs to deregister the device and starts the firmware update process. The PT then registers the device with the new firmware version(14/0/2) that it received from the `manifest_meta_data` api. +The edge-core uses these resources to receive the manifest, send the status as well as the result back to the cloud. The PT needs to implement the function that receives the vendorid, classid, version and firmware size using `manifest_meta_data` api. The PT then needs to verifies the vendor and class id. Upon successful verification, the PT needs to send the download request to the edge-core using `download_asset` api. If the edge-core successfully downloaded the firmware, the PT receives the path of the downloaded binary, otherwise it gets the error. The PT then needs to deregister the device and starts the firmware update process. The PT then registers the device with the new firmware version(14/0/2) that it received from the `manifest_meta_data` api. ## simple-pt-example.js and pt-crypto-api-example.js @@ -39,7 +39,7 @@ JSONRPC 2.0 API and read the relevant documentation for Edge APIs from This example management application demostrates the calls and parameters to pass to Edge core management API. The websocket connection and JSONRPC 2.0 -specification and communciation is left out of the scope to keep the +specification and communication is left out of the scope to keep the example simple. This application is interactive and supports few command that can be given @@ -72,7 +72,7 @@ This example uses `node.js v8` or higher. Install the dependencies: ```bash -$ npm install +npm install ``` Dependencies are: @@ -90,7 +90,7 @@ Dependencies are: The list with version can be listed with: ```bash -$ npm ls +npm ls ``` ## Running the protocol translator example @@ -109,7 +109,7 @@ Fixed values for the example: from [Device Management Portal](https://portal.mbedcloud.com) 1. Run this example and connect to Edge. ```bash - $ nodejs simple-pt-example.js + nodejs simple-pt-example.js ``` Or, using docker ``` @@ -130,7 +130,7 @@ Fixed values for the example: [Edge examples](https://github.com/PelionIoT/mbed-edge-examples). 1. Run this example and connect to Edge. ```bash - $ nodejs simple-mgmt-example.js + nodejs simple-mgmt-example.js ``` 1. Use the `connect()` function provided by the interactive example to connect to the Edge Core. @@ -152,7 +152,7 @@ Fixed values for the example: from [Device Management Portal](https://portal.mbedcloud.com) 1. Run this example and connect to Edge. ```bash - $ nodejs simple-grm-example.js + nodejs simple-grm-example.js ``` 1. Follow the command prompt to register resource manager, add gateway resources and update them. 1. Monitor the registered Edge and gateway resources from Device Management Portal.