Merge pull request #1 from brentru/master

Initial Code, AWS IoT Library for CircuitPython

.gitignore

@@ -0,0 +1,13 @@
+*.mpy
+.idea
+__pycache__
+_build
+*.pyc
+.env
+build*
+bundles
+*.DS_Store
+.eggs
+dist
+**/*.egg-info
+.vscode

.pylintrc

@@ -0,0 +1,433 @@
+[MASTER]
+
+# A comma-separated list of package or module names from where C extensions may
+# be loaded. Extensions are loading into the active Python interpreter and may
+# run arbitrary code
+extension-pkg-whitelist=
+
+# Add files or directories to the blacklist. They should be base names, not
+# paths.
+ignore=CVS
+
+# Add files or directories matching the regex patterns to the blacklist. The
+# regex matches against base names, not paths.
+ignore-patterns=
+
+# Python code to execute, usually for sys.path manipulation such as
+# pygtk.require().
+#init-hook=
+
+# Use multiple processes to speed up Pylint.
+# jobs=1
+jobs=2
+
+# List of plugins (as comma separated values of python modules names) to load,
+# usually to register additional checkers.
+load-plugins=
+
+# Pickle collected data for later comparisons.
+persistent=yes
+
+# Specify a configuration file.
+#rcfile=
+
+# Allow loading of arbitrary C extensions. Extensions are imported into the
+# active Python interpreter and may run arbitrary code.
+unsafe-load-any-extension=no
+
+
+[MESSAGES CONTROL]
+
+# Only show warnings with the listed confidence levels. Leave empty to show
+# all. Valid levels: HIGH, INFERENCE, INFERENCE_FAILURE, UNDEFINED
+confidence=
+
+# Disable the message, report, category or checker with the given id(s). You
+# can either give multiple identifiers separated by comma (,) or put this
+# option multiple times (only on the command line, not in the configuration
+# file where it should appear only once).You can also use "--disable=all" to
+# disable everything first and then reenable specific checks. For example, if
+# you want to run only the similarities checker, you can use "--disable=all
+# --enable=similarities". If you want to run only the classes checker, but have
+# no Warning level messages displayed, use"--disable=all --enable=classes
+# --disable=W"
+# disable=import-error,print-statement,parameter-unpacking,unpacking-in-except,old-raise-syntax,backtick,long-suffix,old-ne-operator,old-octal-literal,import-star-module-level,raw-checker-failed,bad-inline-option,locally-disabled,locally-enabled,file-ignored,suppressed-message,useless-suppression,deprecated-pragma,apply-builtin,basestring-builtin,buffer-builtin,cmp-builtin,coerce-builtin,execfile-builtin,file-builtin,long-builtin,raw_input-builtin,reduce-builtin,standarderror-builtin,unicode-builtin,xrange-builtin,coerce-method,delslice-method,getslice-method,setslice-method,no-absolute-import,old-division,dict-iter-method,dict-view-method,next-method-called,metaclass-assignment,indexing-exception,raising-string,reload-builtin,oct-method,hex-method,nonzero-method,cmp-method,input-builtin,round-builtin,intern-builtin,unichr-builtin,map-builtin-not-iterating,zip-builtin-not-iterating,range-builtin-not-iterating,filter-builtin-not-iterating,using-cmp-argument,eq-without-hash,div-method,idiv-method,rdiv-method,exception-message-attribute,invalid-str-codec,sys-max-int,bad-python3-import,deprecated-string-function,deprecated-str-translate-call
+disable=print-statement,parameter-unpacking,unpacking-in-except,old-raise-syntax,backtick,long-suffix,old-ne-operator,old-octal-literal,import-star-module-level,raw-checker-failed,bad-inline-option,locally-disabled,locally-enabled,file-ignored,suppressed-message,useless-suppression,deprecated-pragma,apply-builtin,basestring-builtin,buffer-builtin,cmp-builtin,coerce-builtin,execfile-builtin,file-builtin,long-builtin,raw_input-builtin,reduce-builtin,standarderror-builtin,unicode-builtin,xrange-builtin,coerce-method,delslice-method,getslice-method,setslice-method,no-absolute-import,old-division,dict-iter-method,dict-view-method,next-method-called,metaclass-assignment,indexing-exception,raising-string,reload-builtin,oct-method,hex-method,nonzero-method,cmp-method,input-builtin,round-builtin,intern-builtin,unichr-builtin,map-builtin-not-iterating,zip-builtin-not-iterating,range-builtin-not-iterating,filter-builtin-not-iterating,using-cmp-argument,eq-without-hash,div-method,idiv-method,rdiv-method,exception-message-attribute,invalid-str-codec,sys-max-int,bad-python3-import,deprecated-string-function,deprecated-str-translate-call,import-error
+
+# Enable the message, report, category or checker with the given id(s). You can
+# either give multiple identifier separated by comma (,) or put this option
+# multiple time (only on the command line, not in the configuration file where
+# it should appear only once). See also the "--disable" option for examples.
+enable=
+
+
+[REPORTS]
+
+# Python expression which should return a note less than 10 (10 is the highest
+# note). You have access to the variables errors warning, statement which
+# respectively contain the number of errors / warnings messages and the total
+# number of statements analyzed. This is used by the global evaluation report
+# (RP0004).
+evaluation=10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10)
+
+# Template used to display messages. This is a python new-style format string
+# used to format the message information. See doc for all details
+#msg-template=
+
+# Set the output format. Available formats are text, parseable, colorized, json
+# and msvs (visual studio).You can also give a reporter class, eg
+# mypackage.mymodule.MyReporterClass.
+output-format=text
+
+# Tells whether to display a full report or only the messages
+reports=no
+
+# Activate the evaluation score.
+score=yes
+
+
+[REFACTORING]
+
+# Maximum number of nested blocks for function / method body
+max-nested-blocks=5
+
+
+[LOGGING]
+
+# Logging modules to check that the string format arguments are in logging
+# function parameter format
+logging-modules=logging
+
+
+[SPELLING]
+
+# Spelling dictionary name. Available dictionaries: none. To make it working
+# install python-enchant package.
+spelling-dict=
+
+# List of comma separated words that should not be checked.
+spelling-ignore-words=
+
+# A path to a file that contains private dictionary; one word per line.
+spelling-private-dict-file=
+
+# Tells whether to store unknown words to indicated private dictionary in
+# --spelling-private-dict-file option instead of raising a message.
+spelling-store-unknown-words=no
+
+
+[MISCELLANEOUS]
+
+# List of note tags to take in consideration, separated by a comma.
+# notes=FIXME,XXX,TODO
+notes=FIXME,XXX
+
+
+[TYPECHECK]
+
+# List of decorators that produce context managers, such as
+# contextlib.contextmanager. Add to this list to register other decorators that
+# produce valid context managers.
+contextmanager-decorators=contextlib.contextmanager
+
+# List of members which are set dynamically and missed by pylint inference
+# system, and so shouldn't trigger E1101 when accessed. Python regular
+# expressions are accepted.
+generated-members=
+
+# Tells whether missing members accessed in mixin class should be ignored. A
+# mixin class is detected if its name ends with "mixin" (case insensitive).
+ignore-mixin-members=yes
+
+# This flag controls whether pylint should warn about no-member and similar
+# checks whenever an opaque object is returned when inferring. The inference
+# can return multiple potential results while evaluating a Python object, but
+# some branches might not be evaluated, which results in partial inference. In
+# that case, it might be useful to still emit no-member and other checks for
+# the rest of the inferred objects.
+ignore-on-opaque-inference=yes
+
+# List of class names for which member attributes should not be checked (useful
+# for classes with dynamically set attributes). This supports the use of
+# qualified names.
+ignored-classes=optparse.Values,thread._local,_thread._local
+
+# List of module names for which member attributes should not be checked
+# (useful for modules/projects where namespaces are manipulated during runtime
+# and thus existing member attributes cannot be deduced by static analysis. It
+# supports qualified module names, as well as Unix pattern matching.
+ignored-modules=board
+
+# Show a hint with possible names when a member name was not found. The aspect
+# of finding the hint is based on edit distance.
+missing-member-hint=yes
+
+# The minimum edit distance a name should have in order to be considered a
+# similar match for a missing member name.
+missing-member-hint-distance=1
+
+# The total number of similar names that should be taken in consideration when
+# showing a hint for a missing member.
+missing-member-max-choices=1
+
+
+[VARIABLES]
+
+# List of additional names supposed to be defined in builtins. Remember that
+# you should avoid to define new builtins when possible.
+additional-builtins=
+
+# Tells whether unused global variables should be treated as a violation.
+allow-global-unused-variables=yes
+
+# List of strings which can identify a callback function by name. A callback
+# name must start or end with one of those strings.
+callbacks=cb_,_cb
+
+# A regular expression matching the name of dummy variables (i.e. expectedly
+# not used).
+dummy-variables-rgx=_+$|(_[a-zA-Z0-9_]*[a-zA-Z0-9]+?$)|dummy|^ignored_|^unused_
+
+# Argument names that match this expression will be ignored. Default to name
+# with leading underscore
+ignored-argument-names=_.*|^ignored_|^unused_
+
+# Tells whether we should check for unused import in __init__ files.
+init-import=no
+
+# List of qualified module names which can have objects that can redefine
+# builtins.
+redefining-builtins-modules=six.moves,future.builtins
+
+
+[FORMAT]
+
+# Expected format of line ending, e.g. empty (any line ending), LF or CRLF.
+# expected-line-ending-format=
+expected-line-ending-format=LF
+
+# Regexp for a line that is allowed to be longer than the limit.
+ignore-long-lines=^\s*(# )?<?https?://\S+>?$
+
+# Number of spaces of indent required inside a hanging  or continued line.
+indent-after-paren=4
+
+# String used as indentation unit. This is usually "    " (4 spaces) or "\t" (1
+# tab).
+indent-string='    '
+
+# Maximum number of characters on a single line.
+max-line-length=100
+
+# Maximum number of lines in a module
+max-module-lines=1000
+
+# List of optional constructs for which whitespace checking is disabled. `dict-
+# separator` is used to allow tabulation in dicts, etc.: {1  : 1,\n222: 2}.
+# `trailing-comma` allows a space between comma and closing bracket: (a, ).
+# `empty-line` allows space-only lines.
+no-space-check=trailing-comma,dict-separator
+
+# Allow the body of a class to be on the same line as the declaration if body
+# contains single statement.
+single-line-class-stmt=no
+
+# Allow the body of an if to be on the same line as the test if there is no
+# else.
+single-line-if-stmt=no
+
+
+[SIMILARITIES]
+
+# Ignore comments when computing similarities.
+ignore-comments=yes
+
+# Ignore docstrings when computing similarities.
+ignore-docstrings=yes
+
+# Ignore imports when computing similarities.
+ignore-imports=no
+
+# Minimum lines number of a similarity.
+min-similarity-lines=4
+
+
+[BASIC]
+
+# Naming hint for argument names
+argument-name-hint=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Regular expression matching correct argument names
+argument-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Naming hint for attribute names
+attr-name-hint=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Regular expression matching correct attribute names
+attr-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Bad variable names which should always be refused, separated by a comma
+bad-names=foo,bar,baz,toto,tutu,tata
+
+# Naming hint for class attribute names
+class-attribute-name-hint=([A-Za-z_][A-Za-z0-9_]{2,30}|(__.*__))$
+
+# Regular expression matching correct class attribute names
+class-attribute-rgx=([A-Za-z_][A-Za-z0-9_]{2,30}|(__.*__))$
+
+# Naming hint for class names
+# class-name-hint=[A-Z_][a-zA-Z0-9]+$
+class-name-hint=[A-Z_][a-zA-Z0-9_]+$
+
+# Regular expression matching correct class names
+# class-rgx=[A-Z_][a-zA-Z0-9]+$
+class-rgx=[A-Z_][a-zA-Z0-9_]+$
+
+# Naming hint for constant names
+const-name-hint=(([A-Z_][A-Z0-9_]*)|(__.*__))$
+
+# Regular expression matching correct constant names
+const-rgx=(([A-Z_][A-Z0-9_]*)|(__.*__))$
+
+# Minimum line length for functions/classes that require docstrings, shorter
+# ones are exempt.
+docstring-min-length=-1
+
+# Naming hint for function names
+function-name-hint=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Regular expression matching correct function names
+function-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Good variable names which should always be accepted, separated by a comma
+# good-names=i,j,k,ex,Run,_
+good-names=r,g,b,w,i,j,k,n,x,y,z,ex,ok,Run,_
+
+# Include a hint for the correct naming format with invalid-name
+include-naming-hint=no
+
+# Naming hint for inline iteration names
+inlinevar-name-hint=[A-Za-z_][A-Za-z0-9_]*$
+
+# Regular expression matching correct inline iteration names
+inlinevar-rgx=[A-Za-z_][A-Za-z0-9_]*$
+
+# Naming hint for method names
+method-name-hint=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Regular expression matching correct method names
+method-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Naming hint for module names
+module-name-hint=(([a-z_][a-z0-9_]*)|([A-Z][a-zA-Z0-9]+))$
+
+# Regular expression matching correct module names
+module-rgx=(([a-z_][a-z0-9_]*)|([A-Z][a-zA-Z0-9]+))$
+
+# Colon-delimited sets of names that determine each other's naming style when
+# the name regexes allow several styles.
+name-group=
+
+# Regular expression which should only match function or class names that do
+# not require a docstring.
+no-docstring-rgx=^_
+
+# List of decorators that produce properties, such as abc.abstractproperty. Add
+# to this list to register other decorators that produce valid properties.
+property-classes=abc.abstractproperty
+
+# Naming hint for variable names
+variable-name-hint=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Regular expression matching correct variable names
+variable-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+
+[IMPORTS]
+
+# Allow wildcard imports from modules that define __all__.
+allow-wildcard-with-all=no
+
+# Analyse import fallback blocks. This can be used to support both Python 2 and
+# 3 compatible code, which means that the block might have code that exists
+# only in one or another interpreter, leading to false positives when analysed.
+analyse-fallback-blocks=no
+
+# Deprecated modules which should not be used, separated by a comma
+deprecated-modules=optparse,tkinter.tix
+
+# Create a graph of external dependencies in the given file (report RP0402 must
+# not be disabled)
+ext-import-graph=
+
+# Create a graph of every (i.e. internal and external) dependencies in the
+# given file (report RP0402 must not be disabled)
+import-graph=
+
+# Create a graph of internal dependencies in the given file (report RP0402 must
+# not be disabled)
+int-import-graph=
+
+# Force import order to recognize a module as part of the standard
+# compatibility libraries.
+known-standard-library=
+
+# Force import order to recognize a module as part of a third party library.
+known-third-party=enchant
+
+
+[CLASSES]
+
+# List of method names used to declare (i.e. assign) instance attributes.
+defining-attr-methods=__init__,__new__,setUp
+
+# List of member names, which should be excluded from the protected access
+# warning.
+exclude-protected=_asdict,_fields,_replace,_source,_make
+
+# List of valid names for the first argument in a class method.
+valid-classmethod-first-arg=cls
+
+# List of valid names for the first argument in a metaclass class method.
+valid-metaclass-classmethod-first-arg=mcs
+
+
+[DESIGN]
+
+# Maximum number of arguments for function / method
+max-args=5
+
+# Maximum number of attributes for a class (see R0902).
+# max-attributes=7
+max-attributes=11
+
+# Maximum number of boolean expressions in a if statement
+max-bool-expr=5
+
+# Maximum number of branch for function / method body
+max-branches=12
+
+# Maximum number of locals for function / method body
+max-locals=15
+
+# Maximum number of parents for a class (see R0901).
+max-parents=7
+
+# Maximum number of public methods for a class (see R0904).
+max-public-methods=20
+
+# Maximum number of return / yield for function / method body
+max-returns=6
+
+# Maximum number of statements in function / method body
+max-statements=50
+
+# Minimum number of public methods for a class (see R0903).
+min-public-methods=1
+
+
+[EXCEPTIONS]
+
+# Exceptions that will emit a warning when being caught. Defaults to
+# "Exception"
+overgeneral-exceptions=Exception

.readthedocs.yml

@@ -0,0 +1,3 @@
+python:
+    version: 3
+requirements_file: requirements.txt

.travis.yml

@@ -0,0 +1,48 @@
+# This is a common .travis.yml for generating library release zip files for
+# CircuitPython library releases using circuitpython-build-tools.
+# See https://github.com/adafruit/circuitpython-build-tools for detailed setup
+# instructions.
+
+dist: xenial
+language: python
+python:
+  - "3.6"
+
+cache:
+  pip: true
+
+# TODO: if deployment to PyPi is desired, change 'DEPLOY_PYPI' to "true",
+#       or remove the env block entirely and remove the condition in the
+#       deploy block.
+env:
+  - DEPLOY_PYPI="false"
+
+deploy:
+  - provider: releases
+    api_key: "$GITHUB_TOKEN"
+    file_glob: true
+    file: "$TRAVIS_BUILD_DIR/bundles/*"
+    skip_cleanup: true
+    overwrite: true
+    on:
+      tags: true
+  # TODO: Use 'travis encrypt --com -r adafruit/<repo slug>' to generate
+  #       the encrypted password for adafruit-travis. Paste result below.
+  - provider: pypi
+    user: adafruit-travis
+    password:
+      secure: #-- PASTE ENCRYPTED PASSWORD HERE --#
+    on:
+      tags: true
+      condition: $DEPLOY_PYPI = "true"
+
+install:
+  - pip install -r requirements.txt
+  - pip install circuitpython-build-tools Sphinx sphinx-rtd-theme
+  - pip install --force-reinstall pylint==1.9.2
+
+script:
+  - pylint adafruit_aws_iot.py
+  - ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name,bad-whitespace examples/*.py)
+  - circuitpython-build-bundles --filename_prefix adafruit-circuitpython-aws_iot --library_location .
+  - cd docs && sphinx-build -E -W -b html . _build/html && cd ..

CODE_OF_CONDUCT.md

@@ -0,0 +1,127 @@
+# Adafruit Community Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and leaders pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level or type of
+experience, education, socio-economic status, nationality, personal appearance,
+race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+We are committed to providing a friendly, safe and welcoming environment for
+all.
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Be kind and courteous to others
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Collaborating with other community members
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and sexual attention or advances
+* The use of inappropriate images, including in a community member's avatar
+* The use of inappropriate language, including in a community member's nickname
+* Any spamming, flaming, baiting or other attention-stealing behavior
+* Excessive or unwelcome helping; answering outside the scope of the question
+  asked
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate
+
+The goal of the standards and moderation guidelines outlined here is to build
+and maintain a respectful community. We ask that you don’t just aim to be
+"technically unimpeachable", but rather try to be your best self.
+
+We value many things beyond technical expertise, including collaboration and
+supporting others within our community. Providing a positive experience for
+other community members can have a much more significant impact than simply
+providing the correct answer.
+
+## Our Responsibilities
+
+Project leaders are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project leaders have the right and responsibility to remove, edit, or
+reject messages, comments, commits, code, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any community member for other behaviors that they deem
+inappropriate, threatening, offensive, or harmful.
+
+## Moderation
+
+Instances of behaviors that violate the Adafruit Community Code of Conduct
+may be reported by any member of the community. Community members are
+encouraged to report these situations, including situations they witness
+involving other community members.
+
+You may report in the following ways:
+
+In any situation, you may send an email to <support@adafruit.com>.
+
+On the Adafruit Discord, you may send an open message from any channel
+to all Community Helpers by tagging @community moderators. You may also send an
+open message from any channel, or a direct message to @kattni#1507,
+@tannewt#4653, @Dan Halbert#1614, @cater#2442, @sommersoft#0222, or
+@Andon#8175.
+
+Email and direct message reports will be kept confidential.
+
+In situations on Discord where the issue is particularly egregious, possibly
+illegal, requires immediate action, or violates the Discord terms of service,
+you should also report the message directly to Discord.
+
+These are the steps for upholding our community’s standards of conduct.
+
+1. Any member of the community may report any situation that violates the
+Adafruit Community Code of Conduct. All reports will be reviewed and
+investigated.
+2. If the behavior is an egregious violation, the community member who
+committed the violation may be banned immediately, without warning.
+3. Otherwise, moderators will first respond to such behavior with a warning.
+4. Moderators follow a soft "three strikes" policy - the community member may
+be given another chance, if they are receptive to the warning and change their
+behavior.
+5. If the community member is unreceptive or unreasonable when warned by a
+moderator, or the warning goes unheeded, they may be banned for a first or
+second offense. Repeated offenses will result in the community member being
+banned.
+
+## Scope
+
+This Code of Conduct and the enforcement policies listed above apply to all
+Adafruit Community venues. This includes but is not limited to any community
+spaces (both public and private), the entire Adafruit Discord server, and
+Adafruit GitHub repositories. Examples of Adafruit Community spaces include
+but are not limited to meet-ups, audio chats on the Adafruit Discord, or
+interaction at a conference.
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. As a community
+member, you are representing our community, and are expected to behave
+accordingly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.4, available at
+<https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>,
+and the [Rust Code of Conduct](https://www.rust-lang.org/en-US/conduct.html).
+
+For other projects adopting the Adafruit Community Code of
+Conduct, please contact the maintainers of those projects for enforcement.
+If you wish to use this code of conduct for your own project, consider
+explicitly mentioning your moderation policy or making a copy with your
+own moderation policy so as to avoid confusion.

LICENSE

@@ -1,6 +1,6 @@
-MIT License
+The MIT License (MIT)
 
-Copyright (c) 2019 Adafruit Industries
+Copyright (c) 2019 Brent Rubell for Adafruit Industries
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,2 +0,0 @@
-# Adafruit_CircuitPython_AWS_IOT
-Amazon AWS IoT MQTT Client for CircuitPython

README.rst

@@ -0,0 +1,95 @@
+Introduction
+============
+
+.. image:: https://readthedocs.org/projects/adafruit-circuitpython-aws_iot/badge/?version=latest
+    :target: https://circuitpython.readthedocs.io/projects/aws_iot/en/latest/
+    :alt: Documentation Status
+
+.. image:: https://img.shields.io/discord/327254708534116352.svg
+    :target: https://discord.gg/nBQh6qu
+    :alt: Discord
+
+.. image:: https://travis-ci.com/adafruit/Adafruit_CircuitPython_AWS_IOT.svg?branch=master
+    :target: https://travis-ci.com/adafruit/Adafruit_CircuitPython_AWS_IOT
+    :alt: Build Status
+
+Amazon AWS IoT MQTT Client for CircuitPython.
+
+
+**Note**: This library requires version **>=1.4.0** of the `Adafruit fork of the Arduino NINA-W102 firmware <https://github.com/adafruit/nina-fw>`_
+ installed on your ESP32 Airlift/WiFi Co-Processor.
+
+If you do not know how to do this, `visit the Adafruit Learning System guide for this topic... <https://learn.adafruit.com/upgrading-esp32-firmware>`_
+
+
+Dependencies
+=============
+This driver depends on:
+
+* `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
+
+Please ensure all dependencies are available on the CircuitPython filesystem.
+This is easily achieved by downloading
+`the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
+
+Installing from PyPI
+=====================
+.. note:: This library is not available on PyPI yet. Install documentation is included
+   as a standard element. Stay tuned for PyPI availability!
+
+On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
+PyPI <https://pypi.org/project/adafruit-circuitpython-aws_iot/>`_. To install for current user:
+
+.. code-block:: shell
+
+    pip3 install adafruit-circuitpython-aws-iot
+
+To install system-wide (this may be required in some cases):
+
+.. code-block:: shell
+
+    sudo pip3 install adafruit-circuitpython-aws-iot
+
+To install in a virtual environment in your current project:
+
+.. code-block:: shell
+
+    mkdir project-name && cd project-name
+    python3 -m venv .env
+    source .env/bin/activate
+    pip3 install adafruit-circuitpython-aws-iot
+
+Usage Example
+=============
+
+Library examples within examples/ folder.
+
+Contributing
+============
+
+Contributions are welcome! Please read our `Code of Conduct
+<https://github.com/adafruit/Adafruit_CircuitPython_AWS_IOT/blob/master/CODE_OF_CONDUCT.md>`_
+before contributing to help this project stay welcoming.
+
+Sphinx documentation
+-----------------------
+
+Sphinx is used to build the documentation based on rST files and comments in the code. First,
+install dependencies (feel free to reuse the virtual environment from above):
+
+.. code-block:: shell
+
+    python3 -m venv .env
+    source .env/bin/activate
+    pip install Sphinx sphinx-rtd-theme
+
+Now, once you have the virtual environment activated:
+
+.. code-block:: shell
+
+    cd docs
+    sphinx-build -E -W -b html . _build/html
+
+This will output the documentation to ``docs/_build/html``. Open the index.html in your browser to
+view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to
+locally verify it will pass.

adafruit_aws_iot.py

@@ -0,0 +1,300 @@
+# The MIT License (MIT)
+#
+# Copyright (c) 2019 Brent Rubell for Adafruit Industries
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+"""
+`adafruit_aws_iot`
+================================================================================
+
+Amazon AWS IoT MQTT Client for CircuitPython
+
+
+* Author(s): Brent Rubell
+
+Implementation Notes
+--------------------
+
+**Hardware:**
+
+
+**Software and Dependencies:**
+
+* Adafruit CircuitPython firmware for the supported boards:
+  https://github.com/adafruit/circuitpython/releases
+
+"""
+import json
+from adafruit_minimqtt import MMQTTException
+
+__version__ = "0.0.0-auto.0"
+__repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_AWS_IOT.git"
+
+
+class AWS_IOT_ERROR(Exception):
+    """Exception raised on MQTT API return-code errors."""
+    # pylint: disable=unnecessary-pass
+    pass
+
+class MQTT_CLIENT:
+    """Client for interacting with Amazon AWS IoT MQTT API.
+
+    :param MiniMQTT mmqttclient: Pre-configured MiniMQTT Client object.
+    :param int keep_alive: Optional Keep-alive timer interval, in seconds.
+                          Provided interval must be 30 <= keep_alive <= 1200.
+
+    """
+    def __init__(self, mmqttclient, keep_alive=30):
+        if "MQTT" in str(type(mmqttclient)):
+            self.client = mmqttclient
+        else:
+            raise TypeError("This class requires a preconfigured MiniMQTT object, \
+                                please create one.")
+        # Verify nina-fw => 1.4.0
+        fw_semver_maj = bytes(self.client.wifi.esp.firmware_version).decode("utf-8")[2]
+        assert int(fw_semver_maj) >= 4, "Please update nina-fw to 1.4.0 or above."
+        # Verify MiniMQTT client object configuration
+        try:
+            self.cid = self.client.client_id
+            assert self.cid[0] != "$", "Client ID can not start with restricted client ID prefix $."
+        except:
+            raise TypeError("You must provide MiniMQTT with your AWS IoT Device's Identifier \
+                                as the Client ID.")
+        # Shadow-interaction topic
+        self.shadow_topic = "$aws/things/{}/shadow".format(self.cid)
+        # Ensure set_certificate and set_private_key were run from ESP32SPI
+        assert self.client.wifi.esp.set_psk and self.client.wifi.esp.set_cert, "Certificate \
+            and private key must be set to your AWS Device Cert and Private Key."
+        # keep_alive timer must be between 30 <= keep alive interval <= 1200 seconds
+        # https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html
+        assert 30 <= keep_alive <= 1200, "Keep_Alive timer \
+            interval must be between 30 and 1200 seconds"
+        self.keep_alive = keep_alive
+        # User-defined MQTT callback methods must be init'd to None
+        self.on_connect = None
+        self.on_disconnect = None
+        self.on_message = None
+        self.on_subscribe = None
+        self.on_unsubscribe = None
+        # Connect MiniMQTT callback handlers
+        self.client.on_connect = self._on_connect_mqtt
+        self.client.on_disconnect = self._on_disconnect_mqtt
+        self.client.on_message = self._on_message_mqtt
+        self.client.on_subscribe = self._on_subscribe_mqtt
+        self.client.on_unsubscribe = self._on_unsubscribe_mqtt
+        self.connected_to_aws = False
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exception_type, exception_value, traceback):
+        self.disconnect()
+
+
+    @property
+    def is_connected(self):
+        """Returns if MQTT_CLIENT is connected to AWS IoT MQTT Broker
+
+        """
+        return self.connected_to_aws
+
+    def disconnect(self):
+        """Disconnects from Amazon AWS IoT MQTT Broker and de-initializes the MiniMQTT Client.
+
+        """
+        try:
+            self.client.disconnect()
+        except MMQTTException as error:
+            raise AWS_IOT_ERROR('Error disconnecting with AWS IoT: ', error)
+        self.connected_to_aws = False
+        # Reset user-defined callback methods to None
+        self.on_connect = None
+        self.on_disconnect = None
+        self.on_message = None
+        self.on_subscribe = None
+        self.on_unsubscribe = None
+        self.client.deinit()
+
+    def connect(self, clean_session=True):
+        """Connects to Amazon AWS IoT MQTT Broker with Client ID.
+        :param bool clean_session: Establishes a clean session with AWS broker.
+
+        """
+        try:
+            self.client.connect(clean_session)
+        except MMQTTException as error:
+            raise AWS_IOT_ERROR('Error connecting to AWS IoT: ', error)
+        self.connected_to_aws = True
+
+    # MiniMQTT Callback Handlers
+    # pylint: disable=not-callable, unused-argument
+    def _on_connect_mqtt(self, client, userdata, flag, ret_code):
+        """Runs when code calls on_connect.
+        :param MiniMQTT client: MiniMQTT client object.
+        :param str user_data: User data from broker
+        :param int flag: QoS flag from broker.
+        :param int ret_code: Return code from broker.
+
+        """
+        self.connected_to_aws = True
+        # Call the on_connect callback if defined in code
+        if self.on_connect is not None:
+            self.on_connect(self, userdata, flag, ret_code)
+
+    # pylint: disable=not-callable, unused-argument
+    def _on_disconnect_mqtt(self, client, userdata, flag, ret_code):
+        """Runs when code calls on_disconnect.
+        :param MiniMQTT client: MiniMQTT client object.
+        :param str user_data: User data from broker
+        :param int flag: QoS flag from broker.
+        :param int ret_code: Return code from broker.
+
+        """
+        self.connected_to_aws = False
+        # Call the on_connect callback if defined in code
+        if self.on_connect is not None:
+            self.on_connect(self, userdata, flag, ret_code)
+
+    # pylint: disable=not-callable
+    def _on_message_mqtt(self, client, topic, payload):
+        """Runs when the client calls on_message.
+        :param MiniMQTT client: MiniMQTT client object.
+        :param str topic: MQTT broker topic.
+        :param str payload: Payload returned by MQTT broker topic
+
+        """
+        if self.on_message is not None:
+            self.on_message(self, topic, payload)
+
+    # pylint: disable=not-callable
+    def _on_subscribe_mqtt(self, client, user_data, topic, qos):
+        """Runs when the client calls on_subscribe.
+
+        :param MiniMQTT client: MiniMQTT client object.
+        :param str user_data: User data from broker
+        :param str topic: Desired MQTT topic.
+        param int qos: Quality of service level for topic, from broker.
+
+        """
+        if self.on_subscribe is not None:
+            self.on_subscribe(self, user_data, topic, qos)
+
+    # pylint: disable=not-callable
+    def _on_unsubscribe_mqtt(self, client, user_data, topic, pid):
+        """Runs when the client calls on_unsubscribe.
+        """
+        if self.on_unsubscribe is not None:
+            self.on_unsubscribe(self, user_data, topic, pid)
+
+    # MiniMQTT Network Control Flow
+    def loop(self):
+        """ Starts a synchronous message loop which maintains connection with AWS IoT.
+        Must be called within the keep_alive timeout specified to init.
+        This method does not handle network connection/disconnection.
+
+        Example of "pumping" an AWS IoT message loop:
+        ..code-block::python
+
+            while True:
+                aws_iot.loop()
+
+        """
+        if self.connected_to_aws:
+            self.client.loop()
+
+    def loop_forever(self):
+        """Begins a blocking, asynchronous message loop.
+        This method handles network connection/disconnection.
+
+        """
+        if self.connected_to_aws:
+            self.client.loop_forever()
+
+    @staticmethod
+    def validate_topic(topic):
+        """Validates if user-provided pub/sub topics adhere to AWS Service Limits.
+        https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html
+        :param str topic: Desired topic to validate
+
+        """
+        assert hasattr(topic, "split"), "Topic must be a string"
+        assert len(topic) < 256, "Topic must be less than 256 bytes!"
+        assert len(topic.split("/")) <= 9, "Topics are limited to 7 forward slashes."
+
+    # MiniMQTT Pub/Sub Methods, for usage with AWS IoT
+    def subscribe(self, topic, qos=1):
+        """Subscribes to an AWS IoT Topic.
+        :param str topic: MQTT topic to subscribe to.
+        :param int qos: Desired topic subscription's quality-of-service.
+
+        """
+        assert qos < 2, "AWS IoT does not support subscribing with QoS 2."
+        self.validate_topic(topic)
+        self.client.subscribe(topic, qos)
+
+    def publish(self, topic, payload, qos=1):
+        """Publishes to a AWS IoT Topic.
+        :param str topic: MQTT topic to publish to.
+        :param str payload: Data to publish to topic.
+        :param int payload: Data to publish to topic.
+        :param float payload: Data to publish to topic.
+        :param json payload: JSON-formatted data to publish to topic.
+        :param int qos: Quality of service level for publishing.
+
+        """
+        assert qos < 2, "AWS IoT does not support publishing with QoS 2."
+        self.validate_topic(topic)
+        if isinstance(payload, int or float):
+            payload = str(payload)
+        self.client.publish(topic, payload, qos=qos)
+
+    # AWS IoT Device Shadow Service
+
+    def shadow_get_subscribe(self, qos=1):
+        """Subscribes to  device's shadow get response.
+        :param int qos: Optional quality of service level.
+
+        """
+        self.client.subscribe(self.shadow_topic+"/get/#", qos)
+
+    def shadow_subscribe(self, qos=1):
+        """Subscribes to all notifications on the device's shadow update topic.
+        :param int qos: Optional quality of service level.
+
+        """
+        self.client.subscribe(self.shadow_topic+"/update/#", qos)
+
+    def shadow_update(self, document):
+        """Publishes a request state document to update the device's shadow.
+        :param json state_document: JSON-formatted state document.
+
+        """
+        self.client.publish(self.shadow_topic+"/update", document)
+
+    def shadow_get(self):
+        """Publishes an empty message to shadow get topic to get the device's shadow.
+
+        """
+        self.client.publish(self.shadow_topic+"/get", json.dumps({"message": "ignore"}))
+
+    def shadow_delete(self):
+        """Publishes an empty message to the shadow delete topic to delete a device's shadow
+
+        """
+        self.client.publish(self.shadow_topic+"/delete", json.dumps({"message": "delete"}))

certificates.py

@@ -0,0 +1,47 @@
+# Replace with the Device Certificate (.crt) from AWS IoT
+DEVICE_CERT = "-----BEGIN CERTIFICATE-----\n"\
+"MIICljCCAX4CAQAwUTELMAkGA1UEBhMCVVMxETAPBgNVBAgMCE5ldyBZb3JrMREw\n"\
+"DwYDVQQHDAhOZXcgWW9yazEcMBoGA1UECgwTQWRhZnJ1aXQgSW5kdXN0cmllczCC\n"\
+"ASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKQSbmfDnFDb1Ul+SjkGmX14\n"\
+"WpwNMH2hlkP2tyPTlCyks8mEN9q28Xs7ikT0K8mzhhuvuWkmwNEtEJimRpEq8i2L\n"\
+"foaxOzguCFBH0O+5PLzNpTH0AphIKPhE92xeR3rSO3KSVHESqL7CItXstogZO4br\n"\
+"h74bkL/UzS5EzIUv+vCLoiYV6sNt2PNcrSWHST1ARHLV94Qdkm6NKX2Ag3dndexk\n"\
+"8eZ014kzkfNtZm6S2+DXtc+CZLhZnyien0r1zIM9C1Heu9Fsjs7I20hWWgq9MjgM\n"\
+"NBTQxJQgTNvDzMNWV1uPEH23cht/j84UaVePGH+1NvWvFudVL2UPLeoxGTY9Or8C\n"\
+"AwEAAaAAMA0GCSqGSIb3DQEBCwUAA4IBAQB0Oh669kmjdv8D20fQavzzHPZMO/WO\n"\
+"aAB8rXggOcyKSNpHys3kYmTLT3DPoswfYijOL/Owdzy/e38FBJhKq1THHVpOXtD+\n"\
+"3egaBOZxhEFCCuk1gi2+XGYuymE4YmFKYENUOeKX0rwgCMgt8v+PBUsVFFGsAfAl\n"\
+"cXeVI/5oTgCRKVsqEAQzGT2AmakLojpm1uqfoNXq+d70e8xC+gstxYWZAJTygSA7\n"\
+"3N2vqsQsN5H7ZGL+ZzoBeVGMH/5QHSr6emp4AWHe/OwmFiSyVYgCtX1OFxtJ6KC6\n"\
+"2wJhNj1KVGeVRnhXPHiT/+L92eZHi+eiu2SnRjNYxZsuma2Z+h8lK28w\n"\
+"-----END CERTIFICATE-----\n"
+
+# Replace with the RSA Private Key from AWS IoT
+DEVICE_KEY = "-----BEGIN PRIVATE KEY-----\n"\
+"MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQCkEm5nw5xQ29VJ\n"\
+"fko5Bpl9eFqcDTB9oZZD9rcj05QspLPJhDfatvF7O4pE9CvJs4Ybr7lpJsDRLRCY\n"\
+"pkaRKvIti36GsTs4LghQR9DvuTy8zaUx9AKYSCj4RPdsXkd60jtyklRxEqi+wiLV\n"\
+"7LaIGTuG64e+G5C/1M0uRMyFL/rwi6ImFerDbdjzXK0lh0k9QERy1feEHZJujSl9\n"\
+"gIN3Z3XsZPHmdNeJM5HzbWZuktvg17XPgmS4WZ8onp9K9cyDPQtR3rvRbI7OyNtI\n"\
+"VloKvTI4DDQU0MSUIEzbw8zDVldbjxB9t3Ibf4/OFGlXjxh/tTb1rxbnVS9lDy3q\n"\
+"MRk2PTq/AgMBAAECggEAIq0OjnmmIOTFSDobv7+oUv9Lzy1ucS7kjkqnXDgMWf8Z\n"\
+"TF7YWy5NDSmBSJ9+XavGjTVvb0zUdaEbn9eMlIPKGVwhCqCMjowUD7uN6gxxTMn9\n"\
+"vvf+UGb32bjhvhKS8t9Z1xYcKKWz6lUnfaUA0vTaQuKmlsRGrHRyRPQfcYq5c3sI\n"\
+"yv3a+KObNaVQphhri7NdCGyE0J0Ob4Pc7coKg8I7M9KbhUagfygkg33HtXd7rNPn\n"\
+"RLcn2UH74KuEX+Edx/2mFnEpdTplo5h0MRBMYG5rMJWiLDJlY5tcZ7k5IlzoN0gc\n"\
+"MjyIkmqF1NQ32KQ4xdN9I2J1w0e9syI9W/6y1uozcQKBgQDSF707g5wJRM2clMeQ\n"\
+"2+zdh28gRHhJwDJzoXPvxZvNR2iqxRyh1QAsR1C6pP7e8zPfwDlvpHrGYX+L1v2V\n"\
+"7G1taSGef6uPt8Mp6ahdkuWxr1+QqKmnqAlmMzWnpOTyKslN8YN9hX7KnRrPKJ3K\n"\
+"6baEy2ujqjb/o6gIlFfrN7uReQKBgQDH7F0e/CBTzts+aahFzjBdQdV0JLgZHYCJ\n"\
+"I3c7vYlc8IIVkAO7GHTB0F57tcekzGEhn3Vg7vIaXB6OwqidoGn2Slb7hropEEr8\n"\
+"xL+9WwzLPWFYcUMMLVZG6c4Yx8J3ikIjRztHKpTYy26CdFx+UruIEIGkCYF0u/Oj\n"\
+"3JWJfUIX9wKBgQDMayrFuJXfcuG45A6VxVdgaUHYHKcJ44dzePnMp/Kjt0KBPo9Q\n"\
+"a2birnU/VgFjvzGPGYMJPPn1ArLOxt4wvT3wAiYjCUhN61hq9J3Mhn0V+XS71VBW\n"\
+"ACs9FMC1IL1fYABE5aSyQm0PCfQm8vctk1/zL9bJBXrEHGIIDwbIqI7JyQKBgQCR\n"\
+"ZE7QktE7wcrmF9a9dVbs60y9m1qbQT5R/Y3fz1ZPVcV0wvhDn2SB8vRTiX54Vf4p\n"\
+"gprNdNhy3R2H+v6/K4MED0o0v+Uwqd2u97LtlYK3Z5scw7nb6Di/d5dfpB7D6rNw\n"\
+"joQInGoFQ+TJULBXWflx2Xc+gX85Etr8BxZlF8fyPwKBgQCkBmi9s0rAqdNLB28Q\n"\
+"31+q39XZMMlT8BPJ225GwekjWiIL6n0Jrm/KkZ6fureBYm3STGLvQbWBao61n4vp\n"\
+"1bSncfADm8rgdkf+/iokP9uZnEIwo050pNNpIFgsJVT2mmu2tHdQFFT6UluQL9q2\n"\
+"733Hks5cHEhAinxLfgLh81+HsQ==\n"
+"-----END PRIVATE KEY-----\n"

docs/api.rst

@@ -0,0 +1,8 @@
+
+.. If you created a package, create one automodule per module in the package.
+
+.. If your library file(s) are nested in a directory (e.g. /adafruit_foo/foo.py)
+.. use this format as the module name: "adafruit_foo.foo"
+
+.. automodule:: adafruit_aws_iot
+   :members:

docs/conf.py

@@ -0,0 +1,160 @@
+# -*- coding: utf-8 -*-
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+
+# -- General configuration ------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.todo',
+]
+
+# TODO: Please Read!
+# Uncomment the below if you use native CircuitPython modules such as
+# digitalio, micropython and busio. List the modules you use. Without it, the
+# autodoc module docs will fail to generate with a warning.
+autodoc_mock_imports = ["adafruit_minimqtt"]
+
+
+intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None),'CircuitPython': ('https://circuitpython.readthedocs.io/en/latest/', None)}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Adafruit AWS_IOT Library'
+copyright = u'2019 Brent Rubell'
+author = u'Brent Rubell'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = u'1.0'
+# The full version, including alpha/beta/rc tags.
+release = u'1.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.env', 'CODE_OF_CONDUCT.md']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#
+default_role = "any"
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#
+add_function_parentheses = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+# If this is True, todo emits a warning for each TODO entries. The default is False.
+todo_emit_warnings = True
+
+napoleon_numpy_docstring = False
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    try:
+        import sphinx_rtd_theme
+        html_theme = 'sphinx_rtd_theme'
+        html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), '.']
+    except:
+        html_theme = 'default'
+        html_theme_path = ['.']
+else:
+    html_theme_path = ['.']
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# The name of an image file (relative to this directory) to use as a favicon of
+# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#
+html_favicon = '_static/favicon.ico'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'AdafruitAws_iotLibrarydoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+     # The paper size ('letterpaper' or 'a4paper').
+     #
+     # 'papersize': 'letterpaper',
+
+     # The font size ('10pt', '11pt' or '12pt').
+     #
+     # 'pointsize': '10pt',
+
+     # Additional stuff for the LaTeX preamble.
+     #
+     # 'preamble': '',
+
+     # Latex figure (float) alignment
+     #
+     # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'AdafruitAWS_IOTLibrary.tex', u'AdafruitAWS_IOT Library Documentation',
+     author, 'manual'),
+]
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'AdafruitAWS_IOTlibrary', u'Adafruit AWS_IOT Library Documentation',
+     [author], 1)
+]
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'AdafruitAWS_IOTLibrary', u'Adafruit AWS_IOT Library Documentation',
+     author, 'AdafruitAWS_IOTLibrary', 'One line description of project.',
+     'Miscellaneous'),
+]

docs/examples.rst

@@ -0,0 +1,8 @@
+Simple test
+------------
+
+Ensure your device works with this simple test.
+
+.. literalinclude:: ../examples/aws_iot_simpletest.py
+    :caption: examples/aws_iot_simpletest.py
+    :linenos:

docs/index.rst

@@ -0,0 +1,47 @@
+.. include:: ../README.rst
+
+Table of Contents
+=================
+
+.. toctree::
+    :maxdepth: 4
+    :hidden:
+
+    self
+
+.. toctree::
+    :caption: Examples
+
+    examples
+
+.. toctree::
+    :caption: API Reference
+    :maxdepth: 3
+
+    api
+
+.. toctree::
+    :caption: Tutorials
+
+
+.. toctree::
+    :caption: Related Products
+
+
+.. toctree::
+    :caption: Other Links
+
+    Download <https://github.com/adafruit/Adafruit_CircuitPython_AWS_IOT/releases/latest>
+    CircuitPython Reference Documentation <https://circuitpython.readthedocs.io>
+    CircuitPython Support Forum <https://forums.adafruit.com/viewforum.php?f=60>
+    Discord Chat <https://adafru.it/discord>
+    Adafruit Learning System <https://learn.adafruit.com>
+    Adafruit Blog <https://blog.adafruit.com>
+    Adafruit Store <https://www.adafruit.com>
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

examples/aws_iot_shadows.py

@@ -0,0 +1,138 @@
+import json
+import board
+import busio
+from digitalio import DigitalInOut
+import neopixel
+from adafruit_esp32spi import adafruit_esp32spi
+from adafruit_esp32spi import adafruit_esp32spi_wifimanager
+import adafruit_esp32spi.adafruit_esp32spi_socket as socket
+from adafruit_minimqtt import MQTT
+from adafruit_aws_iot import MQTT_CLIENT
+
+### WiFi ###
+
+# Get wifi details and more from a secrets.py file
+try:
+    from secrets import secrets
+except ImportError:
+    print("WiFi secrets are kept in secrets.py, please add them there!")
+    raise
+
+# Get device certificate and private key from a certificates.py file
+try:
+    from certificates import DEVICE_CERT, DEVICE_KEY
+except ImportError:
+    print("Certificate and private key data is kept in certificates.py, \
+           please add them there!")
+    raise
+
+# If you are using a board with pre-defined ESP32 Pins:
+esp32_cs = DigitalInOut(board.ESP_CS)
+esp32_ready = DigitalInOut(board.ESP_BUSY)
+esp32_reset = DigitalInOut(board.ESP_RESET)
+
+# If you have an externally connected ESP32:
+# esp32_cs = DigitalInOut(board.D9)
+# esp32_ready = DigitalInOut(board.D10)
+# esp32_reset = DigitalInOut(board.D5)
+
+spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
+esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset)
+"""Use below for Most Boards"""
+status_light = neopixel.NeoPixel(board.NEOPIXEL, 1, brightness=0.2) # Uncomment for Most Boards
+"""Uncomment below for ItsyBitsy M4"""
+# status_light = dotstar.DotStar(board.APA102_SCK, board.APA102_MOSI, 1, brightness=0.2)
+# Uncomment below for an externally defined RGB LED
+# import adafruit_rgbled
+# from adafruit_esp32spi import PWMOut
+# RED_LED = PWMOut.PWMOut(esp, 26)
+# GREEN_LED = PWMOut.PWMOut(esp, 27)
+# BLUE_LED = PWMOut.PWMOut(esp, 25)
+# status_light = adafruit_rgbled.RGBLED(RED_LED, BLUE_LED, GREEN_LED)
+wifi = adafruit_esp32spi_wifimanager.ESPSPI_WiFiManager(esp, secrets, status_light)
+
+### Code ###
+
+# Define callback methods which are called when events occur
+# pylint: disable=unused-argument, redefined-outer-name
+def connect(client, userdata, flags, rc):
+    # This function will be called when the client is connected
+    # successfully to the broker.
+    print('Connected to MQTT Broker!')
+    print('Flags: {0}\n RC: {1}'.format(flags, rc))
+
+    # Subscribe client to all shadow updates
+    print("Subscribing to shadow updates...")
+    aws_iot.shadow_subscribe()
+
+def disconnect(client, userdata, rc):
+    # This method is called when the client disconnects
+    # from the broker.
+    print('Disconnected from MQTT Broker!')
+
+def subscribe(client, userdata, topic, granted_qos):
+    # This method is called when the client subscribes to a new topic.
+    print('Subscribed to {0} with QOS level {1}'.format(topic, granted_qos))
+
+    # Update device shadow with example JSON payload
+    payload = {"state":{"reported":{"moisture":50,"temp":30}}}
+    aws_iot.shadow_update(json.dumps(payload))
+
+    # We can also retrieve the shadow from AWS IoT,
+    # aws_iot.shadow_get()
+
+    # or delete the shadow
+    # aws_iot.shadow_delete()
+
+def unsubscribe(client, userdata, topic, pid):
+    # This method is called when the client unsubscribes from a topic.
+    print('Unsubscribed from {0} with PID {1}'.format(topic, pid))
+
+def publish(client, userdata, topic, pid):
+    # This method is called when the client publishes data to a topic.
+    print('Published to {0} with PID {1}'.format(topic, pid))
+
+def message(client, topic, msg):
+    # This method is called when the client receives data from a topic.
+    print("Message from {}: {}".format(topic, msg))
+
+# Set AWS Device Certificate
+esp.set_certificate(DEVICE_CERT)
+
+# Set AWS RSA Private Key
+esp.set_private_key(DEVICE_KEY)
+
+# Connect to WiFi
+print("Connecting to WiFi...")
+wifi.connect()
+print("Connected!")
+
+
+# Set up a new MiniMQTT Client
+client =  MQTT(socket,
+               broker = secrets['broker'],
+               client_id = secrets['client_id'],
+               network_manager = wifi,
+               log=True)
+
+# Initialize AWS IoT MQTT API Client
+aws_iot = MQTT_CLIENT(client)
+
+# Connect callback handlers to AWS IoT MQTT Client
+aws_iot.on_connect = connect
+aws_iot.on_disconnect = disconnect
+aws_iot.on_subscribe = subscribe
+aws_iot.on_unsubscribe = unsubscribe
+aws_iot.on_publish = publish
+aws_iot.on_message = message
+
+print('Attempting to connect to %s'%client.broker)
+aws_iot.connect()
+
+# Pump the message loop forever, all events
+# are handled in their callback handlers
+# while True:
+#   aws_iot.loop()
+
+# Attempt to loop forever and handle network interface
+aws_iot.loop_forever()

examples/aws_iot_simpletest.py

@@ -0,0 +1,135 @@
+import json
+import board
+import busio
+from digitalio import DigitalInOut
+import neopixel
+from adafruit_esp32spi import adafruit_esp32spi
+from adafruit_esp32spi import adafruit_esp32spi_wifimanager
+import adafruit_esp32spi.adafruit_esp32spi_socket as socket
+from adafruit_minimqtt import MQTT
+from adafruit_aws_iot import MQTT_CLIENT
+
+### WiFi ###
+
+# Get wifi details and more from a secrets.py file
+try:
+    from secrets import secrets
+except ImportError:
+    print("WiFi secrets are kept in secrets.py, please add them there!")
+    raise
+
+# Get device certificate and private key from a certificates.py file
+try:
+    from certificates import DEVICE_CERT, DEVICE_KEY
+except ImportError:
+    print("Certificate and private key data is kept in certificates.py, \
+           please add them there!")
+    raise
+
+# If you are using a board with pre-defined ESP32 Pins:
+esp32_cs = DigitalInOut(board.ESP_CS)
+esp32_ready = DigitalInOut(board.ESP_BUSY)
+esp32_reset = DigitalInOut(board.ESP_RESET)
+
+# If you have an externally connected ESP32:
+# esp32_cs = DigitalInOut(board.D9)
+# esp32_ready = DigitalInOut(board.D10)
+# esp32_reset = DigitalInOut(board.D5)
+
+spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
+esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset)
+"""Use below for Most Boards"""
+status_light = neopixel.NeoPixel(board.NEOPIXEL, 1, brightness=0.2) # Uncomment for Most Boards
+"""Uncomment below for ItsyBitsy M4"""
+# status_light = dotstar.DotStar(board.APA102_SCK, board.APA102_MOSI, 1, brightness=0.2)
+# Uncomment below for an externally defined RGB LED
+# import adafruit_rgbled
+# from adafruit_esp32spi import PWMOut
+# RED_LED = PWMOut.PWMOut(esp, 26)
+# GREEN_LED = PWMOut.PWMOut(esp, 27)
+# BLUE_LED = PWMOut.PWMOut(esp, 25)
+# status_light = adafruit_rgbled.RGBLED(RED_LED, BLUE_LED, GREEN_LED)
+wifi = adafruit_esp32spi_wifimanager.ESPSPI_WiFiManager(esp, secrets, status_light)
+
+### Code ###
+
+topic = "circuitpython/aws"
+
+# Define callback methods which are called when events occur
+# pylint: disable=unused-argument, redefined-outer-name
+def connect(client, userdata, flags, rc):
+    # This function will be called when the client is connected
+    # successfully to the broker.
+    print('Connected to MQTT Broker!')
+    print('Flags: {0}\n RC: {1}'.format(flags, rc))
+
+    # Subscribe to topic circuitpython/aws
+    print("Subscribing to topic {}".format(topic))
+    aws_iot.subscribe(topic)
+
+def disconnect(client, userdata, rc):
+    # This method is called when the client disconnects
+    # from the broker.
+    print('Disconnected from MQTT Broker!')
+
+def subscribe(client, userdata, topic, granted_qos):
+    # This method is called when the client subscribes to a new topic.
+    print('Subscribed to {0} with QOS level {1}'.format(topic, granted_qos))
+
+    # Create a json-formatted message
+    message = {"message": "Hello from AWS IoT CircuitPython"}
+    # Publish message to topic
+    aws_iot.publish(topic, json.dumps(message))
+
+def unsubscribe(client, userdata, topic, pid):
+    # This method is called when the client unsubscribes from a topic.
+    print('Unsubscribed from {0} with PID {1}'.format(topic, pid))
+
+def publish(client, userdata, topic, pid):
+    # This method is called when the client publishes data to a topic.
+    print('Published to {0} with PID {1}'.format(topic, pid))
+
+def message(client, topic, msg):
+    # This method is called when the client receives data from a topic.
+    print("Message from {}: {}".format(topic, msg))
+
+
+# Set AWS Device Certificate
+esp.set_certificate(DEVICE_CERT)
+
+# Set AWS RSA Private Key
+esp.set_private_key(DEVICE_KEY)
+
+# Connect to WiFi
+print("Connecting to WiFi...")
+wifi.connect()
+print("Connected!")
+
+# Set up a new MiniMQTT Client
+client =  MQTT(socket,
+               broker = secrets['broker'],
+               client_id = secrets['client_id'],
+               network_manager = wifi,
+               log=True)
+
+# Initialize AWS IoT MQTT API Client
+aws_iot = MQTT_CLIENT(client)
+
+# Connect callback handlers to AWS IoT MQTT Client
+aws_iot.on_connect = connect
+aws_iot.on_disconnect = disconnect
+aws_iot.on_subscribe = subscribe
+aws_iot.on_unsubscribe = unsubscribe
+aws_iot.on_publish = publish
+aws_iot.on_message = message
+
+print('Attempting to connect to %s'%client.broker)
+aws_iot.connect()
+
+# Pump the message loop forever, all events
+# are handled in their callback handlers
+# while True:
+#   aws_iot.loop()
+
+# Attempt to loop forever and handle network interface
+aws_iot.loop_forever()

requirements.txt

@@ -0,0 +1 @@
+Adafruit-Blinka

setup.py

@@ -0,0 +1,64 @@
+"""A setuptools based setup module.
+
+See:
+https://packaging.python.org/en/latest/distributing.html
+https://github.com/pypa/sampleproject
+"""
+
+from setuptools import setup, find_packages
+# To use a consistent encoding
+from codecs import open
+from os import path
+
+here = path.abspath(path.dirname(__file__))
+
+# Get the long description from the README file
+with open(path.join(here, 'README.rst'), encoding='utf-8') as f:
+    long_description = f.read()
+
+setup(
+    name='adafruit-circuitpython-aws-iot',
+
+    use_scm_version=True,
+    setup_requires=['setuptools_scm'],
+
+    description='Amazon AWS IoT MQTT Client for CircuitPython',
+    long_description=long_description,
+    long_description_content_type='text/x-rst',
+
+    # The project's main homepage.
+    url='https://github.com/adafruit/Adafruit_CircuitPython_AWS_IOT',
+
+    # Author details
+    author='Adafruit Industries',
+    author_email='circuitpython@adafruit.com',
+
+    install_requires=[
+        'Adafruit-Blinka'
+    ],
+
+    # Choose your license
+    license='MIT',
+
+    # See https://pypi.python.org/pypi?%3Aaction=list_classifiers
+    classifiers=[
+        'Development Status :: 3 - Alpha',
+        'Intended Audience :: Developers',
+        'Topic :: Software Development :: Libraries',
+        'Topic :: System :: Hardware',
+        'License :: OSI Approved :: MIT License',
+        'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.4',
+        'Programming Language :: Python :: 3.5',
+    ],
+
+    # What does your project relate to?
+    keywords='adafruit blinka circuitpython micropython aws_iot aws, iot, amazon, mqtt, '
+             'client',
+
+    # You can just specify the packages manually here if your project is
+    # simple. Or you can use find_packages().
+    # TODO: IF LIBRARY FILES ARE A PACKAGE FOLDER,
+    #       CHANGE `py_modules=['...']` TO `packages=['...']`
+    py_modules=['adafruit_aws_iot'],
+)