# SimpleIOT Command-Line-Interface (CLI)
This is the command-line-interface (CLI) for the [SimpleIOT](https://simpleiot.net) framework.
SimpleIOT abstracts out IoT device connectivity and hides the underlying details so you can focus on your application's unique features.
## Basic Concepts
In the SimpleIOT world, an installation supports the following concepts:
- **team**: A single installation of SimpleIOT in the cloud. This is mainly relevant to using the Command-Line-Interface (CLI) tool.
- **project**: Each backend supports one or more _Projects_.
- **Model**: A _Model_ describes a device's capabilities. For example, what data it likes to exchange with the cloud, whether an end-node or a gateway device, what features it supports (i.e., storage, encryption, or AI/ML.), and how it communicates with the cloud.
- **DataType**: A _DataType_ is a single named value that can be exchanged between a device and the cloud. A _Model_ typically has one or more _DataTypes_ associated with it.
- **Device**: A _Device_ represents a single instance of a _Model_. Each device has a unique identification via its _serial_number_.
- **Data**: A _Data_ element is an instance of a _DataType_ associated with a single _Device_. For example, if a _Model_ defines a _DataType_ named `pressure`, each unique _Device_ will have its own instance of `pressure`. You can get/set values associated with each _Device_ instance by name.
_Data_ elements are bi-directional so that updates go from the devices to or from the cloud back to the device. It is up to the firmware to handle what to do with values received from the cloud.
## Dual-use
This CLI can be used by both backend administrators as well as end-users.
As an Administrator, you need to:
- Have one or more AWS accounts with IAM Administrative privileges.
- Configure a profile for each account by running the `aws configure` command.
With this CLI, you can:
- Create a private, serverless IOT backend on AWS.
- Create one or more Teams (individual backend installations on each account).
- Securely invite users to join the team (including support for bulk emailing).
- Remove users from a Team.
As a User, you can:
- Join a Team to which you have been invited.
- Install an Arduino command-line toolchain with support for ESP32 processors.
- Create and manage Projects, Models, DataTypes, and Devices.
- Simulate and monitor remote device values via `set` and `get` operations.
- Provision and deploy secure IOT device instances.
- Generate firmware source code based on templates (currently supporting the ESP32/Arduino toolchain).
- Compile and flash firmware to an M5Stack ESP-32 device via USB cable.
- Monitor MQTT traffic sent to/from AWS IOT.
The CLI can be installed on systems running at least Windows 10 or MacOS Big Sur. It requires pre-installation of **Python** (Users + Administrators) and **Docker Desktop** (Administrators).
## Installation
Administrators can install and remove the backend cloud for a SimpleIOT deployment. They can also invite new users to the _Team_ so they can interact with an existing installation.
### Step 1: AWS CLI
Before creating a backend, you need to make sure you have an AWS account created and a user account configured via the [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html).
---
**NOTE**
This will require downloading and setting up an account with AWS IAM Administrative Privileges. If you are not allowed to have AWS admin privileges, a list of fine-grain IAM privileges will be released along with the SimpleIOT back-end sources. These can be used to create only the privileges needed by the system.
This is a one-time operation. Once configured, you may proceed with the following steps. You can configure multiple named profiles using the `aws config` command. During installation, you will be prompted to choose which profile you would like to use. If only one account is configured, it will be considered the _default_ profile.
---
### Step 2: Install pre-requisites
For all Users:
- Latest version of Python from [https://python.org](https://python.org) (minimum 3.9+)
- Silicon Labs [CP210x USB to UART Bridge drivers](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers). Under Windows, once you plug in an AWS EduKit device, it should automatically install this driver. You will have to download the above driver and manually install it if it fails. Under MacOS, you need to download and install it manually.
Additionally, for Administrators:
- Docker Desktop: [https://docs.docker.com/desktop/](https://docs.docker.com/desktop/)
Installing these may require other dependencies on Windows or Mac. Once installed, the system may need to be rebooted.
### Step 3: Install SimpleIOT CLI
Open a powershell (Windows) or terminal (Mac) terminal window, then run:
```
pip install simpleiot-cli
```
Once installed, you can test the command-line interface:
```
% iot help
Usage: iot [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
Commands:
auth User Authentication
cloud Cloud backend provisioning
data Data set and retrieve
datatype Model DataType management
device Device provisioning
firmware Generate sample source
location Location management
model Manage Models
project Project management
team Team management (CLI only)
template Project Template management
toolchain Project Template management
twin Manage Digital 3D Twin files
update OTA Firmware Updates
```
### Uninstalling
To uninstall `simpleiot-cli` use the `pip` command:
```
% pip uninstall simpleiot-cli
```
Note that this only removes the CLI itself. If you have installed other items, like the compiler toolchain or actual projects, those must be removed before reinstalling.
If the CLI was used to create a cloud backend, it should be deleted via:
```
% iot cloud uninstall
```
Be careful if you have allowed others access to this team. This command will permanently delete the entire backend infrastructure, including user accounts and all provisioned AWS IOT Things and certificates.
### Troubleshooting
#### Python missing or out-of-date
Once `simpleiot-cli` is installed, you can verify that it is operational by running the `iot --help` command. If this returns an error, your version of Python may be missing or not up-to-date. To verify, open a **Powershell** or **Terminal** window and enter:
```
% python --version
Python 3.9.4
```
You should get a version higher than 3.9. If not, please update or install the latest version of Python. If the _python_ command is not found, re-run the Python installer and check the box that asks if it should be added to the PATH.
#### Unable to deploy the backend
This could be due to a variety of reasons, including:
- AWS CLI is not installed correctly.
- `aws configure` has not been run properly.
- AWS configuration settings in `~/.aws` are not valid.
- The account does not have sufficient IAM privileges to create the components for the SimpleIOT platform.
Please check and remedy these problems before proceeding.
## License
This project is licensed under the Apache-2.0 License.
Raw data
{
"_id": null,
"home_page": "http://github.com/awslabs/simpleiot-cli",
"name": "simpleiot-cli",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "simpleiot,simpleiot-cli,iot,aws,awslabs,cli",
"author": "Ramin Firoozye",
"author_email": "framin@amazon.com",
"download_url": "https://files.pythonhosted.org/packages/7b/91/f902ccfedaec9b672301711c8bf8490ee58aa82d1c73cf1028ee56b57091/simpleiot-cli-1.0.180.tar.gz",
"platform": null,
"description": "# SimpleIOT Command-Line-Interface (CLI)\n\n\n\n\n\n\n\n\n\nThis is the command-line-interface (CLI) for the [SimpleIOT](https://simpleiot.net) framework.\n\nSimpleIOT abstracts out IoT device connectivity and hides the underlying details so you can focus on your application's unique features.\n\n## Basic Concepts\n\n\n\nIn the SimpleIOT world, an installation supports the following concepts:\n\n- **team**: A single installation of SimpleIOT in the cloud. This is mainly relevant to using the Command-Line-Interface (CLI) tool.\n- **project**: Each backend supports one or more _Projects_.\n- **Model**: A _Model_ describes a device's capabilities. For example, what data it likes to exchange with the cloud, whether an end-node or a gateway device, what features it supports (i.e., storage, encryption, or AI/ML.), and how it communicates with the cloud.\n- **DataType**: A _DataType_ is a single named value that can be exchanged between a device and the cloud. A _Model_ typically has one or more _DataTypes_ associated with it.\n- **Device**: A _Device_ represents a single instance of a _Model_. Each device has a unique identification via its _serial_number_.\n- **Data**: A _Data_ element is an instance of a _DataType_ associated with a single _Device_. For example, if a _Model_ defines a _DataType_ named `pressure`, each unique _Device_ will have its own instance of `pressure`. You can get/set values associated with each _Device_ instance by name.\n\n_Data_ elements are bi-directional so that updates go from the devices to or from the cloud back to the device. It is up to the firmware to handle what to do with values received from the cloud.\n\n## Dual-use\n\nThis CLI can be used by both backend administrators as well as end-users.\n\nAs an Administrator, you need to:\n- Have one or more AWS accounts with IAM Administrative privileges.\n- Configure a profile for each account by running the `aws configure` command.\n\nWith this CLI, you can:\n\n- Create a private, serverless IOT backend on AWS.\n- Create one or more Teams (individual backend installations on each account).\n- Securely invite users to join the team (including support for bulk emailing).\n- Remove users from a Team.\n\nAs a User, you can:\n\n- Join a Team to which you have been invited.\n- Install an Arduino command-line toolchain with support for ESP32 processors.\n- Create and manage Projects, Models, DataTypes, and Devices.\n- Simulate and monitor remote device values via `set` and `get` operations.\n- Provision and deploy secure IOT device instances.\n- Generate firmware source code based on templates (currently supporting the ESP32/Arduino toolchain).\n- Compile and flash firmware to an M5Stack ESP-32 device via USB cable.\n- Monitor MQTT traffic sent to/from AWS IOT.\n\nThe CLI can be installed on systems running at least Windows 10 or MacOS Big Sur. It requires pre-installation of **Python** (Users + Administrators) and **Docker Desktop** (Administrators).\n\n## Installation\n\nAdministrators can install and remove the backend cloud for a SimpleIOT deployment. They can also invite new users to the _Team_ so they can interact with an existing installation.\n\n### Step 1: AWS CLI\n\nBefore creating a backend, you need to make sure you have an AWS account created and a user account configured via the [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html).\n\n---\n**NOTE**\n\nThis will require downloading and setting up an account with AWS IAM Administrative Privileges. If you are not allowed to have AWS admin privileges, a list of fine-grain IAM privileges will be released along with the SimpleIOT back-end sources. These can be used to create only the privileges needed by the system.\n\nThis is a one-time operation. Once configured, you may proceed with the following steps. You can configure multiple named profiles using the `aws config` command. During installation, you will be prompted to choose which profile you would like to use. If only one account is configured, it will be considered the _default_ profile.\n\n---\n\n### Step 2: Install pre-requisites\n\nFor all Users:\n\n- Latest version of Python from [https://python.org](https://python.org) (minimum 3.9+)\n- Silicon Labs [CP210x USB to UART Bridge drivers](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers). Under Windows, once you plug in an AWS EduKit device, it should automatically install this driver. You will have to download the above driver and manually install it if it fails. Under MacOS, you need to download and install it manually.\n\nAdditionally, for Administrators:\n\n- Docker Desktop: [https://docs.docker.com/desktop/](https://docs.docker.com/desktop/)\n\nInstalling these may require other dependencies on Windows or Mac. Once installed, the system may need to be rebooted.\n\n### Step 3: Install SimpleIOT CLI\n\nOpen a powershell (Windows) or terminal (Mac) terminal window, then run:\n\n```\npip install simpleiot-cli\n```\n\nOnce installed, you can test the command-line interface:\n\n```\n% iot help\nUsage: iot [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n auth User Authentication\n cloud Cloud backend provisioning\n data Data set and retrieve\n datatype Model DataType management\n device Device provisioning\n firmware Generate sample source\n location Location management\n model Manage Models\n project Project management\n team Team management (CLI only)\n template Project Template management\n toolchain Project Template management\n twin Manage Digital 3D Twin files\n update OTA Firmware Updates\n```\n\n### Uninstalling\n\nTo uninstall `simpleiot-cli` use the `pip` command:\n\n```\n% pip uninstall simpleiot-cli\n```\n\nNote that this only removes the CLI itself. If you have installed other items, like the compiler toolchain or actual projects, those must be removed before reinstalling.\n\nIf the CLI was used to create a cloud backend, it should be deleted via:\n\n```\n% iot cloud uninstall\n```\n\nBe careful if you have allowed others access to this team. This command will permanently delete the entire backend infrastructure, including user accounts and all provisioned AWS IOT Things and certificates.\n\n### Troubleshooting\n\n#### Python missing or out-of-date\n\nOnce `simpleiot-cli` is installed, you can verify that it is operational by running the `iot --help` command. If this returns an error, your version of Python may be missing or not up-to-date. To verify, open a **Powershell** or **Terminal** window and enter:\n\n```\n% python --version\nPython 3.9.4\n```\n\nYou should get a version higher than 3.9. If not, please update or install the latest version of Python. If the _python_ command is not found, re-run the Python installer and check the box that asks if it should be added to the PATH.\n\n#### Unable to deploy the backend\n\nThis could be due to a variety of reasons, including:\n\n- AWS CLI is not installed correctly.\n- `aws configure` has not been run properly.\n- AWS configuration settings in `~/.aws` are not valid.\n- The account does not have sufficient IAM privileges to create the components for the SimpleIOT platform.\n\nPlease check and remedy these problems before proceeding.\n\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "SimpleIOT command line interface",
"version": "1.0.180",
"split_keywords": [
"simpleiot",
"simpleiot-cli",
"iot",
"aws",
"awslabs",
"cli"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "94e9e2b7e659080cf80139b420a5d62e4357c382b62cbb7ed2bbd15a2a4286a1",
"md5": "fb93e5eb1f8a13282c881dd7d4da460c",
"sha256": "29571ebb2245ce9c2b176696c0cff69b62f39fcbe31fb87ef277e06c07ff17e9"
},
"downloads": -1,
"filename": "simpleiot_cli-1.0.180-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fb93e5eb1f8a13282c881dd7d4da460c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 709009,
"upload_time": "2023-02-01T01:09:36",
"upload_time_iso_8601": "2023-02-01T01:09:36.590700Z",
"url": "https://files.pythonhosted.org/packages/94/e9/e2b7e659080cf80139b420a5d62e4357c382b62cbb7ed2bbd15a2a4286a1/simpleiot_cli-1.0.180-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7b91f902ccfedaec9b672301711c8bf8490ee58aa82d1c73cf1028ee56b57091",
"md5": "08fa901897bb57bb170be1ea2f529efd",
"sha256": "1fd968463d32fa348fa34df88bdd05eaa25210c0867e9118f770aeefceee0845"
},
"downloads": -1,
"filename": "simpleiot-cli-1.0.180.tar.gz",
"has_sig": false,
"md5_digest": "08fa901897bb57bb170be1ea2f529efd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 681963,
"upload_time": "2023-02-01T01:09:38",
"upload_time_iso_8601": "2023-02-01T01:09:38.575238Z",
"url": "https://files.pythonhosted.org/packages/7b/91/f902ccfedaec9b672301711c8bf8490ee58aa82d1c73cf1028ee56b57091/simpleiot-cli-1.0.180.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-01 01:09:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "awslabs",
"github_project": "simpleiot-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "simpleiot-cli"
}
JSON
