Metadata-Version: 2.0
Name: pozetron-cli
Version: 0.4.2
Summary: Pozetron command-line interface. The developer interface for the Pozetron IoT Cloud.
Home-page: https://www.pozetron.com
Author: Pozetron Inc
Author-email: hello@pozetroninc.com
License: Apache License 2.0
Description-Content-Type: UNKNOWN
Keywords: pozetron,IoT,MicroPython
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Requires-Dist: httpsig-pure-hmac (==1.1.2)
Requires-Dist: pydicti (==0.0.6)
Requires-Dist: python-dateutil (==2.6.1)
Requires-Dist: pytz (==2016.10)
Requires-Dist: requests (==2.11.1)
Requires-Dist: six (==1.10.0)

`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:

-  2.7
-  3.3
-  3.4
-  3.5
-  3.6

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.

Once you have registered, you will receive an email like the following:

.. code:: 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.

.. code:: 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.

.. code:: 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.

.. code:: python3

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

.. code:: 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.

.. code:: 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.

.. code:: bash

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

We can now use these tags whenever we would use the matching hashes.

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:

.. code:: 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.

.. code:: 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.

.. code:: 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.

.. code:: 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.

.. code:: 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 latest blog post https://www.pozetron.com/blog/jedi-lights/


