Construct an environment friendly growth surroundings for AWS IoT Greengrass

This submit exhibits you tips on how to arrange a clear and environment friendly growth surroundings for AWS IoT Greengrass. With this surroundings you may quickly iterate in your concepts and automate your course of to construct edge compute techniques from scratch. Constructing a repeatable growth surroundings for edge techniques can take a very long time. These instruments will scale back the period of time it takes you to get began and offer you a base to construct your manufacturing purposes.

Overview

The Ubuntu 20.04 primarily based digital machine that you just construct can:

• Begin from scratch in minutes
• Hook up with actual USB units
• Work together with AWS companies utilizing your AWS credentials
• Seize pictures from a USB digital camera and save them to your host system
• Run AWS IoT Greengrass with a single part

We are going to use GreenEyes to implement a digital video recorder (DVR) platform. This platform makes use of a number of AWS companies for edge computing, like AWS IoT Greengrass and FreeRTOS.

Conditions

All working techniques

You need to have the AWS Command Line Interface v2 put in and have credentials arrange within the default location $HOME/.aws. The venture will deliver these credentials into the VM so you may work together with AWS straight away.

MacOS and Linux

You need to have git and bash put in. All current variations of Linux and MacOS ought to have these put in already.

Home windows

You want a shell that may run bash scripts. We advocate Git Bash which comes with Git for Home windows. You probably have Home windows Terminal put in be sure to allow the Git Bash profile for Home windows Terminal in the course of the Git for Home windows set up course of. You possibly can then choose Git Bash from the Home windows Terminal drop-down as an alternative of utilizing the default terminal.

Instruments overview

Virtualization with VirtualBox

You want a virtualization platform. It’s attainable to do quite a bit in containers and many individuals desire them. On this case although you’ll want to load some kernel modules and entry USB units which isn’t all the time attainable in container primarily based techniques. Moreover, one objective is to make the expertise to be as related as attainable throughout Home windows, MacOS, and Linux.

The virtualization platform you’ll use is VirtualBox. VirtualBox is cross-platform, free, and helps USB passthrough. Assessments present that the efficiency is ample for single stream video seize and processing.

Automated builds with Vagrant

You want instruments to make establishing digital machines as simple as attainable. With the ability to begin, cease, and rebuild machines on the command-line will save time and keep away from handbook configuration steps.

Vagrant automates constructing and configuring your VMs. Vagrant is a cross-platform, and might use VirtualBox as a back-end which helps USB passthrough.

Vagrant may also share information between the host and the visitor working system. Outcomes present up instantly and you may monitor your system proper from the host.

Digicam choice

USB cameras usually are not all equal. Fortunately all UVC webcams ought to be equal. UVC stands for USB video class. This can be a customary that gives a normal interface to seize video. Some webcams don’t help this customary and require further software program.

For simplicity, this submit limits the scope to UVC webcams solely. This technique will be tailored to make use of different cameras however that’s past the scope of this submit.

A dependable UVC digital camera that you would be able to begin with is the Logitech C922. It may be discovered on-line at numerous shops both new or used. There are additionally some variations of the C922 just like the C920s, and the C920e. These ought to work as properly and we’ll add data to the documentation to point once we’ve examined them to make sure.

So long as the digital camera you’re utilizing is on the UVC machine checklist or claims to help UVC it ought to work. Nevertheless, the default code makes use of the Logitech C922. In case you use one other digital camera there are some modifications you’ll must make to the configuration. When you arrange VirtualBox and Vagrant you may take a look at the digital camera and validate your setup.

Set up instruments

VirtualBox

VirtualBox is among the best dependencies so that you can arrange. You possibly can go to the VirtualBox wiki’s downloads web page and click on on whichever VirtualBox platform corresponds to the platform you’ll be operating on. You will want administrator entry to put in VirtualBox so be sure to use a pc that you’ve got full management over.

This submit relies on VirtualBox 6.1.32 on MacOS. In case you are on a unique platform or are utilizing a more recent model among the screens could also be barely completely different. In case you run into points be happy to share screenshots with us by submitting a difficulty in our GreenEyes repo.

