pozetron-cli 0.8.0
Pozetron command-line interface. The developer interface for the Pozetron IoT Cloud.
License: Apache License 2.0
Keywords: pozetron,IoT,MicroPython

[Pozetron](https://www.pozetron.com/) is the next evolution of development tools for the devices which make up the Internet of Things.

This package provides a single unified command line interface for developers to interact with the Pozetron Cloud.

The pozetron-cli package is tested on Python versions:

* 3.5
* 3.6
* 3.7
* 3.8

Pozetron enables you to write MicroPython code which will run on small, cost efficient, low power modules such as the ESP8266 or ESP32 from
[Espressif Systems](https://espressif.com/).

## Getting an Account

You can register for an account at [https://registration.apps.pozetron.com/registration](https://registration.apps.pozetron.com/registration).

Once you have registered, you will receive an email like the following:
``` text
Hi there!

Thanks for being an early adopter of Pozetron!

To authenticate to the cloud, download your identity file from https://registration.apps.pozetron.com/registration/id-pozetron/

Move this file to `~/.pozetron/id_pozetron` if you are on Linux or macOS.
If you are on Windows, move this file to `C:\Users\%USERNAME%\.pozetron\id_pozetron`.

Once you have this file you can continue with the installation of the pozetron-cli by using pip to install it like so:

$ pip install pozetron-cli

Once you have your ~/.pozetron/id_pozetron configured and the pozetron-cli command line tool installed, you can follow our tutorial to get your "hello world" up and running.

https://www.pozetron.com/tutorial/getting-started/
https://www.pozetron.com/tutorial/getting-started-esp8266/

Note: By downloading or using our software, you accept the terms of service https://www.pozetron.com/legal/tos.html and privacy policy https://www.pozetron.com/legal/privacy.html
```

As the email instructs, you need to create a file which will contain your credentials for the CLI. The default location is in `~/.pozetron/` but this can be overridden using the `POZETRON_DIR` environment variable.

## Installing the Command line

Obtaining the Command Line Interface (CLI) is simply a matter of using Python's `pip` to install it.

```bash
$ pip install pozetron-cli
```

## Provisioning your first device

After your credentials set up, you'll want to take your first steps with the command line client. let's do that now by requesting a new device be provisioned.
This process will take a secret that you supply and register it with the cloud. In return you will receive a device ID, in the form of a device address, and a
key ID. These three items will be copied to your device and will be used to authenticate the device to the cloud.

``` bash
$ poze.py device provision -k DEADBEEF
usage: poze.py device provision [-h] -k KEY
poze.py device provision: error: argument -k/--key: Enter a valid hash (64 characters).
May we suggest: 7ed951450f7bef3f5a359464bbf430a88af316aef3dae5097faf364cae323056
$ poze.py device provision -k 7ed951450f7bef3f5a359464bbf430a88af316aef3dae5097faf364cae323056
a77eed66d15a3b3cba76573376695729bf7bce33d8e0997bfd8399f993fca4f8@pozetrondevices.com
36d43af16bfde6575efff2878c9b081b71bc3d5f3105cbfbead8ed62770d267d
```

## Uploading a module

After you have a device, you'll want to have something ready to deploy to that device. You can upload modules or packages to the cloud to be deployed.
To keep things simple we'll start off by uploading a single module.

``` python3
def say_hello():
    log('Hello World!')
```

``` bash
$ poze.py script upload -f hello.py -m hello
f2fefab13050f4e5b0e580ba9b5b4e9f88ffc633581b5fbeaf3da231477258e5
```

## Adding tags

Pozetron uses hashes to identify devices, modules and packages. These are very easy for a computer to work with but are not the most user friendly.
To make it easier we'll add a tag to the module we just uploaded.

``` bash
$ poze.py tag add f2fefab13050f4e5b0e580ba9b5b4e9f88ffc633581b5fbeaf3da231477258e5 hello:v1
hello:v1 -> f2fefab13050f4e5b0e580ba9b5b4e9f88ffc633581b5fbeaf3da231477258e5
```

Now that we have a tag for our module, we should create a tag to use for our device.

``` bash
$ poze.py tag add a77eed66d15a3b3cba76573376695729bf7bce33d8e0997bfd8399f993fca4f8 tutorial
tutorial -> a77eed66d15a3b3cba76573376695729bf7bce33d8e0997bfd8399f993fca4f8
```

We can now use these tags whenever we would use the matching hashes. Tags are synced to the cloud so you will also see them on https://devices.apps.pozetron.com/.

## Deploying our module

Once we have the credentials, we will want to program our device so that we can deploy our new module.
After following the
[Getting Started with Pozetron on the ESP8266](https://www.pozetron.com/tutorial/getting-started-esp8266) or [Getting Started with Pozetron on the ESP32](https://www.pozetron.com/tutorial/getting-started-esp32) tutorial you will have a device connected to your network and ready to use.

Deploying a new module to a device is as easy as:

``` bash
$ poze.py script deploy -s hello:v1 -d tutorial
```

Now that we have a module on the device, let's set up the special `main.py` module which is launched when the device starts.

``` python3
import hello
import time
import sys

# This is a pointer to the module object instance itself. We use this so we can reference module level variables
# inside our main_loop(). This is more memory efficient than using a class.
main = sys.modules[__name__]
######################################################################################################
#                                            MAIN LOOP                                               #
######################################################################################################

# The only things that should go in the main loop are those which you want to execute hundreds
# of thousands of times. Anything that you want to do once, like assign a constant string to a
# variable should occur above for performance reasons. Also, anything whose value you want to
# share with your 'epilog'.

# The epilog runs if the main_loop ever exits. The main_loop should exit regularly to provide
# an opportunity for the Pozetron functionality to run.

def main_loop():
    hello.say_hello()
    log('We came, we saw, we said hello')
    time.sleep(10)
```

Let's upload this module and deploy it to the device.
```bash
$ poze.py script deploy -s `poze.py script upload -f main.py -m main` -d tutorial
```

Success! Now that we have our module on the device, let's restart it so that it picks up the new modules.

``` bash
$ poze.py device reboot -d tutorial
```

## Logs

So now we have a device, connected to the Internet and with our module deployed. Let's get the logs from this device to see our handy work.

``` bash
$ poze.py device logs -d tutorial
2017-05-12T06:39:44.210265 Hello World!
2017-05-12T06:39:44.211335 We came, we saw, we said hello
```

So there you have it, we've set up our account credentials, provisioned our device, deployed our first code to the device, and successfully retrieved the logs for our device, from the cloud. All without even needing to be on the same continent as our device.

Whether you are working with devices near you or deployed in some remote location, you can always keep them up to date, diagnose problems or push new features without ever plugging them into a laptop again.

If you would like to get some inspiration for your next project check out our blog post [https://www.pozetron.com/blog/jedi-lights/](https://www.pozetron.com/blog/jedi-lights/)