This document is not up-to-date, please refer to the Japanese document.
Installation
Overview
This manual explains the installation procedure of enebular-agent.
There are two connection methods for enebular-agent: connecting to enebular using AWS IoT and connecting to enebular using Pelion Device Management. Although this manual explains both installation procedures, only one of them can be installed on one device at any time. Installation is performed by executing a shell script on the Linux OS of the target device.
Description
Prerequisites
The prerequisites executing the installation script are as follows.
Linux
- Debian GNU/Linux supported by enebular-agent must be installed
- A user has been created to execute enebular-agent (hereinafter described on the assumption that the "enebular" user has been created)
- The user installing has Super User permission (using sudo command)
- Having an internet connection environment
AWS IoT（For AWS IoT）
- AWS account has been created
- This account has been granted AWSIoTConfigAccess privileges
- AWS Access Key Id (AWSAccessKeyId) used to install enebular
- AWS Secret Access Key (AWSSecretKey) used to install enebular
Pelion Device Management （For Pelion Device Management）
- Create an account for Pelion Device Management
- The API Key of Pelion Device Management used to install enebular
- When installing in factory mode, acquire authentication information (device bundle) for factory
- Contact [email protected] for details on creating device bundles
enebular
- An enebular account
- A project in enebular
Execute installation script
The installation script can be executed with the following command from shell by logging in to the target device Linux.
wget -qO- https://enebular.com/agent-install | sudo -E bash -s -- option1 option2 ・・・
The directory for executing the above command can be anywhere. The installation script is obtained via the Internet from the enebular.com server.
The installation directory is specified by the installation script option. Therefore, you can run the installation script in any directory.
Option
The following table shows the options and option arguments that can be set in the installation script.
| Option | Optional argument | Description |
|---|---|---|
| -p or --port | -p=[awsiot, pelion] | Specify whether to use in conjunction with AWS IoT (awsiot) or to use in conjunction with Pelion Device Management (pelion) |
| -u or --user | -u=* | Specify a Linux username (Note 1) |
| -d or --install-dir | -d=path | Specify the installation directory on Linux (Note 2) |
| -v or --release-version | -v=* | Specifies the version of enebular-agent |
| --no-startup-register | None | Specify whether to enable or disable automatic start of enebular-agent (Note 3) |
| --aws-access-key-id | =* | AWS Access Key Specify ID |
| --aws-secret-access-key | =* | Specify your AWS Secret Access Key |
| --aws-iot-region | =* | Specify the AWS IoT Region |
| --aws-iot-thing-name | =* | Specify the name of the AWS IoT thing |
| --mbed-cloud-mode | =[developer, factory] | Specify the Pelion connection mode (developer, factory) |
| --mbed-cloud-dev-cred | =* | When the connection mode of Pelion is set to developer, specify the authentication information file path (Note 4) |
| --mbed-cloud-pal | =* | When Pelion connection mode is set to factory, specify the path of authentication information (pal directory) (Note 4) (Note 5) |
| --mbed-cloud-bundle | =* | When Pelion connection mode is set to factory, specify the path of authentication information (bundle file) (Note 4) (Note 5) |
| --dev-mode | None | Specify the start mode (Developer mode, Normal mode) when enabling automatic start of enebular-agent |
| --remote-maintenance-user-password | =* | Specify the password of the Remote Maintenance login user (Note 6) |
Indicates any string =[aaa, bbb] Indicates to choose either aaa or bbb
Note 1: enebular-agent is installed and executed by the user specified here
- Note 2: If the specified directory does not exist, it will be created
- Note 3: The automatic start of enebular-agent is realized by making Linux service
- Note 4: Specify the path of the file where the authentication information is placed. This path is recommended to use temporary storage area which is not saved after reboot
- Note 5: Please contact [email protected] for information on how to create authentication information for factory mode
- Note 6: For security reasons, it is recommended to set a password
Reference: About the name of option "mbed-cloud"
- Pelion Device Management has been available since August 2018
- Because this script file was created before that, it remains with the original name "mbed cloud" of Pelion Device Management
Option Details
The following table shows the needs of each option for AWS IoT and Pelion Device Management.
| option | AWS IoT setting items | Pelion Device Management setting items | Setting contents when option is omitted |
|---|---|---|---|
| -p or --port | Optional | Required (pelion) | awsiot |
| -u or --user | Required (User registered user name) | Required (User registered user name) | enebular (Note １) |
| -d or --install-dir | Optional | Optional | /home/<user>/enebular-runtime-agent |
| -v or --release-version | Optional | Optional | The latest release (Latest release) |
| --no-startup-register | Omission recommendation | Omission recommendation | Enable auto Launch of enebular-agent |
| --aws-access-key-id | Required | Unnecessary | Cannot omit |
| --aws-secret-access-key | Required | Unnecessary | Cannot omit |
| --aws-iot-region | Required | Unnecessary | Cannot omit |
| --aws-iot-thing-name | Required | Unnecessary | Cannot omit |
| --mbed-cloud-mode | Unnecessary | Required (factory) | developer (Note ２) |
| --mbed-cloud-dev-cred | Unnecessary | Unnecessary | Cannot omit |
| --mbed-cloud-pal | Unnecessary | Required (Not required if --mbed-cloud-bundle is specified) | Cannot omit |
| --mbed-cloud-bundle | Unnecessary | Required (Not required if --mbed-cloud-pal is specified) | Cannot omit |
| --dev-mode | Optional | Optional | Start enebular-agent in "Normal mode" (Note 3) |
| --remote-maintenance-user-password | Optional | Optional | enebular |
- Note 1: Please use the registered user name under Linux. If you use a user name that has not been registered, the directory files required for this system will be created on Linux, but additional work is required to enable login.
- Note 2: Recommended connection mode of Pelion is "factory". If you use "developer", please contact [email protected]
- Note 3: We recommend "normal mode" at the time of the first installation of enebular-agent's startup mode
Notes on setting options
Lists of notes on setting options.
- Multiple options can be specified (Keep spaces/blacks between options)
- Do not put unnecessary single-byte blanks in the option argument
- -d(--install-dir) Specify with full path when specifying option (example: -d=/home/enebular/enebular-runtime-agent）
If you do not specify an option when executing the command, "Default settings for option" is set.
wget -qO- https://enebular.com/agent-install | sudo -E bash -s
If -p -u -d is not specified as in the above example, it will be set as follows.
- Connect with enebular using AWS IoT
- enebular-agent runs as the enebular user
- The installation directory will be
/home/enebular/enebular-runtime-agent
Example
Install Example
The execution example of the installation script is divided into AWS IoT and Pelion Device Management.
Example of command execution for AWS IoT
wget -qO- https://enebular.com/agent-install | sudo -E bash -s -- --aws-iot-thing-name=enebular-agent-test --aws-access-key-id=AKIAJWWCHDEPQJD456PQ --aws-secret-access-key=6qtl9JJ90ue5CMeHSJKm1I4iRRwKOQKLCpzt9Y94 --aws-iot-region=us-west-2`
Explanation of the options in the above example is as follows.
- Linux users
enebular(default value is applied to omit option) - AWS Access Key ID is
AKIAJWWCHDEPQJD456PQ - AWS Secret Access Key is
6qtl9JJ90ue5CMeHSJKm1I4iRRwKOQKLCpzt9Y94 - AWS IoT region
us-west-2 - Name of the AWS IoT thing
enebular-agent-test - Other options are omitted
Note: The AWS Access Key ID and AWS Secret Access Key values listed here are just examples, so executing a command using this value will not complete successfully.
Example of Command Execution for Installing to Raspberry Pi
It is recommended to use pi for the user name when installing enebular-agent to Raspberry Pi.
wget -qO- https://enebular.com/agent-install | sudo -E bash -s -- --aws-iot-thing-name=enebular-agent-test --aws-access-key-id=AKIAJWWCHDEPQJD456PQ --aws-secret-access-key=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 --aws-iot-region=us-west-2 --user=pi
The pi user, which is the default user on Raspberry Pi OS, belongs to the groups which can access peripherals such as GPIO and I2C.
By installing with the user name set to pi, it's possible to avoid needing to configure access permissions when using peripherals from enebular-agent.
If installing with a user name other than pi, as the user doesn't belong to the groups which can access peripherals, the required access permissions for the peripherals will need to be granted as required.
Command execution example for Pelion Device Management
wget -qO- https://enebular.com/agent-install | sudo -E bash -s -- -p=pelion --mbed-cloud-mode=factory --mbed-cloud-pal=/tmp/pelion/pal --mbed-cloud-build-fcc
Explanation of the options in the above example is as follows.
- Linux users
enebular(default value is applied to omit option) - Pelion connection mode is
factory - The path of Pelion's authentication information (device bundle) is
/ tmp / pelion / pal(Please put the device bundle in the path shown left) - Build Pelion's FCC Tools
- Other options are omitted
Example of Command Execution for Installing to Raspberry Pi
It is recommended to use pi for the user name when installing enebular-agent to Raspberry Pi.
For details, see the example of command execution for AWS IoT.
wget -qO- https://enebular.com/agent-install | sudo -E bash -s -- -p=pelion --mbed-cloud-mode=factory --mbed-cloud-pal=/tmp/pelion/pal --user=pi
Result
Directory structure
If installation is successful, relevant files will be installed on the target device with the following directory configuration.
/home/
└enebular/ ← user name
├enebular-runtime-agent/ ← install directory
└nodejs-v/ ← JavaScript
In AWS IoT's case, please backup as the following keys and certificates are generated in the /home/enebular/enebular-runtime-agent/ports/awsiot/certs/ directory.
- enebular-agent-test-private.pem
- enebular-agent-test.crt.pem
- root.pem
Checking the execution status of enebular-agent
sudo journalctl -ex -u enebular-agent-enebular.service
If you have installed in a configuration that automatically starts enebular-agent (if you do not specify --no-startup-register), you can check the execution status of enebular-agent by executing the above command.
Checking on AWS IoT
You can check the following from the management screen of AWS IoT.
- "Admin"-"enebular-agent-test" is added to "thing"
- You can check "HTTPS (end point)" in "Manage"-"Material"-"enebular-agent-test"-"Operation"
Uninstallation
You can uninstall the software from the device by following the steps below.
sudo systemctl stop enebular-agent-{agent's installation user name}.service
sudo systemctl disable enebular-agent-{agent's installation user name}.service
sudo rm /etc/systemd/system/enebular-agent-{agent's installation user name}.service
Example of command execution to uninstall enebular-agent installed on Raspberry Pi.
sudo systemctl stop enebular-agent-pi.service
sudo systemctl disable enebular-agent-pi.service
sudo rm /etc/systemd/system/enebular-agent-pi.service
If you want to delete the entire user for agent, execute the following command.
sudo deluser --remove-all-files {agent install-username}
To remove the elements of enebular-agent, execute the following command.
※The version number of nodejs should be set to the version number found under /home/{agent installation user name}/.
sudo rm -r /home/{agent installation user name}/enebular-runtime-agent
sudo rm -r /home/{agent installation user name}/nodejs-v{nodejs version number}
Troubleshooting
Insufficient storage space
- If there is not enough free space available to install enebular-agent, it may fail to install with an error message.
It's possible that even when there is enough overall space, it may fail to install if the space has been divided into partitions.
The installer saves the package downloaded to the /tmp directory. That's why if not enough space has been assigned to the /tmp directory, there may not be enough space to download the installation package.
In these cases, it may be possible to resolve the problem by adjusting partition settings.