VirtualBox extension pack

You additionally want so as to add help for USB 3.x in order that your USB digital camera will work appropriately. To get help for USB 3.x you’ll want to set up the Oracle VM VirtualBox Extension Pack which will be discovered on the identical obtain web page you downloaded VirtualBox from.

NOTE: If you have already got the VirtualBox GUI open while you set up the extension pack you have to to shut and re-open it.

Vagrant

Head over to the Vagrant downloads web page and set up the construct applicable on your working system. Some working techniques can set up Vagrant with a bundle supervisor (Homebrew, apt, and so on.), some require downloading a binary construct.

Code

GreenEyes repository overview

The GreenEyes repository accommodates scripts and documentation for every submit on this sequence. Scripts that are supposed to be run on the host are within the greeneyes/blog-posts/001/host listing. Scripts that are supposed to be run on the visitor are within the greeneyes/blog-posts/001/visitor listing.

Within the host listing for this submit there may be solely a Vagrantfile. There are not any further scripts to run.

Cloning the GreenEyes repository

Navigate in your shell to a listing the place you’d prefer to retailer the repository and clone it like this:

git clone https://github.com/awslabs/greeneyes/

Setting

Initializing the surroundings

In case your system is operating MacOS or Linux then you might be able to go and all the dependencies are current.

In case your system is operating Home windows then Hyper-V must be enabled if it isn’t already. Allow Hyper-V in an administrator terminal session with this command:

powershell Allow-WindowsOptionalFeature -On-line -FeatureName Microsoft-Hyper-V -All

Beginning the VM

NOTE: Any time you employ a vagrant command you have to be within the greeneyes/blog-posts/001/host listing for this weblog submit.

Run vagrant up within the greeneyes/blog-posts/001/host listing. When this completes the VM is bootstrapped with the required kernel modules and USB 3.0 shall be enabled. This command can take some time relying on a lot of components together with your Web bandwidth, CPU, RAM, and so on. On the low finish you may count on about three and a half minutes.

If the VM fails to provision

It’s attainable for the VM to fail to run the provisioning steps because of short-term community connectivity points. When this occurs an error is printed that appears like this:

The SSH command responded with a non-zero exit standing. Vagrant
assumes that this implies the command failed. The output for this command
ought to be within the log above. Please learn the output to find out what
went mistaken.

In case you see this message, run vagrant destroy to delete the VM after which run vagrant up once more. In any other case the VM is not going to have the right dependencies and configuration to proceed.

Validating USB 3.0 help

Run vagrant ssh and also you’ll be dropped right into a shell within the VM. To confirm that USB help is working run this command:

dmesg | grep -i xhci

The output ought to comprise some strains much like this:

[    1.287174] usb usb3: Product: xHCI Host Controller
[    1.287928] usb usb3: Producer: Linux 5.4.0-107-generic xhci-hcd

If these strains are there (there could also be extra as properly) then USB 3.0 help is working. Exit the shell by operating the exit command.

Now run vagrant halt to cease the VM so you may arrange USB passthrough on your webcam.

Configuring USB passthrough

NOTE: The default Vagrant configuration configures USB 3.0 passthrough and provides a tool filter for the Logitech C922. You possibly can skip this part in case you are utilizing the Logitech C922. In any other case, comply with this part so as to add a tool filter on your webcam.

Plug your USB digital camera into your laptop. You will want to pick it from an inventory on one of many subsequent screens and it’s higher to have it able to go as an alternative of reloading the interface.

Begin the VirtualBox GUI. The interface ought to seem like this:

Now select the “Settings”, then “Ports”, after which “USB”.

The display ought to have “Allow USB Controller” checked, “USB 3.0 (xHCI) Controller) chosen, an empty “USB Machine Filters” checklist, and two USB icons on the appropriate aspect.

Select the icon with the USB cable and the plus signal as proven right here:

Choose the digital camera you linked from the checklist and it’ll present up within the checklist like this:

Select “OK” and you might be able to restart your occasion and take a look at it.

