Administrator
If you haven't already set up an AWS account, please do so now. To proceed, you should have an AWS Profile configured on your machine.
We will be using the SimpleIOT Command-Line-Interface (CLI) to:
- Set up the back-end
- Invite team members to join the Team
Installation pre-requisites
For all Users:
- Latest version of Python from https://python.org (minimum 3.9+)
- Docker 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.
Install SimpleIOT CLI
Once you have the above set up, installing the CLI on your system is straightforward.
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 back-end 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
Install the Back-end
You are ready to install the back-end if you have already set up your AWS Account (or added a profile to your ~/.aws directory).
This step will download a pre-built Docker image to your system and invoke it. The image has all the pre-requisites needed to configure a SimpleIOT stack. It will ask you a few questions, then start the process.
This step usually takes between 20-30 minutes. Please do not interrupt it, otherwise the system will be in a half-baked stage.
If you encounter any errors, make sure you run iot cloud uninstall to clear out the debris before trying again.
Do NOT run the installer while on a VPN!
If this happens, the final database setup stage may freeze when trying to securely connect to the database. If this happens, Ctrl-C out, uninstall (see above), and try installing again, this time without the VPN connection.
To start, open a terminal window and run:
iot cloud install
A series of log messages from Docker will show that the container is getting downloaded. Once ready, you will be asked a few questions to bootstrap the process:
None of the information you provide is sent anywhere outside your account or system. The questions are there only so you can distinguish one of your Teams from another.
The questions are:
- Choose AWS profile:
- If you have more than one AWS profile on your machine, you will be shown a list of profiles. Select one using the arrow keys and press ENTER.
- If you only have a single default profile, that will be used, and you will not be prompted.
- If you do not have ANY accounts configured, the installer will ask you to enter your AWS Secret Key and ID (from your account setup).
- Organization Name: Choose a name that represents your organization. If you are a solo developer, enter your name. Or if you have grand ambitions: "{enter name} Enterprises" or _"Intergalactic {{enter name}}." Go ahead, Think Big!
- Administrator Email: This is your email. Make sure it's a valid one. You will be e-mailed an acknowledgment once the system is set up. The information is not transmitted anywhere outside your own account.
- Dashboard Admin Password: The system generates a difficult-to-guess password. You can change it if you want, but it must comply with the Cognito minimum password requirements. You may also want to copy and save this password someplace safe. You will need this to log in with the CLI.
- Short Team Name: This is the name you will use to refer to the Team when accessing the back-end. Even if you will only ever have a single Team, you still need to have a team name defined. The system will suggest a name based on your AWS profile (default if you only have one AWS account configured).
The name of the team will be used to create a settings directory. The name should be short, without any spaces, and consist of characters allowed as directory names. i.e., characters, numbers, and a hyphen.
No punctuation or non-ASCII characters should be used. Seriously. Keep it boring.
Once you have answered these questions, you will be asked to confirm and hit ENTER. Once the process starts, you can watch it go or take a 20-30m break.
If the account has insufficient AIM privileges or something goes wrong, the system will try to rewind and delete what is created. However, you still have to run the following to clean out extra resources (like SSH keys, S3 buckets, etc.):
iot cloud uninstall
Installer stages
The installer process has three stages:
- Bootstrap
- Deploy
- Database setup
When you run the iot cloud install step, it runs all three back-to-back. Once done, you should see a message indicating success. If you see that, you can proceed to install the toolchain.
If you get any errors, check the Troubleshooting section, uninstall, fix the problem, and start again. You can re-use the same answers as before, except when you run the installer, a new password is auto-generated.
Logging in
As an administrator, you can log into the system you just installed using the credentials:
Username: admin
Password: {password generated during installation}
If you forget or misplace the admin password, you can log into the AWS Console (make sure you set it to the same region as the AWS profile you configured).
Then visit the AWS Systems Manager (SSM) > Parameter Store, click on the /simpleiot/{team-name}/admin_password key and click on the Show link.
Inviting Team Members
Once the back-end is installed, you can invite others to join your team. Only Administrators are allowed to invite others to join.
Inviting others is a three-step process:
Invoke the command to invite someone. This will require entering a valid username and email for the invitee. Next, a secure invitation file and a private key are generated. The administrator must get these to the recipient (via email, text, or any other messaging app).
The recipient will use the invitation file and the key to accept and join the team. They will be prompted to enter a password for that account.
Users can now log in with their username and password.
The invitation system uses the Amazon Cognito user provisioning workflow. If there are any issues, you can delete the user via the SimpleIOT CLI or manually remove the account from the Amazon Cognito Console.
Single-user Invitation
To invite individual users, you can use:
iot team invite --username={team-member username} --email="{recipient email}"
This will show the name of an invitation file, ending with .simpleiot and saved in the current directory, as well as a unique Invite Key value.
Both these items need to be securely sent to an invitee. The mode of transmission is up to you.
Suppose the recipient cannot finish the process and join using these credentials. In that case, you can use the following command to remove the user's account from Cognito:
iot team leave --username={team-member username}
Be careful when using this command on an active user.
Once removed, the user can no longer log into the SimpleIOT system. All the files stored on their own machine, as well as projects, models, and devices they have created, will remain untouched. But they will no longer be able to log in via the CLI to manage them.
You will need to send them a new Team invitation to allow them to log in again.
Shared Environment
The SimpleIOT back-end is an open, shared environment designed for development and collaboration. This means all registered users can access all projects, models, and provisioned devices.
It is recommended that each person create a project prefixed with a unique name or initials to prevent accidentally accessing someone else's work.