Pelion Edge provisioning (pep) tool
The Pelion Edge provisioning (pep) tool lets you automate the gateway provisioning flow. The pep tool injects production-mode identity certificates and configuration information onto the gateways over IP. The automation is possible because of these features:
- The gateway initiates certificate injection, instead of Factory Configurator Utility (FCU), which initiates the injection in the default Device Management provisioning flow.
- The pep tool records the enrollment identity and configuration information of all provisioned gateways.
Common use cases of the pep tool include the manufacturing floor, inventory management and testing with production credentials.
Consider a factory set up to provision Pelion Edge enabled gateways with 15 workstations running in parallel. The default provisioning flow, using FCU and FCC, requires accessing the terminal of the gateway to retrieve its IP address, serial number and the port on which FCC runs. You then have to enter the information into FCU, which typically runs outside the gateway on a local factory server. These manual steps reduce operational efficiency, increase complexity and are prone to user error. Therefore, the factory flow generally requires a headless environment in which you automate all steps, and the status is reported through the colors of the LED connected to the gateway.
Please note that this is not a factory tool that automates the complete factory flow process. It is intended to automate the Pelion provisioning flow and provide an easy integration with the factory tool, considering the factory tool is set up according to the customer's and factory's specific requirements.
After you configure the pep API server and run the pep tool successfully in the factory, you can provision any gateway on the same local network without any manual effort.
If your factory dispatches gateways to various end users or tenants, you need a mechanism to track gateways dispatched to specific end users. The pep tool has a database that stores information about dispatched gateways and can later be exported to manage your inventory and the ownership of gateways.
Testing with production credentials:
You can also use the pep tool internally to iteratively test the Pelion Edge firmware in production mode without having to set up separate or individual FCUs, and your QA team can use the tool to automate regression testing and CI workflows.
In the default Device Management gateway provisioning flow, FCU (running outside the gateway) injects the credentials in the gateway over IP. This requires knowing the serial number and IP address of the gateway. This flow cannot be automated because it requires manual effort to read the serial number and IP address off of the gateway. The pep tool inverts this flow by providing REST APIs that allow the gateway to send its serial number and IP address to the server and request the credentials on demand.
The server also saves the identity information and gateway configurations in the database, which you can later download or upload to a server for inventory management or to prime the system for the first-to-claim process.
The server is a multicontainer Docker application with two services:
pep API server: a node.js based RESTful web service that exposes APIs consumed by the client, pep CLI. You can find the API documentation in the
pelion-edge-provisionerrepository. This service internally interacts with FCU and leverages the ft-demo tool, which provides the IP interface to inject the certificates in the gateway. Therefore, the precursor to building the Docker image is to successfully download the factory_configurator_utility archive file from the Pelion Device Management Portal and configure it according to your use case. The details of that can be found in the Prerequisite section. To know more about the Docker image the instructions used to assemble it are stated in this Dockerfile.
Mongo: a service that deploys an instance of MongoDB. The database is used for record keeping. It stores the nonsensitive gateway information, such as gateway's serial number and its configuration parameter values. After the gateway is provisioned successfully in first-to-claim mode, it also stores the enrollment identity, which is the fingerprint of the device certificate of the gateway, but it never stores the device certificate itself. You can export the stored information into CSV format using pep CLI, which you can use for inventory management. When using the first-to-claim process, you can upload it to the Portal using the bulk upload feature.
You can use Docker's compose tool to configure and define the above service containers. It creates:
- A default
bridgenetwork which setup for containers to communicate with each other.
- A Docker volume
mongo_datais created to persistently store the mongo data.
The environment file
.env lists the versions of the services
Physical setup requirements
The server can run on any Docker supported platform and client on any Pelion Edge supported platforms. Both the server and gateway need an IP address and to be connected to the same LAN network.
The server machine must allow inbound and outbound HTTP traffic on port 5151 and also TCP traffic on the port used by Factory Configurator Client (FCC), which is running on the client machine.
Note: We recommend you install the server on a secure machine, in a secure room or both to protect the device keys and certificates. Set up production flow in accordance with good security practices, and use secure processes and Hardware Security Module (HSM) hardware when possible.
./fcu_config_dirfolder that contains the required files:
./fcu_config_dir --- fcu.yml --- factory_configurator_utility.zip --- update-auth-certificate.der --- keystore --- --- CA_private.pem --- --- CA_cert.pem
fcu_config_dirfolder in the root directory of the repository for the contents to be copied to the Docker container.
factory_configurator_utility.zipis the FCU archive.
We license FCU to Device Management customers who manufacture connected devices. Please contact us for more information. Authorized customers can download the tool and documentation from the Device Management Portal.
fcu.ymlis the FCU configuration file.
Follow the documentation to configure FCU. You can find the default
fcu.ymlin the archive file at
Example: Typically, you configure
fcu.ymlwith the following values; everything else remains unchanged.
Parameter Value use-bootstrap true time-sync true verify-on-device true first-to-claim true update-auth-certificate-file <%= ENV['FCU_RESOURCES_DIR'] %>/update-auth-certificate.der vendor-id '42fa7b48-1a65-43aa-890f-8c704daade54' class-id 'c56f3a62-b52b-4ef6-95a0-db7a6e3b5b21' device-info fill the information as per your organization device-key-generation-mode by_tool device-certificate fill the information as per your organization entropy-generation-mode by_device
CA_cert.pemare the certificate authority (CA) private key certificate.
When your devices connect to Device Management, they need to trust the CA certificate that issued the device certificate or one of the CAs in the device certificate chain of trust. To set up a certificate authority, follow the documentation to create your own CA. Place the generated private key,
CA_private.pem, and certificate,
CA_cert.pem, in the
Caution: The OpenSSL commands in the docs are for reference only. You must adapt the commands to your own production setup and security requirements.
Note: As you are creating your own certificate authority, do not populate the X.509 properties in the
certificate-authoritysection of the
Upload the CA certificate: You must upload this CA certificate to Device Management to allow Device Management to trust the device certificates signed by this CA and then connect to Device Management. Follow the document about managing trusted certificates to learn about the various ways you can achieve this and also how to manage the lifecycle of the CAs.
Make sure to select Enrollment from the "How will devices use this certificate?" dropdown.
Note: You can also set up FCU as a CA, but that requires you to manually install the FCU and invoke the
setupAPI. Because installation of FCU is automated in the Docker build process, we recommend you use generate your own CA.
update-auth-certificate.deris the firmware update authentication certificate (optional).
You only need this certificate if you intend to update your firmware. For more information about authentication certificate use and requirements, please see the authenticity certificate documentation.
For testing purposes, you can use the manifest tool to generate the authentication certificate. This enables you to develop the firmware updates for your gateway. These certificates generated above are not suitable for production environments. Only use them for testing purposes.
For example, you can run this command to generate the update certificate:
manifest-tool init -m "<product model identifier>" -V 42fa7b48-1a65-43aa-890f-8c704daade54 -q
You can find the DER formatted update certificate at
.update-certificates/default.der. Rename it to
update-auth-certificate.der, and place it in the
Note: To unlock the rich node features, such as gateway logs and the gateway terminal in the Device Management Portal, pass the command-line parameter
-V 42fa7b48-1a65-43aa-890f-8c704daade54to the manifest tool. Contact the service continuity team to request they enable Edge gateway features in your Device Management Portal account. By default, the features are not enabled.
Manually run the
./fcu-config-validator.shvalidator script on
fcu_config_dirto verify the files are in the correct structure.
Installing the server using Docker
docker-compose to build and run the containers (these
docker-compose commands have been tested with
docker-compose version 1.25.0):
Clone this repository:
git clone https://github.com/armPelionEdge/pelion-edge-provisioner
Build the pep server:
docker-compose build --build-arg fcu_config=<fcu_config_relative_dir_path>
Run the pep server:
docker-compose up -d
Verify that the mongo and pep API server containers are running:
If a container is restarting, view the logs to troubleshoot:
View the API server logs:
docker logs -f pep-api-server
Verify the mongo_data volume was created successfully:
docker volume inspect pelion-edge-provisioner_mongo_data
If the pep API server is running successfully, you can view the Swagger API docs at
Installing the pep CLI tool
pep CLI is a command-line tool that interacts with the pep API server using cURL. To test, you can run it on the same machine as the server, but in production, it runs on the Pelion Edge supported platforms. The supported commands are detailed in the commands section.
Clone this repository on your gateway:
git clone https://github.com/armPelionEdge/pelion-edge-provisioner
Install pep CLI to
/usr/local/binby creating a symlink:
cd pelion-edge-provisioner ln -s `pwd`/cli/bash/pep-cli.sh /usr/local/bin/pep-cli pep-cli --help
Note: Make sure
/usr/local/binis already in your PATH. To verify, run
echo $PATH. If it is not in your PATH, add it.
Alternatively, go to:
cd cli/bash ./pep-cli.sh --help
To enable debug mode:
DEBUG=* pep-cli --help
When you run the CLI on the gateway, you can provide the PEP_SERVER_URL as an env variable:
PEP_SERVER_URL=http://<api-server-ip-address>:5151 pep-cli --help
Pep CLI commands
get-one-identity: Requests the pep API server to create a new identity based on the passed parameters. The prerequisite is to run FCC first. The steps on how to install and run FCC are documented in the typical production provisioning and onboarding flow section.
In the request to the server, provide the gateway IP address and the port at which FCC is running, so the server can then invoke FCU to inject a new device certificate in the gateway.
helpcommand to learn about the various parameters you can pass:
pep-cli get-one-identity --help
get-enrollment-id: After the gateway has been injected with a device certificate, you can request the server to provide the enrollment ID of the gateway, so you can upload it to the Device Management account with which you want the gateway to be associated:
pep-cli get-enrollment-id --help
list-enrollment-ids: Gets the enrollment identities of dispatched gateways in CSV and JSON format. The CSV formatted information is compatible with the bulk upload feature of Portal. Therefore, the information can directly be uploaded to a Pelion account through the Portal or using the bulk upload REST API. The command returns paginated data. By default, the command returns 50 entries in descending order. To enumerate through the list, you can provide the following command line parameters:
limit: Number of results to return. Between 1 and 1000.
order: The order in which the identities have been dispatched.
last: The ID of the last entry in the previous result. Marks the start of the next page.
For more information, run:
pep-cli list-enrollment-ids --help
Typical production provisioning and onboarding flow
- Log in to the gateway.
factory-configurator-client-exampleis not installed, follow the document about building the FCC example on native Linux for the detailed steps. Below are the quick steps that install the program. For example, in the
meta-pelion-edgeproject you can find the precompiled binary located at
Note: This tool is not supported on macOS, so if you are running the server on macOS, you can't test pep CLI on the same machine.
pip install mbed-cli git clone https://github.com/ARMmbed/factory-configurator-client-example.git cd factory-configurator-client-example rm -rf mbed-os.lib mbed deploy python pal-platform/pal-platform.py deploy --target=x86_x64_NativeLinux_mbedtls generate cd __x86_x64_NativeLinux_mbedtls cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=./../pal-platform/Toolchain/GCC/GCC.cmake -DEXTERNAL_DEFINE_FILE=./../linux-config.cmake make factory-configurator-client-example.elf
Binary is located at:
Stop Edge Core, and clear out the old provisioning files. For example, if you are running meta-pelion-edge on Raspberry Pi 3 Model B+, run the following commands:
systemctl stop edge-core rm -rf /userdata/mbed/mcc_config rm -rf /userdata/edge_gw_config
or run this script:
Modify the commands or the scripts for your platform.
On the gateway, run this command:
By default, the interface is
eth0. If required, you can change the interface name:
You can change the entropy source:
Note down the TCP port of FCC: You will use it in the next step.
Fetch a new identity:
- Open another terminal.
- Log in to the gateway.
- Run the following command. At minimum, you must pass in the serial number of the gateway, the IP address of the gateway and the TCP port at which FCC is running.
Note: There is no schema enforced on the
serial_number, but we recommend using only the characters
SPACE. For more information, see endpoint name. However, it has to be unique. The server will not provision two gateways with the same serial number.
PEP_SERVER_URL=http://<api-server-ip-address>:5151 pep-cli get-one-identity -s <serial_number> -i <gateway_ip> -p <fcc_port>
Install a new identity. After the above command runs successfully, the factory-configurator-client-example creates a
palfolder, and pep CLI creates
Place and rename the
palfolder to the location specified by the compile time flag
PAL_FS_MOUNT_POINT_PRIMARYof Edge Core. By default, its defined by this CMake flag. The meta-pelion-edge project overwrites that to this and snap-pelion-edge to this.
Note: Before copying to that location, make sure the folder is not present. Edge Core creates this folder only if this folder is not already present. Therefore, stop Edge Core, and clear out that folder before copying the
identity.jsonto the location specified by
platform_readers/params/identity_pathof Maestro configuration file. In
meta-pelion-edge, its placed at this location and for
For example, in
meta-pelion-edge, you can run the following commands:
mkdir -p /userdata/edge_gw_config mv identity.json /userdata/edge_gw_config/ mv pal/ /userdata/mbed/mcc_config
The same steps are listed in this script. You can modify this script for your platform:
Upload the enrollment identity:
- To retrieve the enrollment ID of this gateway, send a request to the pep API server.
pep-cli get-enrollment-id -s <serial_number>
- Upload the enrollment identity to Device Management by following the First-to-Claim by enrollment list documentation
Connect to Device Management:
- Reboot the gateway.
- Verify the gateway is connected to Device Management. For example, in
meta-pelion-edge, you can run this command to know the status of Edge Core:
How to automate the provisioning flow
- Pre-installed FCC with the Pelion Edge firmware image.
- Create a bash script to:
- Start FCC and capture the TCP port.
- Read the serial number of the gateway. For example, you can find serial number in
/proc/cpuinfoon Raspberry Pi.
- Get the IP address of the gateway. For example, you can grep the IP address from
- Delete the old identity files and reset the gateway configurations.
- Run the pep CLI with the parameters above.
- Install the new identity on the gateway and then reboot.
Typically, these steps are integrated with the factory tool, which is responsible for installing the gateway firmware image and validating the hardware.
factory-configurator-client-example, if you see this error on the gateway:
ImportError: No module named site
Unset the Python path:
unset PYTHONPATH unset PYTHONHOME
If you see
bad-requesterror on mbed-edge, mbed-edge and factory-configurator-client-example have been compiled with different entropy sources.
If you see
Connection erroron mbed-edge, make sure the enrollment identity and the CA certificate has been uploaded successfully to your Device Management account.