Testing USB passthrough

It’s time to get into your VM and attempt to seize an image out of your digital camera.

Run vagrant up to start out the VM. Open a terminal within the VM by operating vagrant ssh.

Within the shell run a seize take a look at with this command:

~/visitor/bash-capture-loop/capture-one

The output from the seize take a look at is only a single < character if it was profitable. It’s best to see a brand new .jpg within the ~/shared listing. The identify of the file shall be a quantity that represents the UNIX epoch time at which the picture was captured. That picture is a single body out of your digital camera. You possibly can view this on the host’s shared listing and confirm the picture is legitimate. Vagrant supplies a shared listing function that maps ~/shared on the VM to shared in your host.

Testing your AWS credentials

Open a terminal within the VM, when you haven’t already, by operating vagrant ssh. Within the terminal run this command:

aws sts get-caller-identity

In case your credentials are loaded appropriately it is best to see output like this:

{
  "UserId": "AXXXXXXXXXXXXXXXXXXXXX",
  "Account": "123456789012",
  "Arn": "arn:aws:iam::123456789012:consumer/me"
}

In case your credentials are lacking you will note output like this:

Unable to find credentials. You possibly can configure credentials by operating "aws configure".

Validate your AWS credentials by making an attempt this identical command in your host system. If it doesn’t work assessment the Configuration fundamentals documentation and set your credentials up once more if obligatory.

Putting in AWS IoT Greengrass

Open a terminal within the VM, when you haven’t already, by operating vagrant ssh. Within the terminal run this command:

gg-install

This script will obtain the newest model of the AWS IoT Greengrass Nucleus and provision AWS IoT Greengrass in your VM. When it completes it is best to see a message like this:

Efficiently arrange Nucleus as a system service
Greengrass S3 entry coverage created [...] for bucket [...]

You possibly can monitor all of the AWS IoT Greengrass logs by operating:

gg-logs

The gg-logs script will even choose up new log information when they’re created so that you don’t must restart it to see what a part is doing.

NOTE: To exit the gg-logs script press CTRL and backslash (CTRL+).

Deploy the Bash Seize Loop part

The capture-one program you ran earlier than is definitely a Bash script. There’s one other program referred to as capture-loop that wraps capture-one in a loop, captures a picture as soon as per second, and retains the final 10 pictures within the shared listing.

capture-loop can also be a Bash script. It was written as a Bash script to reveal that elements will be written in any language you want.

To deploy the Bash Seize Loop part first be sure to have a terminal open that’s monitoring the logs with the gg-logs command you ran earlier than. Then open a brand new terminal and run this command:

gg-cloud-deploy

After a number of seconds it is best to see log messages that seem like this:

2022-04-29T15:31:37.495Z [WARN] (Copier) greeneyes.BashCaptureLoop: stderr. <. {scriptName=companies.greeneyes.BashCaptureLoop.lifecycle.Run, serviceName=greeneyes.BashCaptureLoop, currentState=RUNNING}

This means that the Bash Seize Loop is operating. You must also see pictures displaying up in your host laptop within the shared listing.

Understanding the cloud deploy command

The gg-cloud-deploy command makes use of the AWS IoT Greengrass Improvement Package Command-Line Interface, also called GDK, to construct, publish, and deploy any AWS IoT Greengrass elements within the visitor listing for you routinely utilizing the AWS IoT Greengrass cloud companies.

It does the next:

• Validates that the AWS IoT Greengrass CLI from the dev instruments bundle is put in. That is carried out within the preliminary deployment by the gg-install script with the --deploy-dev-tools true possibility.
• Locates any elements within the visitor listing which are suitable with GDK. It does this by in search of a gdk-config.json or gdk-config.json.template file.
• If gdk-config.json is current however not gdk-config.json.template then it makes use of gdk-config.json with out making any modifications. This permits it to help elements that aren’t a part of this submit.
• If there’s a gdk-config.json.template file it populates the any placeholder values after which overwrites gdk-config.json with the up to date data. This makes it simpler to reuse a part’s configuration throughout a number of AWS IoT Greengrass VMs with out having to replace the Amazon Easy Storage Service (S3) bucket every time.
• Builds every part with the gdk part construct command. This creates a ZIP archive of the elements that may be printed to S3.
• Publishes every part with the gdk part publish command. This uploads the ZIP archive to S3.
• Deploys the newest model of every part with gg-cli deployment create. To get the newest model it queries your privately deployed Bash Seize Loop part with the AWS CLI.

Extra comfort scripts

Along with gg-cloud-deploy and gg-install there are a number of comfort scripts within the greengrass listing. By default the greengrass listing is within the vagrant consumer’s PATH so you should use these instruments from anyplace inside the VM. The opposite scripts that you should use are:

• gg-cli – Runs the AWS IoT Greengrass CLI
• gg-names – Prints the names which are used to configure and handle the present VM’s occasion of AWS IoT Greengrass
• gg-password – Prints the username and password data for the AWS IoT Greengrass native developer console.
• gg-start – Begins AWS IoT Greengrass utilizing systemd
• gg-status – Exhibits the AWS IoT Greengrass standing utilizing systemd
• gg-stop – Stops AWS IoT Greengrass utilizing systemd

Cleanup

The cleanup course of is to take away the AWS sources that the scripts created after which to destroy the Vagrant VM.

The sources created by putting in AWS IoT Greengrass and operating the cloud deploy script are:

• One S3 bucket for AWS IoT Greengrass deployment artifacts
• One S3 object per deploy
• One factor group
• One AWS IoT certificates
• Two AWS IoT insurance policies
  • One for the token change service to get AWS Safety Token Service (STS) credentials from the AWS Identification and Entry Administration (IAM) position utilizing the AWS IoT Greengrass Core’s certificates
  • One for the AWS IoT Greengrass core to entry AWS IoT and AWS IoT Greengrass companies
• One IAM position that may be assumed with the AWS IoT Greengrass core certificates
• Two IAM insurance policies
  • One default coverage created by AWS IoT Greengrass to permit it to ship logs to CloudWatch Logs
  • One coverage created by gg-install to permit AWS IoT Greengrass to entry the S3 bucket gg-cloud-deploy creates for deployment artifacts
• One AWS IoT position alias to level the AWS IoT Credentials Supplier service to the IAM position
• One AWS IoT Greengrass core machine
• One AWS IoT factor

In case you would like to delete these sources manually you may run the gg-names script to search out the names of the sources.

To do an automatic cleanup you should use the Superfluid software. Obtain the software and run this command:

superfluid greeneyes cleanup THING_NAME

Substitute THING_NAME with the identify of the factor reported by gg-names. This queries AWS for the factor, finds the sources associated to that factor for this submit sequence, and cleans them up routinely for you. It first shows what sources it needs to wash up, prompts for affirmation, after which cleans the sources up. It additionally logs if operations failed so the sources will be cleaned up later.

Recap

On this submit, you arrange an AWS IoT Greengrass part growth surroundings. Utilizing an Ubuntu VM and Vagrant, you deployed an AWS IoT Greengrass part that may seize pictures from a digital camera. The VM has a USB passthrough to connect with a USB internet digital camera. You possibly can modify the code for the part contained in the VM and redeploy it to see your modifications instantly.

Authors

Tim Mattison is a Principal Technologist within the IoT Ecosystem Companies group at Amazon Net Companies. Initially a firmware engineer, he has moved up and down the stack from Linux kernel drivers to GUIs. He enjoys the challenges concerned with eradicating friction for builders and is all the time looking out for methods to enhance. He primarily works on AWS IoT content material that exhibits tips on how to weave a number of companies collectively throughout the product lifecycle from fast prototyping to manufacturing.

Nenad Ilic is an Web of Issues specialist with greater than a decade of expertise. At present, he works as a Senior Developer Advocate at Amazon Net Companies, the place he helps builders throughout the business speed up their Edge Software program Improvement and builds infrastructure so different builders can categorical themselves via code. In his free time he likes to experiment with electrical skateboards and share his expertise with the broader neighborhood.