GitBook: [master] 331 pages modified

firmwareapi/introduction.md

@@ -0,0 +1,15 @@
+# Introduction
+
+This chapter describes modules \(function and class libraries\) that are built into MicroPython. There are a number of categories for the available modules:
+
+* Modules which implement a subset of standard Python functionality and are not intended to be extended by the user.
+* Modules which implement a subset of Python functionality, with a provision for extension by the user \(via Python code\).
+* Modules which implement MicroPython extensions to the Python standard libraries.
+* Modules specific to a particular port and thus not portable.
+
+## Note about the availability of modules and their contents
+
+This documentation in general aspires to describe all modules and functions/classes which are implemented in MicroPython. However, MicroPython is highly configurable, and each port to a particular board/embedded system makes available only a subset of MicroPython libraries. For officially supported ports, there is an effort to either filter out non-applicable items, or mark individual descriptions with “Availability:” clauses describing which ports provide a given feature. With that in mind, please still be warned that some functions/classes in a module \(or even the entire module\) described in this documentation may be unavailable in a particular build of MicroPython on a particular board. The best place to find general information of the availability/non-availability of a particular feature is the “General Information” section which contains information pertaining to a specific port.
+
+Beyond the built-in libraries described in this documentation, many more modules from the Python standard library, as well as further MicroPython extensions to it, can be found in the [micropython-lib](https://github.com/micropython/micropython-lib) repository.
+

firmwareapi/micropython/README.md

@@ -0,0 +1,10 @@
+# MicroPython Modules
+
+The following list contains the standard Python libraries, MicroPython-specific libraries and Pycom specific modules that are available on the Pycom devices.
+
+The standard Python libraries have been "micro-ified" to fit in with the philosophy of MicroPython. They provide the core functionality of that module and are intended to be a drop-in replacement for the standard Python library.
+
+{% hint style="info" %}
+Some modules are available by an u-name, and also by their non-u-name. The non-u-name can be overridden by a file of that name in your package path. For example, `import json` will first search for a file `json.py` or directory `json` and load that package if it's found. If nothing is found, it will fallback to loading the built-in `ujson` module.
+{% endhint %}
+

firmwareapi/micropython/_thread.md

@@ -0,0 +1,86 @@
+# \_thread
+
+This module provides low-level primitives for working with multiple threads \(also called light-weight processes or tasks\) — multiple threads of control sharing their global data space. For synchronisation, simple locks \(also called mutexes or binary semaphores\) are provided.
+
+When a thread specific error occurs a `RuntimeError` exception is raised.
+
+## Quick Usage Example
+
+```python
+import _thread
+import time
+
+def th_func(delay, id):
+    while True:
+        time.sleep(delay)
+        print('Running thread %d' % id)
+
+for i in range(2):
+    _thread.start_new_thread(th_func, (i + 1, i))
+```
+
+## Methods
+
+#### \_thread.start\_new\_thread\(function, args\[, kwargs\]\)
+
+Start a new thread and return its identifier. The thread executes the function with the argument list args \(which must be a tuple\). The optional `kwargs` argument specifies a dictionary of keyword arguments. When the function returns, the thread silently exits. When the function terminates with an unhandled exception, a stack trace is printed and then the thread exits \(but other threads continue to run\).
+
+#### \_thread.exit\(\)
+
+Raise the `SystemExit` exception. When not caught, this will cause the thread to exit silently.
+
+#### \_thread.allocate\_lock\(\)
+
+Return a new lock object. Methods of locks are described below. The lock is initially unlocked.
+
+#### \_thread.get\_ident\(\)
+
+Return the `thread identifier` of the current thread. This is a nonzero integer. Its value has no direct meaning; it is intended as a magic cookie to be used e.g. to index a dictionary of thread-specific data. Thread identifiers may be recycled when a thread exits and another thread is created.
+
+#### \_thread.stack\_size\(\[size\]\)
+
+Return the thread stack size \(in bytes\) used when creating new threads. The optional size argument specifies the stack size to be used for subsequently created threads, and must be `0` \(use platform or configured default\) or a positive integer value of at least `4096` \(4KiB\). 4KiB is currently the minimum supported stack size value to guarantee sufficient stack space for the interpreter itself.
+
+## Objects
+
+#### \_thread.LockType
+
+This is the type of lock objects.
+
+## class Lock
+
+Used for synchronisation between threads
+
+### Methods
+
+Lock objects have the following methods:
+
+#### lock.acquire\(waitflag=1, timeout=-1\)
+
+Without any optional argument, this method acquires the lock unconditionally, if necessary waiting until it is released by another thread \(only one thread at a time can acquire a lock — that’s their reason for existence\).
+
+If the integer `waitflag` argument is present, the action depends on its value: if it is zero, the lock is only acquired if it can be acquired immediately without waiting, while if it is nonzero, the lock is acquired unconditionally as above.
+
+If the floating-point timeout argument is present and positive, it specifies the maximum wait time in seconds before returning. A negative timeout argument specifies an unbounded wait. You cannot specify a timeout if `waitflag` is zero.
+
+The return value is `True` if the lock is acquired successfully, `False` if not.
+
+#### lock.release\(\)
+
+Releases the lock. The lock must have been acquired earlier, but not necessarily by the same thread.
+
+#### lock.locked\(\)
+
+Return the status of the lock: `True` if it has been acquired by some thread, `False` if not.
+
+In addition to these methods, lock objects can also be used via the with statement, e.g.:
+
+```python
+import _thread
+
+a_lock = _thread.allocate_lock()
+
+with a_lock:
+    print("a_lock is locked while this executes")
+```
+

firmwareapi/micropython/array.md

@@ -0,0 +1,22 @@
+# array
+
+See [Python array](https://docs.python.org/3/library/array.html) for more information.
+
+Supported format codes: `b, B, h, H, i, I, l, L, q, Q, f, d` \(the latter 2 depending on the floating-point support\).
+
+## Classes
+
+#### class array.array\(typecode\[, iterable\]\)
+
+Create array with elements of given type. Initial contents of the array are given by an iterable. If it is not provided, an empty array is created.
+
+## Methods
+
+#### array.append\(val\)
+
+Append new element to the end of array, growing it.
+
+#### array.extend\(iterable\)
+
+Append new elements as contained in an iterable to the end of array, growing it.
+

firmwareapi/micropython/builtin.md

@@ -0,0 +1,126 @@
+# Builtin
+
+All builtin functions are described here. They are also available via [builtins](builtin.md) module.
+
+abs\(\)
+
+all\(\)
+
+any\(\)
+
+bin\(\)
+
+class bool
+
+class bytearray
+
+class bytes
+
+callable\(\)
+
+chr\(\)
+
+class method\(\)
+
+compile\(\)
+
+class complex
+
+class dict
+
+dir\(\)
+
+divmod\(\)
+
+enumerate\(\)
+
+eval\(\)
+
+exec\(\)
+
+filter\(\)
+
+class float
+
+class frozenset
+
+getattr\(\)
+
+globals\(\)
+
+hasattr\(\)
+
+hash\(\)
+
+hex\(\)
+
+id\(\)
+
+input\(\)
+
+class int
+
+isinstance\(\)
+
+issubclass\(\)
+
+iter\(\)
+
+len\(\)
+
+class list
+
+locals\(\)
+
+map\(\)
+
+max\(\)
+
+class memoryview
+
+min\(\)
+
+next\(\)
+
+class object
+
+oct\(\)
+
+open\(\)
+
+ord\(\)
+
+pow\(\)
+
+print\(\)
+
+property\(\)
+
+range\(\)
+
+repr\(\)
+
+reversed\(\)
+
+round\(\)
+
+class set
+
+setattr\(\)
+
+sorted\(\)
+
+staticmethod\(\)
+
+class str
+
+sum\(\)
+
+super\(\)
+
+class tuple
+
+type\(\)
+
+zip\(\)
+

firmwareapi/micropython/cmath.md

@@ -0,0 +1,47 @@
+# cmath
+
+The `cmath` module provides some basic mathematical functions for working with complex numbers. Floating point support required for this module.
+
+## Methods
+
+#### cmath.cos\(z\)
+
+Return the cosine of `z`.
+
+#### cmath.exp\(z\)
+
+Return the exponential of `z`.
+
+#### cmath.log\(z\)
+
+Return the natural logarithm of `z`. The branch cut is along the negative real axis.
+
+#### cmath.log10\(z\)
+
+Return the base-10 logarithm of `z`. The branch cut is along the negative real axis.
+
+#### cmath.phase\(z\)
+
+Returns the phase of the number `z`, in the range \(-pi, +pi\).
+
+#### cmath.polar\(z\)
+
+Returns, as a tuple, the polar form of `z`.
+
+#### cmath.rect\(r, phi\)
+
+Returns the complex number with modulus `r` and phase `phi`.
+
+#### cmath.sin\(z\)
+
+Return the sine of `z`.
+
+#### cmath.sqrt\(z\)
+
+Return the square-root of `z`.
+
+## Constants
+
+* `cmath.e`: Base of the natural logarithm
+* `cmath.pi`: The ratio of a circle’s circumference to its diameter
+

firmwareapi/micropython/gc.md

@@ -0,0 +1,24 @@
+# gc
+
+## Methods
+
+#### gc.enable\(\)
+
+Enable automatic garbage collection.
+
+#### gc.disable\(\)
+
+Disable automatic garbage collection. Heap memory can still be allocated, and garbage collection can still be initiated manually using `gc.collect()`.
+
+#### gc.collect\(\)
+
+Run a garbage collection.
+
+#### gc.mem\_alloc\(\)
+
+Return the number of bytes of heap RAM that are allocated.
+
+#### gc.mem\_free\(\)
+
+Return the number of bytes of available heap RAM.
+

firmwareapi/micropython/math.md

@@ -0,0 +1,163 @@
+# math
+
+The math module provides some basic mathematical functions for working with floating-point numbers. Floating point support required for this module.
+
+## Methods
+
+#### math.acos\(x\)
+
+Return the inverse cosine of `x`.
+
+#### math.acosh\(x\)
+
+Return the inverse hyperbolic cosine of `x`.
+
+#### math.asin\(x\)
+
+Return the inverse sine of `x`.
+
+#### math.asinh\(x\)
+
+Return the inverse hyperbolic sine of `x`.
+
+#### math.atan\(x\)
+
+Return the inverse tangent of `x`.
+
+#### math.atan2\(y, x\)
+
+Return the principal value of the inverse tangent of `y/x`.
+
+#### math.atanh\(x\)
+
+Return the inverse hyperbolic tangent of `x`.
+
+#### math.ceil\(x\)
+
+Return an integer, being x rounded towards positive infinity.
+
+#### math.copysign\(x, y\)
+
+Return x with the sign of `y`.
+
+#### math.cos\(x\)
+
+Return the cosine of `x`.
+
+#### math.cosh\(x\)
+
+Return the hyperbolic cosine of `x`.
+
+#### math.degrees\(x\)
+
+Return radians `x` converted to degrees.
+
+#### math.erf\(x\)
+
+Return the error function of `x`.
+
+#### math.erfc\(x\)
+
+Return the complementary error function of `x`.
+
+#### math.exp\(x\)
+
+Return the exponential of `x`.
+
+#### math.expm1\(x\)
+
+Return `exp(x) - 1`.
+
+#### math.fabs\(x\)
+
+Return the absolute value of `x`.
+
+#### math.floor\(x\)
+
+Return an integer, being `x` rounded towards negative infinity.
+
+#### math.fmod\(x, y\)
+
+Return the remainder of `x/y`.
+
+#### math.frexp\(x\)
+
+Decomposes a floating-point number into its mantissa and exponent. The returned value is the tuple `(m, e)` such that `x == m * 2**e` exactly. If `x == 0` then the function returns `(0.0, 0)`, otherwise the relation `0.5 <= abs(m) < 1` holds.
+
+#### math.gamma\(x\)
+
+Return the gamma function of `x`.
+
+#### math.isfinite\(x\)
+
+Return `True` if `x` is finite.
+
+#### math.isinf\(x\)
+
+Return `True` if `x` is infinite.
+
+#### math.isnan\(x\)
+
+Return `True` if `x` is not-a-number
+
+#### math.ldexp\(x, exp\)
+
+Return `x * (2**exp)`.
+
+#### math.lgamma\(x\)
+
+Return the natural logarithm of the gamma function of `x`.
+
+#### math.log\(x\)
+
+Return the natural logarithm of `x`.
+
+#### math.log10\(x\)
+
+Return the base-10 logarithm of `x`.
+
+#### math.log2\(x\)
+
+Return the base-2 logarithm of `x`.
+
+#### math.modf\(x\)
+
+Return a tuple of two floats, being the fractional and integral parts of `x`. Both return values have the same sign as `x`.
+
+#### math.pow\(x, y\)
+
+Returns `x` to the power of `y`.
+
+#### math.radians\(x\)
+
+Return degrees `x` converted to radians.
+
+#### math.sin\(x\)
+
+Return the sine of `x`.
+
+#### math.sinh\(x\)
+
+Return the hyperbolic sine of `x`.
+
+#### math.sqrt\(x\)
+
+Return the square root of `x`.
+
+#### math.tan\(x\)
+
+Return the tangent of `x`.
+
+#### math.tanh\(x\)
+
+Return the hyperbolic tangent of `x`.
+
+#### math.trunc\(x\)
+
+Return an integer, being `x` rounded towards `0`.
+
+## Constants
+
+* `math.e`: Base of the natural logarithm
+* `math.pi`: The ratio of a circle’s circumference to its diameter
+

firmwareapi/micropython/micropython.md

@@ -0,0 +1,59 @@
+# micropython
+
+## Methods
+
+#### micropython.alloc\_emergency\_exception\_buf\(size\)
+
+Allocate size bytes of RAM for the emergency exception buffer \(a good size is around 100 bytes\). The buffer is used to create exceptions in cases when normal RAM allocation would fail \(eg within an interrupt handler\) and therefore give useful traceback information in these situations.
+
+A good way to use this function is to place it at the start of a main script \(e.g. `boot.py` or `main.py`\) and then the emergency exception buffer will be active for all the code following it.
+
+#### micropython.const\(expr\)
+
+Used to declare that the expression is a constant so that the compile can optimise it. The use of this function should be as follows:
+
+```python
+from micropython import const  
+
+CONST_X = const(123)
+CONST_Y = const(2 * CONST_X + 1)
+```
+
+Constants declared this way are still accessible as global variables from outside the module they are declared in. On the other hand, if a constant begins with an underscore then it is hidden, it is not available as a global variable, and does not take up any memory during execution.
+
+This const function is recognised directly by the MicroPython parser and is provided as part of the `micropython` module mainly so that scripts can be written which run under both CPython and MicroPython, by following the above pattern.
+
+#### micropython.opt\_level\(\[level\]\)
+
+If `level` is given then this function sets the optimisation level for subsequent compilation of scripts, and returns `None`. Otherwise it returns the current optimisation level.
+
+#### micropython.mem\_info\(\[verbose\]\)
+
+Print information about currently used memory. If the `verbose` argument is given then extra information is printed.
+
+The information that is printed is implementation dependent, but currently includes the amount of stack and heap used. In verbose mode it prints out the entire heap indicating which blocks are used and which are free.
+
+#### micropython.qstr\_info\(\[verbose\]\)
+
+Print information about currently interned strings. If the `verbose` argument is given then extra information is printed.
+
+The information that is printed is implementation dependent, but currently includes the number of interned strings and the amount of RAM they use. In verbose mode it prints out the names of all RAM-interned strings.
+
+#### micropython.stack\_use\(\)
+
+Return an integer representing the current amount of stack that is being used. The absolute value of this is not particularly useful, rather it should be used to compute differences in stack usage at different points.
+
+#### micropython.heap\_lock\(\)
+
+#### micropython.heap\_unlock\(\)
+
+Lock or unlock the heap. When locked no memory allocation can occur and a `MemoryError` will be raised if any heap allocation is attempted.
+
+These functions can be nested, i.e. `heap_lock()` can be called multiple times in a row and the lock-depth will increase, and then `heap_unlock()` must be called the same number of times to make the heap available again.
+
+#### micropython.kbd\_intr\(chr\)
+
+Set the character that will raise a `KeyboardInterrupt` exception. By default this is set to 3 during script execution, corresponding to `Ctrl-C`. Passing `-1` to this function will disable capture of `Ctrl-C`, and passing `3` will restore it.
+
+This function can be used to prevent the capturing of `Ctrl-C` on the incoming stream of characters that is usually used for the REPL, in case that stream is used for other purposes.
+

firmwareapi/micropython/select.md

@@ -0,0 +1,49 @@
+# select
+
+This module provides functions to wait for events on streams \(select streams which are ready for operations\).
+
+## Pyboard specifics
+
+Polling is an efficient way of waiting for read/write activity on multiple objects. Current objects that support polling are: `pyb.UART`, `pyb.USB_VCP`.
+
+## Methods
+
+#### select.poll\(\)
+
+Create an instance of the `Poll` class.
+
+#### select.select\(rlist, wlist, xlist\[, timeout\]\)
+
+Wait for activity on a set of objects.
+
+This function is provided for compatibility and is not efficient. Usage of `Poll` is recommended instead.
+
+## class Poll
+
+### Methods
+
+#### poll.register\(obj\[, eventmask\]\)
+
+Register `obj` for polling. `eventmask` is logical OR of:
+
+* `select.POLLIN` - data available for reading
+* `select.POLLOUT` - more data can be written
+* `select.POLLERR` - error occurred
+* `select.POLLHUP` - end of stream/connection termination detected
+
+  `eventmask` defaults to `select.POLLIN | select.POLLOUT`.
+
+#### poll.unregister\(obj\)
+
+Unregister `obj` from polling.
+
+#### poll.modify\(obj, eventmask\)
+
+Modify the `eventmask` for `obj`.
+
+#### poll.poll\(\[timeout\]\)
+
+Wait for at least one of the registered objects to become ready. Returns list of \(`obj`, `event`, ...\) tuples, `event` element specifies which events happened with a stream and is a combination of `select.POLL*` constants described above. There may be other elements in tuple, depending on a platform and version, so don’t assume that its size is 2. In case of timeout, an empty list is returned.
+
+Timeout is in milliseconds.
+

firmwareapi/micropython/sys.md

@@ -0,0 +1,62 @@
+# sys
+
+## Methods
+
+#### sys.exit\(retval=0\)
+
+Terminate current program with a given exit code. Underlyingly, this function raise as `SystemExit` exception. If an argument is given, its value given as an argument to `SystemExit`.
+
+#### sys.print\_exception\(exc, file=sys.stdout\)
+
+Print exception with a traceback to a file-like object file \(or `sys.stdout` by default\).
+
+{% hint style="info" %}
+**Difference to CPython**
+
+This is simplified version of a function which appears in the traceback module in CPython. Unlike `traceback.print_exception()`, this function takes just exception value instead of exception type, exception value, and traceback object; file argument should be positional; further arguments are not supported. CPython-compatible traceback module can be found in `micropython-lib`.
+{% endhint %}
+
+## Constants
+
+* `sys.argv`: A mutable list of arguments the current program was started with.
+* `sys.byteorder`: The byte order of the system \("little" or "big"\).
+* `sys.implementation`: Object with information about the current Python implementation. For MicroPython, it has following attributes:
+  * _name_ - string "micropython"
+  * _version_ - tuple \(major, minor, micro\), e.g. \(1, 7, 0\)
+
+    This object is the recommended way to distinguish MicroPython from other Python implementations \(note that it still may not exist in the very minimal ports\).
+
+{% hint style="info" %}
+**Difference to CPython**
+
+CPython mandates more attributes for this object, but the actual useful bare minimum is implemented in MicroPython.
+{% endhint %}
+
+* `sys.maxsize`: Maximum value which a native integer type can hold on the current platform, or maximum value representable by MicroPython integer type, if it’s smaller than platform max value \(that is the case for MicroPython ports without long int support\).
+
+This attribute is useful for detecting "bitness" of a platform \(32-bit vs 64-bit, etc.\). It’s recommended to not compare this attribute to some value directly, but instead count number of bits in it:
+
+```python
+bits = 0
+v = sys.maxsize
+while v:
+    bits += 1
+    v >>= 1
+if bits > 32:
+    # 64-bit (or more) platform
+else:
+    # 32-bit (or less) platform
+    # Note that on 32-bit platform, value of bits may be less than 32
+    # (e.g. 31) due to peculiarities described above, so use "> 16",
+    # "> 32", "> 64" style of comparisons.
+```
+
+* `sys.modules`: Dictionary of loaded modules. On some ports, it may not include builtin modules.
+* `sys.path`: A mutable list of directories to search for imported modules.
+* `sys.platform`: The platform that MicroPython is running on. For OS/RTOS ports, this is usually an identifier of the OS, e.g. `linux`. For baremetal ports, it is an identifier of a board, e.g. `pyboard` for the original MicroPython reference board. It thus can be used to distinguish one board from another. If you need to check whether your program runs on MicroPython \(vs other Python implementation\), use `sys.implementation` instead.
+* `sys.stderr`: Standard error stream.
+* `sys.stdin`: Standard input stream.
+* `sys.stdout`: Standard output stream.
+* `sys.version`: Python language version that this implementation conforms to, as a string.
+* `sys.version_info`: Python language version that this implementation conforms to, as a tuple of ints.
+

firmwareapi/micropython/ubinascii.md

@@ -0,0 +1,28 @@
+# ubinascii
+
+This module implements conversions between binary data and various encodings of it in ASCII form \(in both directions\).
+
+## Methods
+
+#### ubinascii.hexlify\(data\[, sep\]\)
+
+Convert binary data to hexadecimal representation. Returns bytes string.
+
+{% hint style="info" %}
+**Difference to CPython**
+
+If additional argument, `sep` is supplied, it is used as a separator between hexadecimal values.
+{% endhint %}
+
+#### ubinascii.unhexlify\(data\)
+
+Convert hexadecimal data to binary representation. Returns bytes string. \(i.e. inverse of `hexlify`\)
+
+#### ubinascii.a2b\_base64\(data\)
+
+Convert Base64-encoded data to binary representation. Returns bytes string.
+
+#### ubinascii.b2a\_base64\(data\)
+
+Encode binary data in Base64 format. Returns string.
+

firmwareapi/micropython/ucrypto.md

@@ -0,0 +1,22 @@
+# ucrypto
+
+This module provides native support for cryptographic algorithms. It’s loosely based on PyCrypto.
+
+## Classes
+
+* [class AES](../pycom/aes.md) - Advanced Encryption Standard
+
+## **Methods**
+
+#### crypto.getrandbits\(bits\)
+
+Returns a bytes object filled with random bits obtained from the hardware random number generator.
+
+According to the **ESP32 Technical Reference Manual**, such bits "... can be used as the basis for cryptographical operations". "These true random numbers are generated based on the noise in the Wi-Fi/BT RF system. When Wi-Fi and BT are disabled, the random number generator will give out pseudo-random numbers."
+
+The parameter `bits` is rounded upwards to the nearest multiple of 32 bits.
+
+{% hint style="danger" %}
+Cryptography is not a trivial business. Doing things the wrong way could quickly result in decreased or no security. Please document yourself in the subject if you are depending on encryption to secure important information.
+{% endhint %}
+

firmwareapi/micropython/uctypes.md

@@ -0,0 +1,138 @@
+# uctypes
+
+This module implements "foreign data interface" for MicroPython. The idea behind it is similar to CPython’s `ctypes` modules, but the actual API is different, streamlined and optimised for small size. The basic idea of the module is to define data structure layout with about the same power as the C language allows, and the access it using familiar dot-syntax to reference sub-fields.
+
+{% hint style="info" %}
+Module ustruct Standard Python way to access binary data structures \(doesn’t scale well to large and complex structures\).
+{% endhint %}
+
+## Defining Structure Layout
+
+Structure layout is defined by a "descriptor" - a Python dictionary which encodes field names as keys and other properties required to access them as associated values. Currently, `uctypes` requires explicit specification of offsets for each field. Offset are given in bytes from a structure start.
+
+Following are encoding examples for various field types:
+
+* Scalar types:
+
+```python
+"field_name": uctypes.UINT32 | 0
+```
+
+In other words, value is scalar type identifier OR-ed with field offset \(in bytes\) from the start of the structure.
+
+* Recursive structures:
+
+```python
+"sub": (2, {
+    "b0": uctypes.UINT8 | 0,
+    "b1": uctypes.UINT8 | 1,
+})
+```
+
+I.e. value is a 2-tuple, first element of which is offset, and second is a structure descriptor dictionary \(note: offsets in recursive descriptors are relative to a structure it defines\).
+
+* Arrays of Primitive Types:
+
+```python
+"arr": (uctypes.ARRAY | 0, uctypes.UINT8 | 2),
+```
+
+I.e. value is a 2-tuple, first element of which is ARRAY flag OR-ed with offset, and second is scalar element type OR-ed number of elements in array.
+
+* Arrays of Aggregate Types:
+
+```python
+"arr2": (uctypes.ARRAY | 0, 2, {"b": uctypes.UINT8 | 0}),
+```
+
+I.e. value is a 3-tuple, first element of which is ARRAY flag OR-ed with offset, second is a number of elements in array, and third is descriptor of element type.
+
+* Pointer to a primitive type:
+
+```python
+"ptr": (uctypes.PTR | 0, uctypes.UINT8),
+```
+
+I.e. value is a 2-tuple, first element of which is PTR flag OR-ed with offset, and second is scalar element type.
+
+* Pointer to an aggregate type:
+
+```python
+"ptr2": (uctypes.PTR | 0, {"b": uctypes.UINT8 | 0}),
+```
+
+I.e. value is a 2-tuple, first element of which is PTR flag OR-ed with offset, second is descriptor of type pointed to.
+
+* Bitfields:
+
+```python
+"bitf0": uctypes.BFUINT16 | 0 | 0 << uctypes.BF_POS | 8 << uctypes.BF_LEN,
+```
+
+I.e. value is type of scalar value containing given bitfield \(typenames are similar to scalar types, but prefixes with "BF"\), OR-ed with offset for scalar value containing the bitfield, and further OR-ed with values for bit offset and bit length of the bitfield within scalar value, shifted by BF\_POS and BF\_LEN positions, respectively. Bitfield position is counted from the least significant bit, and is the number of right-most bit of a field \(in other words, it’s a number of bits a scalar needs to be shifted right to extra the bitfield\).
+
+In the example above, first `UINT16` value will be extracted at offset 0 \(this detail may be important when accessing hardware registers, where particular access size and alignment are required\), and then bitfield whose rightmost bit is least-significant bit of this `UINT16`, and length is 8 bits, will be extracted - effectively, this will access least-significant byte of `UINT16`.
+
+Note that bitfield operations are independent of target byte endianness, in particular, example above will access least-significant byte of `UINT16` in both little- and big-endian structures. But it depends on the least significant bit being numbered 0. Some targets may use different numbering in their native ABI, but `uctypes` always uses normalised numbering described above.
+
+## Module Contents
+
+#### class uctypes.struct\(addr, descriptor, layout\_type=NATIVE\)
+
+Instantiate a "foreign data structure" object based on structure address in memory, descriptor \(encoded as a dictionary\), and layout type \(see below\).
+
+#### uctypes.LITTLE\_ENDIAN
+
+Layout type for a little-endian packed structure. \(Packed means that every field occupies exactly as many bytes as defined in the descriptor, i.e. the alignment is 1\).
+
+#### uctypes.BIG\_ENDIAN
+
+Layout type for a big-endian packed structure.
+
+#### uctypes.NATIVE
+
+Layout type for a native structure - with data endianness and alignment conforming to the ABI of the system on which MicroPython runs.
+
+#### uctypes.sizeof\(struct\)
+
+Return size of data structure in bytes. Argument can be either structure class or specific instantiated structure object \(or its aggregate field\).
+
+#### uctypes.addressof\(obj\)
+
+Return address of an object. Argument should be bytes, `bytearray` or other object supporting buffer protocol \(and address of this buffer is what actually returned\).
+
+#### uctypes.bytes\_at\(addr, size\)
+
+Capture memory at the given address and size as bytes object. As bytes object is immutable, memory is actually duplicated and copied into bytes object, so if memory contents change later, created object retains original value.
+
+#### uctypes.bytearray\_at\(addr, size\)
+
+Capture memory at the given address and size as `bytearray` object. Unlike `bytes_at()` function above, memory is captured by reference, so it can be both written too, and you will access current value at the given memory address.
+
+## Structure Descriptors and Instantiating Structure Objects
+
+Given a structure descriptor dictionary and its layout type, you can instantiate a specific structure instance at a given memory address using uctypes.struct\(\) constructor. Memory address usually comes from following sources:
+
+* Predefined address, when accessing hardware registers on a baremetal system. Lookup these addresses in datasheet for a particular MCU/SoC.
+* As a return value from a call to some FFI \(Foreign Function Interface\) function.
+* From uctypes.addressof\(\), when you want to pass arguments to an FFI function, or alternatively, to access some data for I/O \(for example, data read from a file or network socket\).
+
+## Structure objects
+
+Structure objects allow accessing individual fields using standard dot notation: `my_struct.substruct1.field1`. If a field is of scalar type, getting it will produce a primitive value \(Python integer or float\) corresponding to the value contained in a field. A scalar field can also be assigned to.
+
+If a field is an array, its individual elements can be accessed with the standard subscript operator `[]` - both read and assigned to.
+
+If a field is a pointer, it can be dereferenced using `[0]` syntax \(corresponding to C `*` operator, though `[0]` works in C too\). Subscripting a pointer with other integer values but 0 are supported too, with the same semantics as in C.
+
+Summing up, accessing structure fields generally follows C syntax, except for pointer dereference, when you need to use `[0]` operator instead of `*`.
+
+## Limitations
+
+Accessing non-scalar fields leads to allocation of intermediate objects to represent them. This means that special care should be taken to layout a structure which needs to be accessed when memory allocation is disabled \(e.g. from an interrupt\). The recommendations are:
+
+* Avoid nested structures. For example, instead of `mcu_registers.peripheral_a.register1`, define separate layout descriptors for each peripheral, to be accessed as `peripheral_a.register1`.
+* Avoid other non-scalar data, like array. For example, instead of `peripheral_a.register[0]` use `peripheral_a.register0`.
+
+Note that these recommendations will lead to decreased readability and conciseness of layouts, so they should be used only if the need to access structure fields without allocation is anticipated \(it’s even possible to define 2 parallel layouts - one for normal usage, and a restricted one to use when memory allocation is prohibited\).
+

firmwareapi/micropython/uhashlib.md

@@ -0,0 +1,44 @@
+# uhashlib
+
+This module implements binary data hashing algorithms. MD5 and SHA are supported. By limitations in the hardware, only one active hashing operation is supported at a time.
+
+## Constructors
+
+#### class uhashlib.md5\(\[data\]\)
+
+Create a MD5 hasher object and optionally feed data into it.
+
+#### class uhashlib.sha1\(\[data\]\)
+
+Create a SHA-1 hasher object and optionally feed data into it.
+
+#### class uhashlib.sha224\(\[data\]\)
+
+Create a SHA-224 hasher object and optionally feed data into it.
+
+#### class uhashlib.sha256\(\[data\]\)
+
+Create a SHA-256 hasher object and optionally feed data into it.
+
+#### class uhashlib.sha384\(\[data\]\)
+
+Create a SHA-384 hasher object and optionally feed data into it.
+
+#### class uhashlib.sha512\(\[data\]\)
+
+Create a SHA-512 hasher object and optionally feed data into it.
+
+## Methods
+
+#### hash.update\(data\)
+
+Feed more binary data into hash.
+
+#### hash.digest\(\)
+
+Return hash for all data passed through hash, as a bytes object. After this method is called, more data cannot be fed into hash any longer.
+
+#### hash.hexdigest\(\)
+
+This method is NOT implemented. Use `ubinascii.hexlify(hash.digest())` to achieve a similar effect.
+

firmwareapi/micropython/ujson.md

@@ -0,0 +1,18 @@
+# ujson
+
+This modules allows to convert between Python objects and the JSON data format.
+
+## Methods
+
+#### ujson.dumps\(obj\)
+
+Return `obj` represented as a JSON string.
+
+#### ujson.loads\(str\)
+
+Parse the JSON `str` and return an object. Raises `ValueError` if the string is not correctly formed.
+
+#### ujson.load\(fp\)
+
+Parse contents of `fp` \(a `.read()`-supporting file-like object containing a JSON document\). Raises `ValueError` if the content is not correctly formed.
+

firmwareapi/micropython/uos.md

@@ -0,0 +1,101 @@
+# uos
+
+The `uos` module contains functions for filesystem access and `urandom` function.
+
+## Port Specifics
+
+The filesystem has `/` as the root directory and the available physical drives are accessible from here. They are currently:
+
+* `/flash` – the internal flash filesystem
+* `/sd` – the SD card \(if it exists\)
+
+## Methods
+
+#### uos.uname\(\)
+
+Return information about the system, firmware release version, and MicroPython interpreter version.
+
+#### uos.chdir\(path\)
+
+Change current directory.
+
+#### uos.getcwd\(\)
+
+Get the current directory.
+
+#### uos.listdir\(\[dir\]\)
+
+With no argument, list the current directory. Otherwise list the given directory.
+
+#### uos.mkdir\(path\)
+
+Create a new directory.
+
+#### uos.remove\(path\)
+
+Remove a file.
+
+#### uos.rmdir\(path\)
+
+Remove a directory.
+
+#### uos.rename\(old\_path, new\_path\)
+
+Rename a file.
+
+#### uos.stat\(path\)
+
+Get the status of a file or directory.
+
+The return value is a tuple with the following 10 values, in order:
+
+* `st_mode`: protection bits.
+* `st_ino`: `inode` number. \(not implemented, returns 0\)
+* `st_dev`: device. \(not implemented, returns 0\)
+* `st_nlink`: number of hard links. \(not implemented, returns 0\)
+* `st_uid`: user id of owner. \(not implemented, returns 0\)
+* `st_gid`: group id of owner. \(not implemented, returns 0\)
+* `st_size`: size of file in bytes.
+* `st_atime`: time of most recent access.
+* `st_mtime`: time of most recent content modification.
+* `st_ctime`: time of most recent metadata change.
+
+#### uos.getfree\(path\)
+
+Returns the free space \(in KiB\) in the drive specified by path.
+
+#### uos.sync\(\)
+
+Sync all filesystems.
+
+#### uos.urandom\(n\)
+
+Return a bytes object with n random bytes.
+
+#### uos.unlink\(path\)
+
+Alias for the `remove()` method.
+
+#### uos.mount\(block\_device, mount\_point, \* , readonly=False\)
+
+Mounts a block device \(like an SD object\) in the specified mount point. Example:
+
+```python
+os.mount(sd, '/sd')
+uos.unmount(path)
+```
+
+Unmounts a previously mounted block device from the given path.
+
+#### uos.mkfs\(block\_device or path\)
+
+Formats the specified path, must be either `/flash` or `/sd`. A block device can also be passed like an SD object before being mounted.
+
+#### uos.dupterm\(stream\_object\)
+
+Duplicate the terminal \(the REPL\) on the passed stream-like object. The given object must at least implement the `read()` and `write()` methods.
+
+## Constants
+
+* `uos.sep`: Separation character used in paths
+

firmwareapi/micropython/ure.md

@@ -0,0 +1,57 @@
+# ure
+
+This module implements regular expression operations. Regular expression syntax supported is a subset of CPython re module \(and actually is a subset of POSIX extended regular expressions\).
+
+Supported operators are:
+
+`.` Match any character. `[]` Match set of characters. Individual characters and ranges are supported.
+
+```text
+^
+$
+?
+*
++
+??
+*?
++?
+```
+
+Counted repetitions `({m,n})`, more advanced assertions, named groups, etc. are not supported.
+
+## Methods
+
+#### ure.compile\(regex\)
+
+Compile regular expression, return `regex object`.
+
+#### ure.match\(regex, string\)
+
+Match regex against `string`. Match always happens from starting position in a string.
+
+#### ure.search\(regex, string\)
+
+Search regex in a string. Unlike match, this will search string for first position which matches regex \(which still may be 0 if regex is anchored\).
+
+#### ure.DEBUG
+
+Flag value, display debug information about compiled expression.
+
+## Regex objects
+
+Compiled regular expression. Instances of this class are created using `ure.compile()`.
+
+#### regex.match\(string\)
+
+#### regex.search\(string\)
+
+#### regex.split\(string, max\_split=-1\)
+
+## Match objects
+
+Match objects as returned by `match()` and `search()` methods.
+
+#### match.group\(\[index\]\)
+
+Only numeric groups are supported.
+

firmwareapi/micropython/usocket.md

@@ -0,0 +1,148 @@
+# usocket
+
+This module provides access to the BSD socket interface.
+
+See corresponding CPython module for comparison.
+
+## Socket Address Format\(s\)
+
+Functions below which expect a network address, accept it in the format of `(ipv4_address, port)`, where `ipv4_address` is a string with dot-notation numeric IPv4 address, e.g. `8.8.8.8`, and port is integer port number in the range 1-65535. Note the domain names are not accepted as `ipv4_address`, they should be resolved first using `socket.getaddrinfo()`.
+
+## Methods
+
+#### socket.socket\(socket.AF\_INET, socket.SOCK\_STREAM, socket.IPPROTO\_TCP\)
+
+Create a new socket using the given address family, socket type and protocol number.
+
+#### socket.getaddrinfo\(host, port\)
+
+Translate the host/port argument into a sequence of 5-tuples that contain all the necessary arguments for creating a socket connected to that service. The list of 5-tuples has following structure:
+
+`(family, type, proto, canonname, sockaddr)` The following example shows how to connect to a given url:
+
+```python
+s = socket.socket()
+s.connect(socket.getaddrinfo('www.micropython.org', 80)[0][-1])
+```
+
+## Exceptions
+
+`socket.error`, `socket.timeout`
+
+## Constants
+
+* Family types: `socket.AF_INET`, `socket.AF_LORA`
+* Socket types: `socket.SOCK_STREAM`, `socket.SOCK_DGRAM`, `socket.SOCK_RAW`
+* Socket protocols: `socket.IPPROTO_UDP`, `socket.IPPROTO_TCP`
+* Socket options layers: `socket.SOL_SOCKET`, `socket.SOL_LORA`, `socket.SOL_SIGFOX`
+* IP socket options: `socket.SO_REUSEADDR`
+* LoRa socket options: `socket.SO_CONFIRMED`, `socket.SO_DR`
+* Sigfox socket options: `socket.SO_RX`, `socket.SO_TX_REPEAT`, `socket.SO_OOB`, `socket.SO_BIT`
+
+## class Socket
+
+### Methods
+
+#### socket.close\(\)
+
+Mark the socket closed. Once that happens, all future operations on the socket object will fail. The remote end will receive no more data \(after queued data is flushed\).
+
+Sockets are automatically closed when they are garbage-collected, but it is recommended to `close()` them explicitly, or to use a with statement around them.
+
+#### socket.bind\(address\)
+
+Bind the `socket` to `address`. The socket must not already be bound. The `address` parameter must be a tuple containing the IP address and the port.
+
+{% hint style="info" %}
+In the case of LoRa sockets, the address parameter is simply an integer with the port number, for instance: `s.bind(1)`
+{% endhint %}
+
+#### socket.listen\(\[backlog\]\)
+
+Enable a server to accept connections. If backlog is specified, it must be at least 0 \(if it’s lower, it will be set to 0\); and specifies the number of unaccepted connections that the system will allow before refusing new connections. If not specified, a default reasonable value is chosen.
+
+#### socket.accept\(\)
+
+Accept a connection. The socket must be bound to an address and listening for connections. The return value is a pair `(conn, address)` where `conn` is a new socket object usable to send and receive data on the connection, and `address` is the address bound to the socket on the other end of the connection.
+
+#### socket.connect\(address\)
+
+Connect to a remote socket at `address`.
+
+#### socket.send\(bytes\)
+
+Send data to the socket. The socket must be connected to a remote socket.
+
+#### socket.sendall\(bytes\)
+
+Alias of `socket.send(bytes)`.
+
+#### socket.recv\(bufsize\)
+
+Receive data from the socket. The return value is a bytes object representing the data received. The maximum amount of data to be received at once is specified by `bufsize`.
+
+#### socket.sendto\(bytes, address\)
+
+Send data to the socket. The socket should not be connected to a remote socket, since the destination socket is specified by address.
+
+#### socket.recvfrom\(bufsize\)
+
+Receive data from the socket. The return value is a pair `(bytes, address)` where `bytes` is a bytes object representing the data received and `address` is the address of the socket sending the data.
+
+#### socket.setsockopt\(level, optname, value\)
+
+Set the value of the given socket option. The needed symbolic constants are defined in the socket module \(`SO_*` etc.\). The value can be an integer or a bytes-like object representing a buffer.
+
+#### socket.settimeout\(value\)
+
+Set a timeout on blocking socket operations. The value argument can be a nonnegative floating point number expressing seconds, or `None`. If a non-zero value is given, subsequent socket operations will raise a timeout exception if the timeout period value has elapsed before the operation has completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket is put in blocking mode.
+
+#### socket.setblocking\(flag\)
+
+Set blocking or non-blocking mode of the socket: if flag is false, the socket is set to non-blocking, else to blocking mode.
+
+This method is a shorthand for certain `settimeout()` calls:
+
+```python
+sock.setblocking(True) is equivalent to sock.settimeout(None)
+sock.setblocking(False) is equivalent to sock.settimeout(0.0)
+```
+
+#### socket.makefile\(mode='rb'\)
+
+Return a file object associated with the socket. The exact returned type depends on the arguments given to makefile\(\). The support is limited to binary modes only \(`rb` and `wb`\). CPython’s arguments: `encoding`, `errors`, and `newline` are not supported.
+
+The socket must be in blocking mode; it can have a timeout, but the file object’s internal buffer may end up in a inconsistent state if a timeout occurs.
+
+{% hint style="info" %}
+**Difference to CPython**
+
+Closing the file object returned by `makefile()` **WILL** close the original socket as well.
+{% endhint %}
+
+#### socket.read\(size\)
+
+Read up to size bytes from the socket. Return a bytes object. If `size` is not given, it behaves just like [`socket.readall()`](usocket.md#socket-readall), see below.
+
+#### socket.readall\(\)
+
+Read all data available from the socket until EOF. This function will not return until the socket is closed.
+
+#### socket.readinto\(buf\[, nbytes\]\)
+
+Read bytes into the `buf`. If `nbytes` is specified then read at most that many bytes. Otherwise, read at most `len(buf)` bytes.
+
+Return value: number of bytes read and stored into `buf`.
+
+#### socket.readline\(\)
+
+Read a line, ending in a newline character.
+
+Return value: the line read.
+
+#### socket.write\(buf\)
+
+Write the buffer of bytes to the socket.
+
+Return value: number of bytes written.
+

firmwareapi/micropython/ussl.md

@@ -0,0 +1,40 @@
+# ussl
+
+This module provides access to Transport Layer Security \(often known as "Secure Sockets Layer"\) encryption and peer authentication facilities for network sockets, both client-side and server-side.
+
+## Methods
+
+#### ssl.wrap\_socket\(sock, keyfile=None, certfile=None, server\_side=False, cert\_reqs=CERT\_NONE, ca\_certs=None\)
+
+Takes an instance `sock` of `socket.socket`, and returns an instance of ssl.SSLSocket, a subtype of `socket.socket`, which wraps the underlying socket in an SSL context. Example:
+
+```python
+import socket
+import ssl
+s = socket.socket()
+ss = ssl.wrap_socket(s)
+ss.connect(socket.getaddrinfo('www.google.com', 443)[0][-1])
+```
+
+Certificates must be used in order to validate the other side of the connection, and also to authenticate ourselves with the other end. Such certificates must be stored as files using the FTP server, and they must be placed in specific paths with specific names.
+
+For instance, to connect to the Blynk servers using certificates, take the file `ca.pem` located in the `blynk` examples folder and put it in `/flash/cert/`. Then do:
+
+```python
+import socket
+import ssl
+s = socket.socket()
+ss = ssl.wrap_socket(s, cert_reqs=ssl.CERT_REQUIRED, ca_certs='/flash/cert/ca.pem')
+ss.connect(socket.getaddrinfo('cloud.blynk.cc', 8441)[0][-1])
+```
+
+SSL sockets inherit all methods and from the standard sockets, see the `usocket` module.
+
+## Exceptions
+
+* `ssl.SSLError`
+
+## Constants
+
+* `ssl.CERT_NONE`, `ssl.CERT_OPTIONAL`, `ssl.CERT_REQUIRED`: Supported values in `cert_reqs`
+

firmwareapi/micropython/ustruct.md

@@ -0,0 +1,30 @@
+# ustruct
+
+See Python [struct](https://docs.python.org/3/library/struct.html) for more information.
+
+Supported size/byte order prefixes: `@, <, >, !`.
+
+Supported format codes: `b, B, h, H, i, I, l, L, q, Q, s, P, f, d` \(the latter 2 depending on the floating-point support\).
+
+## Methods
+
+#### ustruct.calcsize\(fmt\)
+
+Return the number of bytes needed to store the given `fmt`.
+
+#### ustruct.pack\(fmt, v1, v2, ...\)
+
+Pack the values `v1, v2, ...` according to the format string `fmt`. The return value is a bytes object encoding the values.
+
+#### ustruct.pack\_into\(fmt, buffer, offset, v1, v2, ...\)
+
+Pack the values `v1, v2, ...` according to the format string `fmt` into a buffer starting at `offset`. `offset` may be negative to count from the end of buffer.
+
+#### ustruct.unpack\(fmt, data\)
+
+Unpack from the `data` according to the format string `fmt`. The return value is a tuple of the unpacked values.
+
+#### ustruct.unpack\_from\(fmt, data, offset=0\)
+
+Unpack from the `data` starting at `offset` according to the format string `fmt`. `offset` may be negative to count from the end of buffer. The return value is a tuple of the unpacked values.
+

firmwareapi/micropython/utime.md

@@ -0,0 +1,87 @@
+# utime
+
+The `utime` module provides functions for getting the current time and date, measuring time intervals, and for delays.
+
+**Time Epoch**: Pycom’s ESP32 port uses standard for POSIX systems epoch of `1970-01-01 00:00:00 UTC`.
+
+## Maintaining actual calendar date/time
+
+This requires a Real Time Clock \(RTC\). On systems with underlying OS \(including some RTOS\), an RTC may be implicit. Setting and maintaining actual calendar time is responsibility of OS/RTOS and is done outside of MicroPython, it just uses OS API to query date/time. On baremetal ports however system time depends on `machine.RTC()` object. The current calendar time may be set using `machine.RTC().datetime(tuple)` function, and maintained by following means:
+
+* By a backup battery \(which may be an additional, optional component for a particular board\).
+* Using networked time protocol \(requires setup by a port/user\).
+* Set manually by a user on each power-up \(many boards then maintain RTC time across hard resets, though some may require setting it again in such case\).
+
+If actual calendar time is not maintained with a system/MicroPython RTC, functions below which require reference to current absolute time may behave not as expected.
+
+## Methods
+
+#### utime.gmtime\(\[secs\]\)
+
+Convert a time expressed in seconds since the Epoch \(see above\) into an 8-tuple which contains: `(year, month, mday, hour, minute, second, weekday, yearday)` If `secs` is not provided or `None`, then the current time from the RTC is used.
+
+* `year` includes the century \(for example 2014\).
+* `month` is 1-12
+* `mday` is 1-31
+* `hour` is 0-23
+* `minute` is 0-59
+* `second` is 0-59
+* `weekday` is 0-6 for Mon-Sun
+* `yearday` is 1-366
+
+#### utime.localtime\(\[secs\]\)
+
+Like `gmtime()` but converts to local time. If `secs` is not provided or `None`, the current time from the RTC is used.
+
+#### utime.mktime\(\)
+
+This is inverse function of `localtime`. It’s argument is a full 8-tuple which expresses a time as per `localtime`. It returns an integer which is the number of seconds since `Jan 1, 2000`.
+
+#### utime.sleep\(seconds\)
+
+Sleep for the given number of `seconds`. `seconds` can be a floating-point number to sleep for a fractional number of seconds. Note that other MicroPython ports may not accept floating-point argument, for compatibility with them use `sleep_ms()` and `sleep_us()` functions.
+
+#### utime.sleep\_ms\(ms\)
+
+Delay for given number of milliseconds, should be positive or 0.
+
+#### utime.sleep\_us\(us\)
+
+Delay for given number of microseconds, should be positive or 0
+
+#### utime.ticks\_ms\(\)
+
+Returns uptime, in milliseconds.
+
+#### utime.ticks\_us\(\)
+
+Just like `ticks_ms` above, but in microseconds.
+
+#### utime.ticks\_cpu\(\)
+
+Same as `ticks_us`, but faster.
+
+#### utime.ticks\_diff\(old, new\)
+
+Measure period between consecutive calls to `ticks_ms()`, `ticks_us()`, or `ticks_cpu()`. The value returned by these functions may wrap around at any time, so directly subtracting them is not supported. `ticks_diff()` should be used instead. "old" value should actually precede "new" value in time, or result is undefined. This function should not be used to measure arbitrarily long periods of time \(because `ticks_*()` functions wrap around and usually would have short period\). The expected usage pattern is implementing event polling with timeout:
+
+```python
+# Wait for GPIO pin to be asserted, but at most 500us
+start = time.ticks_us()
+while pin.value() == 0:
+    if time.ticks_diff(start, time.ticks_us()) > 500:
+        raise TimeoutError
+```
+
+#### utime.time\(\)
+
+Returns the number of seconds, as an integer, since the Epoch, assuming that underlying RTC is set. If an RTC is not set, this function returns number of seconds since power up or reset\). If you want to develop portable MicroPython application, you should not rely on this function to provide higher than second precision. If you need higher precision, use `ticks_ms()` and `ticks_us()` functions, if you need calendar time, `localtime()` without an argument is a better choice.
+
+#### utime.timezone\(\[secs\]\)
+
+Set or get the timezone offset, in seconds. If `secs` is not provided, it returns the current value.
+
+{% hint style="info" %}
+In MicroPython, `time.timezone` works the opposite way to Python. In [Python](https://docs.python.org/3/library/time.html#time.timezone), to get the local time, you write `local_time = utc - timezone`, while in MicroPython it is `local_time = utc + timezone`.
+{% endhint %}
+

firmwareapi/notes.md

@@ -0,0 +1,16 @@
+# Notes
+
+## Interrupt Handling
+
+In Pycom’s ESP32 MicroPython port there are no restrictions on what can be done within an interrupt handler. For example, other ports do not allow allocating memory inside the handler or the use of sockets.
+
+These limitations were raised by handling the interrupt events differently. When an interrupt happens, a message is posted into a queue, notifying a separate thread that the appropriate callback handler should be called. Such handler would receive an argument. By default it is the object associated with the event.
+
+The user can do whatever is required inside of the callback, such as creating new variables, or even sending network packets. Bear in mind that interrupts are processed sequentially and thus it is ideal to keep the handlers as short as possible in order to attend all of them in the minimum time.
+
+Currently, there are 2 classes that support interrupts; the [`Alarm`](pycom/machine/timer.md#class-timer-alarm-handler-none-s-ms-us-arg-none-periodic-false) and [`Pin`](pycom/machine/pin.md) classes. Both classes provide the `.callback()` method that enables the interrupt and registers the given handler. For more details about interrupt usage along with examples, please visit their respective sections.
+
+{% hint style="info" %}
+Currently the interrupt system can queue up to **16 interrupts**.
+{% endhint %}
+

firmwareapi/pycom/README.md

@@ -0,0 +1,4 @@
+# Pycom Modules
+
+These modules are specific to the Pycom devices and may have slightly different implementations to other variations of MicroPython \(i.e. for Non-Pycom devices\). Modules include those which support access to underlying hardware, e.g. I2C, SPI, WLAN, Bluetooth, etc.
+

firmwareapi/pycom/aes.md

@@ -0,0 +1,62 @@
+# AES
+
+AES \(Advanced Encryption Standard\) is a symmetric block cipher standardised by NIST. It has a fixed data block size of 16 bytes. Its keys can be 128, 192, or 256 bits long.
+
+{% hint style="info" %}
+AES is implemented using the ESP32 hardware module.
+{% endhint %}
+
+## Quick Usage Example
+
+```python
+from crypto import AES
+import crypto
+key = b'notsuchsecretkey' # 128 bit (16 bytes) key
+iv = crypto.getrandbits(128) # hardware generated random IV (never reuse it)
+
+cipher = AES(key, AES.MODE_CFB, iv)
+msg = iv + cipher.encrypt(b'Attack at dawn')
+
+# ... after properly sent the encrypted message somewhere ...
+
+cipher = AES(key, AES.MODE_CFB, msg[:16]) # on the decryption side
+original = cipher.decrypt(msg[16:])
+print(original)
+```
+
+## Constructors
+
+#### class ucrypto.AES\(key, mode, IV, \* , counter, segment\_size\)
+
+Create an AES object that will let you encrypt and decrypt messages.
+
+The arguments are:
+
+* `key` \(byte string\) is the secret key to use. It must be 16 \(AES-128\), 24 \(AES-192\), or 32 \(AES-256\) bytes long.
+* `mode` is the chaining mode to use for encryption and decryption. Default is `AES.MODE_ECB`.
+* `IV` \(byte string\) initialisation vector. Should be 16 bytes long. It is ignored in modes `AES.MODE_ECB` and `AES.MODE_CRT`.
+* `counter` \(byte string\) used only for `AES.MODE_CTR`. Should be 16 bytes long. Should not be reused.
+* `segment_size` is the number of bits `plaintext` and `ciphertext` are segmented in. Is only used in `AES.MODE_CFB`. Supported values are `AES.SEGMENT_8` and `AES.SEGMENT_128`
+
+## Methods
+
+#### ucrypto.encrypt\(\)
+
+Encrypt data with the key and the parameters set at initialisation.
+
+#### ucrypto.decrypt\(\)
+
+Decrypt data with the key and the parameters set at initialisation.
+
+## Constants
+
+* `AES.MODE_ECB`: Electronic Code Book. Simplest encryption mode. It does not hide data patterns well \(see this article for more info\)
+* `AES.MODE_CBC`: Cipher-Block Chaining. An Initialisation Vector \(IV\) is required.
+* `AES.MODE_CFB`: Cipher feedback. `plaintext` and `ciphertext` are processed in segments of `segment_size` bits. Works a stream cipher.
+* `AES.MODE_CTR`:  Counter mode. Each message block is associated to a counter which must be unique across all messages that get encrypted with the same key.
+* `AES.SEGMENT_8`, `AES.SEGMENT_128`: Length of the segment for `AES.MODE_CFB`
+
+{% hint style="danger" %}
+To avoid security issues, IV should always be a random number and should never be reused to encrypt two different messages. The same applies to the counter in CTR mode. You can use `crypto.getrandbits()` for this purpose.
+{% endhint %}
+

firmwareapi/pycom/machine/README.md

@@ -0,0 +1,106 @@
+# machine
+
+The `machine` module contains specific functions related to the board.
+
+### Quick Usage Example
+
+```python
+import machine
+
+help(machine) # display all members from the machine module
+machine.freq() # get the CPU frequency
+machine.unique_id() # return the 6-byte unique id of the board (the LoPy's WiFi MAC address)
+```
+
+## Reset Functions
+
+#### machine.reset\(\)
+
+Resets the device in a manner similar to pushing the external RESET button.
+
+#### machine.reset\_cause\(\)
+
+Get the reset cause. See constants for the possible return values.
+
+## Interrupt Functions
+
+#### machine.disable\_irq\(\)
+
+Disable interrupt requests. Returns and integer representing the previous IRQ state. This return value can be passed to `enable_irq` to restore the IRQ to its original state.
+
+#### machine.enable\_irq\(\[state\]\)
+
+Enable interrupt requests. The most common use of this function is to pass the value returned by `disable_irq` to exit a critical section. Another options is to enable all interrupts which can be achieved by calling the function with no parameters.
+
+## Power Functions
+
+#### machine.freq\(\)
+
+Returns CPU frequency in hertz.
+
+#### machine.idle\(\)
+
+Gates the clock to the CPU, useful to reduce power consumption at any time during short or long periods. Peripherals continue working and execution resumes as soon as any interrupt is triggered \(on many ports this includes system timer interrupt occurring at regular intervals on the order of millisecond\).
+
+#### machine.deepsleep\(\[time\_ms\]\)
+
+Stops the CPU and all peripherals, including the networking interfaces \(except for LTE\). Execution is resumed from the main script, just as with a reset. If a value in milliseconds is given then the device will wake up after that period of time, otherwise it will remain in deep sleep until the reset button is pressed.
+
+The products with LTE connectivity \(FiPy, GPy, G01\), require the LTE radio to be disabled separately via the LTE class before entering deepsleep. This is required due to the LTE radio being powered independently and allowing use cases which require the system to be taken out from deepsleep by an event from the LTE network \(data or SMS received for instance\).
+
+#### machine.pin\_deepsleep\_wakeup\(pins, mode, enable\_pull\)
+
+Configure pins to wake up from deep sleep mode. The pins which have this capability are: `P2, P3, P4, P6, P8 to P10 and P13 to P23`.
+
+The arguments are:
+
+* `pins` a list or tuple containing the `GPIO` to setup for deepsleep wakeup.
+* `mode` selects the way the configure `GPIO`s can wake up the module. The possible values are: `machine.WAKEUP_ALL_LOW` and `machine.WAKEUP_ANY_HIGH`.
+* `enable_pull` if set to `True` keeps the pull up or pull down resistors enabled during deep sleep. If this variable is set to `True`, then `ULP` or capacitive touch wakeup cannot be used in combination with `GPIO` wakeup.
+
+#### machine.wake\_reason\(\)
+
+Get the wake reason. See constants for the possible return values. Returns a tuple of the form: `(wake_reason, gpio_list)`. When the wakeup reason is either GPIO or touch pad, then the second element of the tuple is a list with GPIOs that generated the wakeup.
+
+#### machine.remaining\_sleep\_time\(\)
+
+Returns the remaining timer duration \(in milliseconds\) if the ESP32 is woken up from deep sleep by something other than the timer. For example, if you set the timer for 30 seconds \(30000 ms\) and it wakes up after 10 seconds then this function will return `20000`.
+
+## Miscellaneous Functions
+
+#### machine.main\(filename\)
+
+Set the `filename` of the main script to run after `boot.py` is finished. If this function is not called then the default file `main.py` will be executed.
+
+It only makes sense to call this function from within `boot.py`.
+
+#### machine.rng\(\)
+
+Return a 24-bit software generated random number.
+
+#### machine.unique\_id\(\)
+
+Returns a byte string with a unique identifier of a board/SoC. It will vary from a board/SoC instance to another, if underlying hardware allows. Length varies by hardware \(so use substring of a full value if you expect a short ID\). In some MicroPython ports, ID corresponds to the network MAC address.
+
+{% hint style="info" %}
+Use `ubinascii.hexlify()` to convert the byte string to hexadecimal form for ease of manipulation and use elsewhere.
+{% endhint %}
+
+#### machine.info\(\)
+
+Returns the high water mark of the stack associated with various system tasks, in words \(1 word = 4 bytes on the ESP32\). If the value is zero then the task has likely overflowed its stack. If the value is close to zero then the task has come close to overflowing its stack.
+
+## Constants
+
+### Reset Causes
+
+`machine.PWRON_RESET`, `machine.HARD_RESET`, `machine.WDT_RESET,` `machine.DEEPSLEEP_RESET`, `machine.SOFT_RESET`, `machine.BROWN_OUT_RESET`
+
+### Wake Reasons
+
+`machine.PWRON_WAKE`, `machine.PIN_WAKE`, `machine.RTC_WAKE`, `machine.ULP_WAKE`
+
+### Pin Wakeup Modes
+
+`machine.WAKEUP_ALL_LOW`, `machine.WAKEUP_ANY_HIGH`
+

firmwareapi/pycom/machine/adc.md

@@ -0,0 +1,100 @@
+---
+search:
+  keywords:
+    - ADC
+    - Analog
+    - ADCChannel
+---
+
+# ADC
+
+## class ADC – Analog to Digital Conversion
+
+### Quick Usage Example
+
+```python
+import machine
+
+adc = machine.ADC()             # create an ADC object
+apin = adc.channel(pin='P16')   # create an analog pin on P16
+val = apin()                    # read an analog value
+```
+
+### Constructors
+
+#### class machine.ADC\(id=0\)
+
+Create an ADC object; associate a channel with a pin. For more info check the hardware section.
+
+### Methods
+
+#### adc.init\( \* , bits=12\)
+
+Enable the ADC block. This method is automatically called on object creation.
+
+* `Bits` can take values between 9 and 12 and selects the number of bits of resolution of the ADC block.
+
+#### adc.deinit\(\)
+
+Disable the ADC block.
+
+#### adc.channel\(\* , pin, attn=ADC.ATTN\_0DB\)
+
+Create an analog pin.
+
+* `pin` is a keyword-only string argument. Valid pins are `P13` to `P20`.
+* `attn` is the attenuation level. The supported values are: `ADC.ATTN_0DB`, `ADC.ATTN_2_5DB`, `ADC.ATTN_6DB`, `ADC.ATTN_11DB`
+
+Returns an instance of `ADCChannel`. Example:
+
+```python
+# enable an ADC channel on P16
+apin = adc.channel(pin='P16')
+```
+
+#### adc.vref\(vref\)
+
+If called without any arguments, this function returns the current calibrated voltage \(in millivolts\) of the `1.1v` reference. Otherwise it will update the calibrated value \(in millivolts\) of the internal `1.1v` reference.
+
+#### adc.vref\_to\_pin\(pin\)
+
+Connects the internal `1.1v` to external `GPIO`. It can only be connected to `P22`, `P21` or `P6`. It is recommended to only use `P6` on the WiPy, on other modules this pin is connected to the radio.
+
+### Constants
+
+* ADC channel attenuation values: `ADC.ATTN_0DB`, `ADC.ATTN_2_5DB`, `ADC.ATTN_6DB`, `ADC.ATTN_11DB`
+
+## class ADCChannel
+
+Read analog values from internal/external sources. ADC channels can be connected to internal points of the `MCU` or to `GPIO` pins. ADC channels are created using the `ADC.channel` method.
+
+### Methods
+
+#### adcchannel\(\)
+
+Fast method to read the channel value.
+
+#### adcchannel.value\(\)
+
+Read the channel value.
+
+#### adcchannel.init\(\)
+
+\(Re\)init and enable the ADC channel. This method is automatically called on object creation.
+
+#### adcchannel.deinit\(\)
+
+Disable the ADC channel.
+
+#### adcchannel.voltage\(\)
+
+Reads the channels value and converts it into a voltage \(in millivolts\)
+
+#### adcchannel.value\_to\_voltage\(value\)
+
+Converts the provided value into a voltage \(in millivolts\) in the same way voltage does.
+
+{% hint style="danger" %}
+ADC pin input range is `0-1.1V`. This maximum value can be increased up to `3.3V` using the highest attenuation of `11dB`. **Do not exceed the maximum of 3.3V**, to avoid damaging the device.
+{% endhint %}
+

firmwareapi/pycom/machine/can.md

@@ -0,0 +1,132 @@
+# CAN
+
+The CAN class supports the full CAN 2.0 specification with standard and extended frames, as well as acceptance filtering.
+
+The ESP32 has a built-in CAN controller, but the transceiver needs to be added externally. A recommended device is the SN65HVD230.
+
+## Quick Usage Example
+
+```python
+from machine import CAN
+
+can = CAN(mode=CAN.NORMAL, baudrate=500000, pins=('P22', 'P23'))
+can.send(id=12, data=bytes([1, 2, 3, 4, 5, 6, 7, 8]))
+can.recv()
+```
+
+## Constructors
+
+#### class machine.CAN\(bus=0, ...\)
+
+Create an CAN object. See init for parameters of initialisation.:
+
+```python
+# only 1 CAN peripheral is available, so the bus must always be 0
+can = CAN(0, mode=CAN.NORMAL, baudrate=500000, pins=('P22', 'P23'))    # pin order is Tx, Rx
+```
+
+## Methods
+
+#### can.init\(mode=CAN.NORMAL, baudrate=500000, \*, frame\_format=CAN.FORMAT\_STD, rx\_queue\_len=128, pins=\('P22', 'P23'\)\)
+
+Initialize the CAN controller. The arguments are:
+
+* `mode` can take either CAN.NORMAL or CAN.SILENT. Silent mode is useful for sniffing the bus.
+* `baudrate` sets up the bus speed. Acceptable values are between 1 and 1000000.
+* `frame_format` defines the frame format to be accepted by the receiver. Useful for filtering frames based on the identifier length. Can tale either `CAN.FORMAT_STD`, `CAN.FORMAT_EXT`, `CAN.FORMAT_BOTH`. If `CAN.FORMAT_STD` is selected, extended frames won't be received and vice-versa.
+* `rx_queue_len` defines the number of messages than can be queued by the receiver. Due to CAN being a high traffic bus, large values are recommended \(>= 128\), otherwise messages will be dropped specially when no filtering is applied.
+* `pins` selects the `Tx` and `Rx` pins \(in that order\).
+
+#### can.deinit\(\)
+
+Disables the CAN bus.
+
+#### can.send\(id, \* , data=None, rtr=False, extended=False\)
+
+Send a CAN frame on the bus
+
+* `id` is the identifier of the message.
+* `data` can take up to 8 bytes. It must be left empty is the message to be sent is a remote request \(rtr=True\).
+* `rtr` set it to false to send a remote request.
+* `extnted` specifies if the message identifier width should be 11bit \(standard\) or 29bit \(extended\).
+
+Can be used like:
+
+```python
+can.send(id=0x0020, data=bytes([0x01, 0x02, 0x03, 0x04, 0x05]), extended=True)   # sends 5 bytes with an extended identifier
+
+can.send(id=0x010, data=bytes([0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08])) # sends 8 bytes with an standard identifier
+
+can.send(id=0x012, rtr=True)         # sends a remote request for message id=0x12
+```
+
+#### can.recv\(timeout=0\)
+
+Get a message from the receive queue, and optionally specify a timeout value in **s** \(can be a floating point value e.g. `0.2`\). This function returns `None` if no messages available. If a message is present, it will be returned as a named tuple with the following form:
+
+`(id, data, rtr, extended)`
+
+```python
+>>> can.recv()
+(id=0x012, data=b'123', rtr=False, extended=False)
+```
+
+#### can.soft\_filter\(mode, filter\_list\)
+
+Specify a software filter accepting only the messages that pass the filter test.
+
+There are 3 possible filter modes:
+
+* `CAN.FILTER_LIST` allows to pass the list of IDs that should be accepted.
+* `CAN.FILTER_RANGE` allows to pass a list or tuple of ID ranges that should be accepted.
+* `CAN.FILTER_MASK` allows to pass a list of tuples of the form: `(filter, mask)`.
+
+With software filters all messages in the bus are received by the CAN controller but only the matching ones are passed to the RX queue. This means that the queue won't be filled up with non relevant messages, but the interrupt overhead will remain as normal. The `filter_list` can contain up to 32 elements.
+
+For example:
+
+```python
+can.soft_filter(CAN.FILTER_LIST, [0x100, 0x200, 0x300, 0x400])  # only accept identifiers from 0x100, 0x200, 0x300 and 0x400
+
+can.soft_filter(CAN.FILTER_RANGE, [(0x001, 0x010), (0x020, 0x030), (0x040, 0x050)])  # only accept identifiers from 0x001 to 0x010, from 0x020 to 0x030 and from 0x040 to 0x050.
+
+can.soft_filter(CAN.FILTER_MASK, [(0x100, 0x7FF), (0x200, 0x7FC)]) # more of the classic Filter and Mask method.
+
+can.soft_filter(None)   # disable soft filters, all messages are accepted
+```
+
+#### can.callback\(trigger, handler=None, arg=None\)
+
+Set a callback to be triggered when any of this 3 events are present:
+
+* trigger is the type of event that triggers the callback. Possible values are:
+  * `CAN.RX_FRAME` interrupt whenever a new frame is received.
+  * `CAN.RX_FIFO_NOT_EMPTY` interrupt when a frame is received on an empty FIFO.
+  * `CAN.RX_FIFO_OVERRUN` interrupt when a message is received and the FIFO is full.
+
+The values can be OR-ed together, for instance `trigger=CAN.RX_FRAME | CAN.RX_FIFO_OVERRUN`
+
+* handler is the function to be called when the event happens. This function will receive one argument. Set handler to None to disable the callback.
+* arg is an optional argument to pass to the callback. If left empty or set to None, the function will receive the CAN object that triggered it.
+
+It can be used like this:
+
+```python
+from machine import CAN
+
+can = CAN(mode=CAN.NORMAL, baudrate=500000, pins=('P22', 'P23'))
+
+def can_cb(can_o):
+    print('CAN Rx:', can_o.recv())
+
+can.callback(handler=can_cb, trigger=CAN.RX_FRAME)
+```
+
+#### can.events\(\)
+
+This method returns a value with bits sets \(if any\) indicating the events that have occurred in the bus. Please note that by calling this function the internal events registry is cleared automatically, therefore calling it immediately for a second time will most likely return a value of 0.
+
+## Constants
+
+`CAN.NORMAL`, `CAN.SILENT`, `CAN.FORMAT_STD`, `CAN.FORMAT_EXT`, `CAN.FORMAT_BOTH`, `CAN.RX_FRAME`, `CAN.RX_FIFO_NOT_EMPTY`, `CAN.RX_FIFO_OVERRUN`, `CAN.FILTER_LIST`, `CAN.FILTER_RANGE`, `CAN.FILTER_MASK`
+

firmwareapi/pycom/machine/dac.md

@@ -0,0 +1,46 @@
+# DAC
+
+The DAC is used to output analog values \(a specific voltage\) on pin `P22` or pin `P21`. The voltage will be between `0` and `3.3V`.
+
+## Quick Usage Example
+
+```python
+import machine
+
+dac = machine.DAC('P22')        # create a DAC object
+dac.write(0.5)                  # set output to 50%
+
+dac_tone = machine.DAC('P21')   # create a DAC object
+dac_tone.tone(1000, 0)          # set tone output to 1kHz
+```
+
+## Constructors
+
+#### class class machine.DAC\(pin\)
+
+Create a DAC object, that will let you associate a channel with a `pin`. `pin` can be a string argument.
+
+## Methods
+
+#### dac.init\(\)
+
+Enable the DAC block. This method is automatically called on object creation.
+
+#### dac.deinit\(\)
+
+Disable the DAC block.
+
+#### dac.write\(value\)
+
+Set the DC level for a DAC pin. `value` is a float argument, with values between 0 and 1.
+
+#### dac.tone\(frequency, amplitude\)
+
+Sets up tone signal to the specified `frequency` at `amplitude` scale. `frequency` can be from `125Hz` to `20kHz` in steps of `122Hz`. `amplitude` is an integer specifying the tone amplitude to write the DAC pin. Amplitude value represents:
+
+* `0` is 0dBV \(~ 3Vpp at 600 Ohm load\)
+* `1` is -6dBV \(~1.5 Vpp\), `2` is -12dBV \(~0.8 Vpp\)
+* `3` is -18dBV \(~0.4 Vpp\).
+
+  The generated signal is a sine wave with an DC offset of VDD/2.
+

firmwareapi/pycom/machine/i2c.md

@@ -0,0 +1,128 @@
+# I2C
+
+I2C is a two-wire protocol for communicating between devices. At the physical level it consists of 2 wires: SCL and SDA, the clock and data lines respectively.
+
+I2C objects are created attached to a specific bus. They can be initialised when created, or initialised later on.
+
+## Example using default Pins
+
+```python
+from machine import I2C
+
+i2c = I2C(0)                         # create on bus 0
+i2c = I2C(0, I2C.MASTER)             # create and init as a master
+i2c = I2C(0, pins=('P10','P11'))     # create and use non-default PIN assignments (P10=SDA, P11=SCL)
+i2c.init(I2C.MASTER, baudrate=20000) # init as a master
+i2c.deinit()                         # turn off the peripheral
+```
+
+## Example using non-default Pins
+
+```python
+from machine import I2C
+
+i2c = I2C(0, pins=('P10','P11'))     # create and use non-default PIN assignments (P10=SDA, P11=SCL)
+i2c.init(I2C.MASTER, baudrate=20000) # init as a master
+i2c.deinit()                         # turn off the peripheral
+```
+
+Printing the `i2c` object gives you information about its configuration.
+
+A master must specify the recipient’s address:
+
+```python
+i2c.init(I2C.MASTER)
+i2c.writeto(0x42, '123')        # send 3 bytes to slave with address 0x42
+i2c.writeto(addr=0x42, b'456')  # keyword for address
+```
+
+Master also has other methods:
+
+```python
+i2c.scan()                          # scan for slaves on the bus, returning
+                                    #   a list of valid addresses
+i2c.readfrom_mem(0x42, 2, 3)        # read 3 bytes from memory of slave 0x42,
+                                    #   starting at address 2 in the slave
+i2c.writeto_mem(0x42, 2, 'abc')     # write 'abc' (3 bytes) to memory of slave 0x42
+                                    # starting at address 2 in the slave, timeout after 1 second
+```
+
+## Quick Usage Example
+
+```python
+from machine import I2C
+# configure the I2C bus
+i2c = I2C(0, I2C.MASTER, baudrate=100000)
+i2c.scan() # returns list of slave addresses
+i2c.writeto(0x42, 'hello') # send 5 bytes to slave with address 0x42
+i2c.readfrom(0x42, 5) # receive 5 bytes from slave
+i2c.readfrom_mem(0x42, 0x10, 2) # read 2 bytes from slave 0x42, slave memory 0x10
+i2c.writeto_mem(0x42, 0x10, 'xy') # write 2 bytes to slave 0x42, slave memory 0x10
+```
+
+## Constructors
+
+#### class machine.I2C\(bus, ...\)
+
+Construct an I2C object on the given `bus`. `bus` can only be `0, 1, 2`. If the `bus` is not given, the default one will be selected \(`0`\). Buses `0` and `1` use the ESP32 I2C hardware peripheral while bus `2` is implemented with a bit-banged software driver.
+
+## Methods
+
+### General Methods
+
+#### i2c.init\(mode, \* , baudrate=100000, pins=\(SDA, SCL\)\)
+
+Initialise the I2C bus with the given parameters:
+
+* `mode` must be I2C.MASTER
+* `baudrate` is the SCL clock rate
+* pins is an optional tuple with the pins to assign to the I2C bus. The default I2C pins are `P9` \(SDA\) and `P10` \(SCL\)
+
+#### i2c.scan\(\)
+
+Scan all I2C addresses between `0x08` and `0x77` inclusive and return a list of those that respond. A device responds if it pulls the SDA line low after its address \(including a read bit\) is sent on the bus.
+
+### Standard Bus Operations
+
+The following methods implement the standard I2C master read and write operations that target a given slave device.
+
+#### i2c.readfrom\(addr, nbytes\)
+
+Read `nbytes` from the slave specified by `addr`. Returns a bytes object with the data read.
+
+#### i2c.readfrom\_into\(addr, buf\)
+
+Read into `buf` from the slave specified by `addr`. The number of bytes read will be the length of `buf`.
+
+Return value is the number of bytes read.
+
+#### i2c.writeto\(addr, buf, \* , stop=True\)
+
+Write the bytes from `buf` to the slave specified by `addr`. The argument `buf` can also be an integer which will be treated as a single byte. If `stop` is set to `False` then the stop condition won’t be sent and the I2C operation may be continued \(typically with a read transaction\).
+
+Return value is the number of bytes written.
+
+### Memory Operations
+
+Some I2C devices act as a memory device \(or set of registers\) that can be read from and written to. In this case there are two addresses associated with an I2C transaction: the slave address and the memory address. The following methods are convenience functions to communicate with such devices.
+
+#### i2c.readfrom\_mem\(addr, memaddr, nbytes, \*, addrsize=8\)
+
+Read `nbytes` from the slave specified by `addr` starting from the memory address specified by `memaddr`. The `addrsize` argument is specified in bits and it can only take 8 or 16.
+
+#### i2c.readfrom\_mem\_into\(addr, memaddr, buf, \*, addrsize=8\)
+
+Read into `buf` from the slave specified by `addr` starting from the memory address specified by `memaddr`. The number of bytes read is the length of `buf`. The `addrsize` argument is specified in bits and it can only take 8 or 16.
+
+The return value is the number of bytes read.
+
+#### i2c.writeto\_mem\(addr, memaddr, buf \*, addrsize=8\)
+
+Write `buf` to the slave specified by `addr` starting from the memory address specified by `memaddr`. The argument `buf` can also be an integer which will be treated as a single byte. The `addrsize` argument is specified in bits and it can only take 8 or 16.
+
+The return value is the number of bytes written.
+
+## Constants
+
+* `I2C.MASTER`: Used to initialise the bus to master mode.
+

firmwareapi/pycom/machine/pin.md

@@ -0,0 +1,153 @@
+# Pin
+
+A pin is the basic object to control I/O pins \(also known as GPIO - general-purpose input/output\). It has methods to set the mode of the pin \(input, output, etc\) and methods to get and set the digital logic level. For analog control of a pin, see the ADC class.
+
+## Quick Usage Example
+
+```python
+from machine import Pin
+
+# initialize `P9` in gpio mode and make it an output
+p_out = Pin('P9', mode=Pin.OUT)
+p_out.value(1)
+p_out.value(0)
+p_out.toggle()
+p_out(True)
+
+# make `P10` an input with the pull-up enabled
+p_in = Pin('P10', mode=Pin.IN, pull=Pin.PULL_UP)
+p_in() # get value, 0 or 1
+```
+
+## Constructors
+
+#### class machine.Pin\(id, ...\)
+
+Create a new Pin object associated with the string `id`. If additional arguments are given, they are used to initialise the pin. [See pin.init\(\)](pin.md#pin-init-mode-pull-alt)
+
+```python
+from machine import Pin
+p = Pin('P10', mode=Pin.OUT, pull=None, alt=-1)
+```
+
+## Methods
+
+#### pin.init\(mode, pull, \* , alt\)
+
+Initialise the pin:
+
+* `mode` can be one of:
+  * `Pin.IN` - input pin.
+  * `Pin.OUT` - output pin in push-pull mode.
+  * `Pin.OPEN_DRAIN` - input or output pin in open-drain mode.
+* `pull` can be one of:
+  * `None` - no pull up or down resistor.
+  * `Pin.PULL_UP` - pull up resistor enabled.
+  * `Pin.PULL_DOWN` - pull down resistor enabled.
+* `alt` is the id of the alternate function.
+
+Returns: `None`.
+
+#### pin.id\(\)
+
+Get the pin id.
+
+#### pin.value\(\[value\]\)
+
+Get or set the digital logic level of the pin:
+
+* With no argument, return 0 or 1 depending on the logic level of the pin.
+* With value given, set the logic level of the pin. value can be anything that converts to a boolean. If it converts to True, the pin is set high, otherwise it is set low.
+
+#### pin\(\[value\]\)
+
+Pin objects are callable. The call method provides a \(fast\) shortcut to set and get the value of the pin.
+
+Example:
+
+```python
+from machine import Pin
+pin = Pin('P12', mode=Pin.IN, pull=Pin.PULL_UP)
+pin()   # fast method to get the value
+```
+
+See `pin.value()` for more details.
+
+#### pin.toggle\(\)
+
+Toggle the value of the pin.
+
+#### pin.mode\(\[mode\]\)
+
+Get or set the pin mode.
+
+#### pin.pull\(\[pull\]\)
+
+Get or set the pin pull.
+
+#### pin.hold\(\[hold\]\)
+
+Get or set the pin hold. You can apply a hold to a pin by passing `True` \(or clear it by passing `False`\). When a pin is held, its value cannot be changed by using `Pin.value()` or `Pin.toggle()` until the hold is released. This Can be used to retain the pin state through a core reset and system reset triggered by watchdog time-out or Deep-sleep events. Only pins in the RTC power domain can retain their value through deep sleep or reset.
+
+These are: `P2, P3, P4, P6, P8, P9, P10, P13, P14, P15, P16, P17, P18, P19, P20, P21, P22, P23`
+
+#### pin.callback\(trigger, handler=None, arg=None\)
+
+Set a callback to be triggered when the input level at the pin changes.
+
+* `trigger` is the type of event that triggers the callback. Possible values are:
+  * `Pin.IRQ_FALLING` interrupt on falling edge.
+  * `Pin.IRQ_RISING` interrupt on rising edge.
+  * `Pin.IRQ_LOW_LEVEL` interrupt on low level.
+  * `Pin.IRQ_HIGH_LEVEL` interrupt on high level.
+
+The values can be OR-ed together, for instance `trigger=Pin.IRQ_FALLING | Pin.IRQ_RISING`
+
+* `handler` is the function to be called when the event happens. This function will receive one argument. Set `handler` to `None` to disable it.
+* `arg` is an optional argument to pass to the callback. If left empty or set to `None`, the function will receive the Pin object that triggered it.
+
+Example:
+
+```python
+from machine import Pin
+
+def pin_handler(arg):
+    print("got an interrupt in pin %s" % (arg.id()))
+
+p_in = Pin('P10', mode=Pin.IN, pull=Pin.PULL_UP)
+p_in.callback(Pin.IRQ_FALLING | Pin.IRQ_RISING, pin_handler)
+```
+
+{% hint style="info" %}
+For more information on how Pycom’s products handle interrupts, see [here](../../notes.md#interrupt-handling).
+{% endhint %}
+
+## Attributes
+
+#### class pin.exp\_board
+
+Contains all Pin objects supported by the expansion board. Examples:
+
+```python
+Pin.exp_board.G16
+led = Pin(Pin.exp_board.G16, mode=Pin.OUT)
+Pin.exp_board.G16.id()
+```
+
+#### class pin.module
+
+Contains all `Pin` objects supported by the module. Examples:
+
+```python
+Pin.module.P9
+led = Pin(Pin.module.P9, mode=Pin.OUT)
+Pin.module.P9.id()
+```
+
+## Constants
+
+The following constants are used to configure the pin objects. Note that not all constants are available on all ports.
+
+* Selects the pin mode: `Pin.IN`, `Pin.OUT`, `Pin.OPEN_DRAIN`
+* Enables the pull up or pull down resistor: `Pin.PULL_UP`, `Pin.PULL_DOWN`
+

firmwareapi/pycom/machine/pwm.md

@@ -0,0 +1,34 @@
+# PWM
+
+## class PWM – Pulse Width Modulation
+
+### Quick Usage Example
+
+```python
+from machine import PWM
+pwm = PWM(0, frequency=5000)  # use PWM timer 0, with a frequency of 5KHz
+# create pwm channel on pin P12 with a duty cycle of 50%
+pwm_c = pwm.channel(0, pin='P12', duty_cycle=0.5)
+pwm_c.duty_cycle(0.3) # change the duty cycle to 30%
+```
+
+### Constructors
+
+#### class machine.PWM\(timer, frequency\)
+
+Create a PWM object. This sets up the `timer` to oscillate at the specified `frequency`. `timer` is an integer from 0 to 3. `frequency` is an integer from 1 Hz to 78 KHz \(this values can change in future upgrades\).
+
+### Methods
+
+#### pwm.channel\(id, pin \* , duty\_cycle=0.5\)
+
+Connect a PWM channel to a pin, setting the initial duty cycle. `id` is an integer from 0 to 7. `pin` is a string argument. `duty_cycle` is a keyword-only float argument, with values between 0 and 1. Returns an instance of `PWMChannel`.
+
+## class PWMChannel — PWM channel
+
+### Methods
+
+#### pwmchannel.duty\_cycle\(value\)
+
+Set the duty cycle for a PWM channel. `value` is a float argument, with values between 0 and 1.
+

firmwareapi/pycom/machine/rmt.md

@@ -0,0 +1,134 @@
+---
+search:
+  keywords:
+    - RMT
+    - Remote
+    - Remote Controller
+    - Pulse
+---
+
+# RMT
+
+The RMT \(Remote Control\) module is primarily designed to send and receive infrared remote control signals that use on-off-keying of a carrier frequency, but due to its design it can be used to generate various types of signals.
+
+## Quick Usage Example: sending
+
+```python
+import machine
+
+# create a RMT object for transmission
+rmt = machine.RMT(channel=3, gpio="P20", tx_idle_level=0)
+# create series of bits to send    
+data = (1,0,1,0,1,0,1,0,1)
+# define duration of the bits, time unit depends on the selected RMT channel  
+duration = 10000
+# send the signal                                         
+rmt.send_pulses(duration, data)
+```
+
+## Quick Usage Example: receiving
+
+```python
+import machine
+# create a RMT object
+rmt = machine.RMT(channel=3)
+# Configure RTM for receiving
+rmt.init(gpio="P20", rx_idle_threshold=12000)     
+# wait for any number of pulses until one longer than rx_idle_threshold        
+data = rmt.recv_pulses()
+```
+
+## Constructors
+
+#### class machine.RMT\(channel,...\)
+
+Construct an RMT object on the given channel. `channel` can be 2-7. With no additional parameters, the RMT object is created but not initialised. If extra arguments are given, the RMT is initialised for transmission or reception. See `init` for parameters of initialisation. The resolution which a pulse can be sent/received depends on the selected channel:
+
+| Channel | Resolution | Maximum Pulse Width |
+| :--- | :--- | :--- |
+| 0 | Used by on-board LED |  |
+| 1 | Used by `pycom.pulses_get()` |  |
+| 2 | 100nS | 3.2768 ms |
+| 3 | 100nS | 3.2768 ms |
+| 4 | 1000nS | 32.768 ms |
+| 5 | 1000nS | 32.768 ms |
+| 6 | 3125nS | 102.4   ms |
+| 7 | 3125nS | 102.4   ms |
+
+## Methods
+
+#### rmt.init\(gpio, rx\_idle\_threshold, rx\_filter\_threshold, tx\_idle\_level, tx\_carrier\)
+
+Initialise the RMT peripheral with the given parameters:
+
+* `gpio` is the GPIO Pin to use.
+* `rx_idle_threshold` is the maximum duration of a valid pulse. The represented time unit \(resolution\) depends on the selected channel, value can be 0-65535.
+* `rx_filter_threshold` is the minimum duration of a valid pulse. The represented time unit \(resolution\) depends on the selected channel, value can be 0-31.
+* `tx_idle_level` is the output signal's level after the transmission is finished, can be RMT.HIGH or RMT.LOW.
+* `tx_carrier` is the modulation of the pulses to send.
+
+Either `rx_idle_threshold` or `tx_idle_level` must be defined, both cannot be given at the same time because a channel can be configured in RX or TX mode only. `rx_filter_threshold` is not mandatory parameter. If not given then all pulses are accepted with duration less than `rx_idle_threshold`. `tx_carrier` is not mandatory parameters. If not given no modulation is used on the sent pulses.
+
+The `tx_carrier` parameter is a tuple with the following structure:
+
+* `carrier_freq_hz` is the carrier's frequency in Hz.
+* `carrier_duty_percent` is the duty percent of the carrier's signal, can be 0%-100%.
+* `carrier_level` is the level of the pulse to modulate, can be RMT.HIGH or RMT.LOW.
+
+#### rmt.deinit\(\)
+
+Deinitialise the RMT object.
+
+{% hint style="info" %}
+If an RMT object needs to be reconfigured from RX/TX to TX/RX, then either first `deinit()` must be called or the `init()` again with the desired configuration.
+{% endhint %}
+
+#### rmt.pulses\_get\(pulses, timeout\)
+
+Reads in pulses from the GPIO pin.
+
+* `pulses` if not specified, this function will keep reading pulses until the
+
+  `rx_idle_threshold` is exceeded. If it is specified this function will return
+
+  the exactly that number of pulses, ignoring anything shorter than
+
+  `rx_filter_threshold` or longer than `rx_idle_threshold`.
+
+* `timeout` is specified, this function will return if the first pulse does
+
+  not occur within `timeout` microseconds. If not specified, it will wait
+
+  indefinitely.
+
+Return value: Tuple of items with the following structure: `(level, duration)`:
+
+* `level` represents the level of the received bit/pulse, can be 0 or 1.
+* `duration` represents the duration of the received pulse, the time unit \(resolution\) depends on the selected channel.
+
+{% hint style="info" %}
+Maximum of 128 pulses can be received in a row without receiving "idle" signal. If the incoming pulse sequence contains more than 128 pulses the rest is dropped and the receiver waits for another sequence of pulses. The `pulses_get` function can be called to receive more than 128 pulses, however the above mentioned limitation should be kept in mind when evaluating the received data.
+{% endhint %}
+
+#### rmt.pulses\_send\(duration, data, start\_level\)
+
+Generates pulses as defined by the parameters below
+
+* `duration` represents the duration of the pulses to be sent,
+
+  the time unit \(resolution\) depends on the selected channel.
+
+* `data` Tuple that represents the sequence of pulses to be sent, must be
+
+  composed of 0 or 1 elements.
+
+* `start_level` defines the state \(HIGH/LOW\) of the first pulse given by
+
+  `duration` if `data` is not given.
+
+`data` must be a tuple and `duration` can be a tuple or a single number, with `data` being optional. In the case that only `duration` is provided, it must be a tuple and you must also provide `start_level` which will dictate the level of the first duration, the signal level then toggles between each duration value. If `data` is provided and `duration` is a single number, each pulse in `data` will have have an equal length as set by `duration`. If `data` and `duration` are provided as tuples, they must be of the same number of elements, with each pulse lasting its matching duration.
+
+## Constants
+
+* Define the level of the pulse: `RMT.LOW`, `RMT.HIGH`
+

firmwareapi/pycom/machine/rtc.md

@@ -0,0 +1,79 @@
+# RTC
+
+The RTC is used to keep track of the date and time.
+
+## Quick Usage Example
+
+```python
+from machine import RTC
+
+rtc = RTC()
+rtc.init((2014, 5, 1, 4, 13, 0, 0, 0))
+print(rtc.now())
+```
+
+## Constructors
+
+#### class machine.RTC\(id=0, ...\)
+
+Create an RTC object. See init for parameters of initialisation.
+
+```python
+# id of the RTC may be set if multiple are connected. Defaults to id = 0.
+rtc = RTC(id=0)
+```
+
+## Methods
+
+#### rtc.init\(datetime=None, source=RTC.INTERNAL\_RC\)
+
+Initialise the RTC. The arguments are:
+
+* `datetime` when passed it sets the current time. It is a tuple of the form: `(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])`
+* `source` selects the oscillator that drives the RTC. The options are RTC.INTERNAL\_RC and RTC.XTAL\_32KHZ
+
+For example:
+
+```python
+# for 2nd of February 2017 at 10:30am (TZ 0)
+rtc.init((2017, 2, 28, 10, 30, 0, 0, 0))
+```
+
+{% hint style="info" %}
+`tzinfo` is ignored by this method. Use `time.timezone` to achieve similar results.
+{% endhint %}
+
+#### rtc.now\(\)
+
+Get get the current `datetime` tuple:
+
+```python
+# returns datetime tuple
+rtc.now()
+```
+
+#### rtc.ntp\_sync\(server, \* , update\_period=3600\)
+
+Set up automatic fetch and update the time using NTP \(SNTP\).
+
+* `server` is the URL of the NTP server. Can be set to `None` to disable the periodic updates.
+* `update_period` is the number of seconds between updates. Shortest period is 15 seconds.
+
+Can be used like:
+
+```python
+rtc.ntp_sync("pool.ntp.org") # this is an example. You can select a more specific server according to your geographical location
+```
+
+#### rtc.synced\(\)
+
+Returns `True` if the last `ntp_sync` has been completed, `False` otherwise:
+
+```python
+rtc.synced()
+```
+
+## Constants
+
+* Clock source: `RTC.INTERNAL_RC`, `RTC.XTAL_32KHZ`
+

firmwareapi/pycom/machine/sd.md

@@ -0,0 +1,53 @@
+# SD
+
+The SD card class allows to configure and enable the memory card module of your Pycom module and automatically mount it as `/sd` as part of the file system. There is a single pin combination that can be used for the SD card, and the current implementation only works in 1-bit mode. The pin connections are as follows:
+
+`P8: DAT0`, `P23: SCLK` and `P4: CMD` \(no external pull-up resistors are needed\)
+
+If you have one of the Pycom expansion boards, then simply insert the card into the micro SD socket and run your script.
+
+{% hint style="info" %}
+Make sure your SD card is formatted either as FAT16 or FAT32.
+{% endhint %}
+
+## Quick Example Usage:
+
+```python
+from machine import SD
+import os
+
+sd = SD()
+os.mount(sd, '/sd')
+
+# check the content
+os.listdir('/sd')
+
+# try some standard file operations
+f = open('/sd/test.txt', 'w')
+f.write('Testing SD card write operations')
+f.close()
+f = open('/sd/test.txt', 'r')
+f.readall()
+f.close()
+```
+
+## Constructors
+
+#### class machine.SD\(id, ...\)
+
+Create a SD card object. See [`sd.init()`](sd.md#sd-init-id-0) for parameters if initialisation.
+
+## Methods
+
+#### sd.init\(id=0\)
+
+Enable the SD card.
+
+#### sd.deinit\(\)
+
+Disable the SD card.
+
+{% hint style="info" %}
+Please note that the SD card library currently supports FAT16/32 formatted SD cards up to 32 GB. Future firmware updates will increase compatibility with additional formats and sizes.
+{% endhint %}
+

firmwareapi/pycom/machine/spi.md

@@ -0,0 +1,87 @@
+# SPI
+
+SPI is a serial protocol that is driven by a master. At the physical level there are 3 lines: SCK, MOSI, MISO.
+
+See usage model of I2C; SPI is very similar. Main difference is parameters to init the SPI bus:
+
+```python
+from machine import SPI
+spi = SPI(0, mode=SPI.MASTER, baudrate=1000000, polarity=0, phase=0, firstbit=SPI.MSB)
+```
+
+Only required parameter is mode, must be SPI.MASTER. Polarity can be 0 or 1, and is the level the idle clock line sits at. Phase can be 0 or 1 to sample data on the first or second clock edge respectively.
+
+## Quick Usage Example
+
+```python
+from machine import SPI
+
+# configure the SPI master @ 2MHz
+# this uses the SPI default pins for CLK, MOSI and MISO (``P10``, ``P11`` and ``P14``)
+spi = SPI(0, mode=SPI.MASTER, baudrate=2000000, polarity=0, phase=0)
+spi.write(bytes([0x01, 0x02, 0x03, 0x04, 0x05])) # send 5 bytes on the bus
+spi.read(5) # receive 5 bytes on the bus
+rbuf = bytearray(5)
+spi.write_readinto(bytes([0x01, 0x02, 0x03, 0x04, 0x05]), rbuf) # send a receive 5 bytes
+```
+
+## Quick Usage Example using non-default pins
+
+```python
+from machine import SPI
+
+# configure the SPI master @ 2MHz
+# this uses the SPI non-default pins for CLK, MOSI and MISO (``P19``, ``P20`` and ``P21``)
+spi = SPI(0, mode=SPI.MASTER, baudrate=2000000, polarity=0, phase=0, pins=('P19','P20','P21'))
+spi.write(bytes([0x01, 0x02, 0x03, 0x04, 0x05])) # send 5 bytes on the bus
+spi.read(5) # receive 5 bytes on the bus
+rbuf = bytearray(5)
+spi.write_readinto(bytes([0x01, 0x02, 0x03, 0x04, 0x05]), rbuf) # send a receive 5 bytes
+```
+
+## Constructors
+
+#### class machine.SPI\(id, ...\)
+
+Construct an SPI object on the given bus. `id` can be only 0. With no additional parameters, the SPI object is created but not initialised \(it has the settings from the last initialisation of the bus, if any\). If extra arguments are given, the bus is initialised. See init for parameters of initialisation.
+
+## Methods
+
+#### spi.init\(mode, baudrate=1000000, \* , polarity=0, phase=0, bits=8, firstbit=SPI.MSB, pins=\(CLK, MOSI, MISO\)\)
+
+Initialise the SPI bus with the given parameters:
+
+* `mode` must be SPI.MASTER.
+* `baudrate` is the SCK clock rate.
+* `polarity` can be 0 or 1, and is the level the idle clock line sits at.
+* `phase` can be 0 or 1 to sample data on the first or second clock edge respectively.
+* `bits` is the width of each transfer, accepted values are 8, 16 and 32.
+* `firstbit` can be SPI.MSB or SPI.LSB.
+* `pins` is an optional tuple with the pins to assign to the SPI bus. If the pins argument is not given the default pins will be selected \(`P10` as CLK,`P11` as MOSI and `P14` as MISO\). If pins is passed as None then no pin assignment will be made.
+
+#### spi.deinit\(\)
+
+Turn off the SPI bus.
+
+#### spi.write\(buf\)
+
+Write the data contained in `buf`. Returns the number of bytes written.
+
+#### spi.read\(nbytes, \* , write=0x00\)
+
+Read the `nbytes` while writing the data specified by `write`. Returns the bytes read.
+
+#### spi.readinto\(buf, \* , write=0x00\)
+
+Read into the buffer specified by `buf` while writing the data specified by `write`. Return the number of bytes read.
+
+#### spi.write\_readinto\(write\_buf, read\_buf\)
+
+Write from `write_buf` and read into `read_buf`. Both buffers must have the same length. Returns the number of bytes written
+
+## Constants
+
+* For initialising the SPI bus to master: `SPI.MASTER`
+* Set the first bit to be the most significant bit: `SPI.MSB`
+* Set the first bit to be the least significant bit: `SPI.LSB`
+

firmwareapi/pycom/machine/timer.md

@@ -0,0 +1,127 @@
+# Timer
+
+## class Timer – Measure Time and Set Alarms
+
+Timers can be used for a great variety of tasks, like measuring time spans or being notified that a specific interval has elapsed.
+
+These two concepts are grouped into two different subclasses:
+
+`Chrono`: used to measure time spans. `Alarm`: to get interrupted after a specific interval.
+
+{% hint style="info" %}
+You can create as many of these objects as needed.
+{% endhint %}
+
+### Constructors
+
+#### class Timer.Chrono\(\)
+
+Create a chronometer object.
+
+#### class Timer.Alarm\(handler=None, s, \* , ms, us, arg=None, periodic=False\)
+
+Create an Alarm object.
+
+* `handler`: will be called after the interval has elapsed. If set to `None`, the alarm will be disabled after creation.
+* `arg`: an optional argument can be passed to the callback handler function. If `None` is specified, the function will receive the object that triggered the alarm.
+* `s, ms, us`: the interval can be specified in seconds \(float\), miliseconds \(integer\) or microseconds \(integer\). Only one at a time can be specified.
+* `periodic`: an alarm can be set to trigger repeatedly by setting this parameter to `True`.
+
+### Methods
+
+#### Timer.sleep\_us\(\)
+
+Delay for a given number of microseconds, should be positive or 0 \(for speed, the condition is not enforced\). Internally it uses the same timer as the other elements of the `Timer` class. It compensates for the calling overhead, so for example, 100us should be really close to 100us. For times bigger than 10,000us it releases the GIL to let other threads run, so exactitude is not guaranteed for delays longer than that.
+
+## class Chrono
+
+Can be used to measure time spans.
+
+### Methods
+
+#### chrono.start\(\)
+
+Start the chronometer.
+
+#### chrono.stop\(\)
+
+Stop the chronometer.
+
+#### chrono.reset\(\)
+
+Reset the time count to 0.
+
+#### chrono.read\(\)
+
+Get the elapsed time in seconds.
+
+#### chrono.read\_ms\(\)
+
+Get the elapsed time in milliseconds.
+
+#### chrono.read\_us\(\)
+
+Get the elapsed time in microseconds.
+
+Example:
+
+```python
+from machine import Timer
+import time
+
+chrono = Timer.Chrono()
+
+chrono.start()
+time.sleep(1.25) # simulate the first lap took 1.25 seconds
+lap = chrono.read() # read elapsed time without stopping
+time.sleep(1.5)
+chrono.stop()
+total = chrono.read()
+
+print()
+print("\nthe racer took %f seconds to finish the race" % total)
+print("  %f seconds in the first lap" % lap)
+print("  %f seconds in the last lap" % (total - lap))
+class Alarm – get interrupted after a specific interval
+```
+
+## class Alarm
+
+Used to get interrupted after a specific interval.
+
+### Methods
+
+#### alarm.callback\(handler, \* , arg=None\)
+
+Specify a callback handler for the alarm. If set to `None`, the alarm will be disabled.
+
+An optional argument `arg` can be passed to the callback handler function. If `None` is specified, the function will receive the object that triggered the alarm.
+
+#### alarm.cancel\(\)
+
+Disables the alarm.
+
+Example:
+
+```python
+from machine import Timer
+
+class Clock:
+
+    def __init__(self):
+        self.seconds = 0
+        self.__alarm = Timer.Alarm(self._seconds_handler, 1, periodic=True)
+
+    def _seconds_handler(self, alarm):
+        self.seconds += 1
+        print("%02d seconds have passed" % self.seconds)
+        if self.seconds == 10:
+            alarm.cancel() # stop counting after 10 seconds
+
+clock = Clock()
+```
+
+{% hint style="info" %}
+For more information on how Pycom’s products handle interrupts, see [notes](../../notes.md#interrupt-handling).
+{% endhint %}
+

firmwareapi/pycom/machine/uart.md

@@ -0,0 +1,135 @@
+# UART
+
+UART implements the standard UART/USART duplex serial communications protocol. At the physical level it consists of 2 lines: RXD and TXD. The unit of communication is a character \(not to be confused with a string character\) which can be 5, 6, 7 or 8 bits wide.
+
+UART objects can be created and initialised using:
+
+```python
+from machine import UART
+
+uart = UART(1, 9600)                         # init with given baudrate
+uart.init(9600, bits=8, parity=None, stop=1) # init with given parameters
+```
+
+Bits can be `5, 6, 7, 8`. Parity can be `None`, `UART.EVEN` or `UART.ODD`. Stop can be `1, 1.5 or 2`.
+
+A UART object acts like a stream object therefore reading and writing is done using the standard stream methods:
+
+```python
+uart.read(10)       # read 10 characters, returns a bytes object
+uart.readall()      # read all available characters
+uart.readline()     # read a line
+uart.readinto(buf)  # read and store into the given buffer
+uart.write('abc')   # write the 3 characters
+```
+
+To check if there is anything to be read, use:
+
+```python
+uart.any()               # returns the number of characters available for reading
+```
+
+## Quick Usage Example
+
+```python
+from machine import UART
+# this uses the UART_1 default pins for TXD and RXD (``P3`` and ``P4``)
+uart = UART(1, baudrate=9600)
+uart.write('hello')
+uart.read(5) # read up to 5 bytes
+```
+
+## Quick Usage Example using non-default pins \(TXD/RXD only\)
+
+```python
+from machine import UART
+# this uses the UART_1 non-default pins for TXD and RXD (``P20`` and ``P21``)
+uart = UART(1, baudrate=9600, pins=('P20','P21'))
+uart.write('hello')
+uart.read(5) # read up to 5 bytes
+```
+
+## Quick Usage Example using non-default pins \(TXD/RXD and flow control\)
+
+```python
+from machine import UART
+# this uses the UART_1 non-default pins for TXD, RXD, RTS and CTS (``P20``, ``P21``, ``P22``and ``P23``)
+uart = UART(1, baudrate=9600, pins=('P20', 'P21', 'P22', 'P23'))
+uart.write('hello')
+uart.read(5) # read up to 5 bytes
+```
+
+## Constructors
+
+#### class machine.UART\(bus, ...\)
+
+Construct a UART object on the given `bus`. `bus` can be `0, 1 or 2`. If the `bus` is not given, the default one will be selected \(`0`\) or the selection will be made based on the given pins.
+
+{% hint style="danger" %}
+On the GPy/FiPy UART2 is unavailable because it is used to communicate with the cellular radio.
+{% endhint %}
+
+## Methods
+
+#### uart.init\(baudrate=9600, bits=8, parity=None, stop=1, \* , timeout\_chars=2, pins=\(TXD, RXD, RTS, CTS\)\)
+
+Initialise the UART bus with the given parameters:
+
+* `baudrate` is the clock rate.
+* `bits` is the number of bits per character. Can be `5, 6, 7 or 8`.
+* `parity` is the parity, `None`, UART.EVEN or UART.ODD.
+* `stop` is the number of stop bits, `1 or 2`.
+* `timeout_chars` Rx timeout defined in number of characters. The value given here will be multiplied by the time a characters takes to be transmitted at the configured `baudrate`.
+* `pins` is a 4 or 2 item list indicating the TXD, RXD, RTS and CTS pins \(in that order\). Any of the pins can be `None` if one wants the UART to operate with limited functionality. If the RTS pin is given the the RX pin must be given as well. The same applies to CTS. When no pins are given, then the default set of TXD \(P1\) and RXD \(P0\) pins is taken, and hardware flow control will be disabled. If `pins=None`, no pin assignment will be made.
+
+#### uart.deinit\(\)
+
+Turn off the UART bus.
+
+#### uart.any\(\)
+
+Return the number of characters available for reading.
+
+#### uart.read\(\[nbytes\]\)
+
+Read characters. If `nbytes` is specified then read at most that many bytes.
+
+Return value: a bytes object containing the bytes read in. Returns `None` on timeout.
+
+#### uart.readall\(\)
+
+Read as much data as possible.
+
+Return value: a bytes object or `None` on timeout.
+
+#### uart.readinto\(buf\[, nbytes\]\)
+
+Read bytes into the `buf`. If `nbytes` is specified then read at most that many bytes. Otherwise, read at most `len(buf)` bytes.
+
+Return value: number of bytes read and stored into `buf` or `None` on timeout.
+
+#### uart.readline\(\)
+
+Read a line, ending in a newline character. If such a line exists, return is immediate. If the timeout elapses, all available data is returned regardless of whether a newline exists.
+
+Return value: the line read or `None` on timeout if no data is available.
+
+#### uart.write\(buf\)
+
+Write the buffer of bytes to the bus.
+
+Return value: number of bytes written or None on timeout.
+
+#### uart.sendbreak\(\)
+
+Send a break condition on the bus. This drives the bus low for a duration of 13 bits. Return value: `None`.
+
+#### uart.wait\_tx\_done\(timeout\_ms\)
+
+Waits at most `timeout_ms` for the last Tx transaction to complete. Returns `True` if all data has been sent and the TX buffer has no data in it, otherwise returns `False`.
+
+## Constants
+
+* Parity types \(along with `None`\): `UART.EVEN`, `UART.ODD`
+* IRQ trigger sources: `UART.RX_ANY`
+

firmwareapi/pycom/machine/wdt.md

@@ -0,0 +1,28 @@
+# WDT
+
+The WDT is used to restart the system when the application crashes and ends up into a non recoverable state. After enabling, the application must "feed" the watchdog periodically to prevent it from expiring and resetting the system.
+
+## Quick Usage Example
+
+```python
+from machine import WDT
+wdt = WDT(timeout=2000)  # enable it with a timeout of 2 seconds
+wdt.feed()
+```
+
+## Constructors
+
+#### class machine.WDT\(id=0, timeout\)
+
+Create a WDT object and start it. The `id` can only be `0`. See the init method for the parameters of initialisation.
+
+## Methods
+
+#### wdt.init\(timeout\)
+
+Initialises the watchdog timer. The timeout must be given in milliseconds. Once it is running the WDT cannot be stopped but the timeout can be re-configured at any point in time.
+
+#### wdt.feed\(\)
+
+Feed the WDT to prevent it from resetting the system. The application should place this call in a sensible place ensuring that the WDT is only fed after verifying that everything is functioning correctly.
+

firmwareapi/pycom/network/README.md

@@ -0,0 +1,4 @@
+# network
+
+This module provides access to network drivers and routing configuration. Network drivers for specific hardware are available within this module and are used to configure specific hardware network interfaces.
+

firmwareapi/pycom/network/bluetooth/README.md

@@ -0,0 +1,249 @@
+# Bluetooth
+
+This class provides a driver for the Bluetooth radio in the module. Currently, only basic BLE functionality is available.
+
+## Quick Usage Example
+
+```python
+from network import Bluetooth
+import time
+bt = Bluetooth()
+bt.start_scan(-1)
+
+while True:
+  adv = bt.get_adv()
+  if adv and bt.resolve_adv_data(adv.data, Bluetooth.ADV_NAME_CMPL) == 'Heart Rate':
+      try:
+          conn = bt.connect(adv.mac)
+          services = conn.services()
+          for service in services:
+              time.sleep(0.050)
+              if type(service.uuid()) == bytes:
+                  print('Reading chars from service = {}'.format(service.uuid()))
+              else:
+                  print('Reading chars from service = %x' % service.uuid())
+              chars = service.characteristics()
+              for char in chars:
+                  if (char.properties() & Bluetooth.PROP_READ):
+                      print('char {} value = {}'.format(char.uuid(), char.read()))
+          conn.disconnect()
+          break
+      except:
+          print("Error while connecting or reading from the BLE device")
+          break
+  else:
+      time.sleep(0.050)
+```
+
+## Bluetooth Low Energy \(BLE\)
+
+Bluetooth low energy \(BLE\) is a subset of classic Bluetooth, designed for easy connecting and communicating between devices \(in particular mobile platforms\). BLE uses a methodology known as Generic Access Profile \(GAP\) to control connections and advertising.
+
+GAP allows for devices to take various roles but generic flow works with devices that are either a Server \(low power, resource constrained, sending small payloads of data\) or a Client device \(commonly a mobile device, PC or Pycom Device with large resources and processing power\). Pycom devices can act as both a Client and a Server.
+
+## Constructors
+
+#### class network.Bluetooth\(id=0, ...\)
+
+Create a Bluetooth object, and optionally configure it. See init for params of configuration.
+
+Example:
+
+```python
+from network import Bluetooth
+bluetooth = Bluetooth()
+```
+
+## Methods
+
+#### bluetooth.init\(id=0, mode=Bluetooth.BLE, antenna=None\)
+
+* `id` Only one Bluetooth peripheral available so must always be 0
+* `mode` currently the only supported mode is `Bluetooth.BLE`
+* `antenna` selects between the internal and the external antenna. Can be either
+
+  `Bluetooth.INT_ANT`, `Bluetooth.EXT_ANT`.
+
+  With our development boards it defaults to using the internal antenna, but in
+
+  the case of an OEM module, the antenna pin \(`P12`\) is not used, so it’s free to be
+
+  used for other things.
+
+Initialises and enables the Bluetooth radio in BLE mode.
+
+#### bluetooth.deinit\(\)
+
+Disables the Bluetooth radio.
+
+#### bluetooth.start\_scan\(timeout\)
+
+Starts performing a scan listening for BLE devices sending advertisements. This function always returns immediately, the scanning will be performed on the background. The return value is `None`. After starting the scan the function `get_adv()` can be used to retrieve the advertisements messages from the FIFO. The internal FIFO has space to cache 16 advertisements.
+
+The arguments are:
+
+* `timeout` specifies the amount of time in seconds to scan for advertisements, cannot be zero. If timeout is > 0, then the BLE radio will listen for advertisements until the specified value in seconds elapses. If timeout < 0, then there’s no timeout at all, and stop\_scan\(\) needs to be called to cancel the scanning process.
+
+Examples:
+
+```python
+bluetooth.start_scan(10)        # starts scanning and stop after 10 seconds
+bluetooth.start_scan(-1)        # starts scanning indefinitely until bluetooth.stop_scan() is called
+```
+
+#### bluetooth.stop\_scan\(\)
+
+Stops an ongoing scanning process. Returns `None`.
+
+#### bluetooth.isscanning\(\)
+
+Returns `True` if a Bluetooth scan is in progress. `False` otherwise.
+
+#### bluetooth.get\_adv\(\)
+
+Gets an named tuple with the advertisement data received during the scanning. The tuple has the following structure: `(mac, addr_type, adv_type, rssi, data)`
+
+* `mac` is the 6-byte ling mac address of the device that sent the advertisement.
+* `addr_type` is the address type. See the constants section below for more details.
+* `adv_type` is the advertisement type received. See the constants section below fro more details.
+* `rssi` is signed integer with the signal strength of the advertisement.
+* `data` contains the complete 31 bytes of the advertisement message. In order to parse the data and get the specific types, the method `resolve_adv_data()` can be used.
+
+Example for getting `mac` address of an advertiser:
+
+```python
+import ubinascii
+
+bluetooth = Bluetooth()
+bluetooth.start_scan(20) # scan for 20 seconds
+
+adv = bluetooth.get_adv() #
+ubinascii.hexlify(adv.mac) # convert hexadecimal to ascii
+```
+
+#### bluetooth.get\_advertisements\(\)
+
+Same as the `get_adv()` method, but this one returns a list with all the advertisements received.
+
+#### bluetooth.resolve\_adv\_data\(data, data\_type\)
+
+Parses the advertisement data and returns the requested `data_type` if present. If the data type is not present, the function returns `None`.
+
+Arguments:
+
+* `data` is the bytes object with the complete advertisement data.
+* `data_type` is the data type to resolve from from the advertisement data. See constants section below for details.
+
+Example:
+
+```python
+import ubinascii
+from network import Bluetooth
+bluetooth = Bluetooth()
+
+bluetooth.start_scan(20)
+while bluetooth.isscanning():
+    adv = bluetooth.get_adv()
+    if adv:
+        # try to get the complete name
+        print(bluetooth.resolve_adv_data(adv.data, Bluetooth.ADV_NAME_CMPL))
+
+        mfg_data = bluetooth.resolve_adv_data(adv.data, Bluetooth.ADV_MANUFACTURER_DATA)
+
+        if mfg_data:
+            # try to get the manufacturer data (Apple's iBeacon data is sent here)
+            print(ubinascii.hexlify(mfg_data))
+```
+
+#### bluetooth.connect\(mac\_addr\)
+
+Opens a BLE connection with the device specified by the `mac_addr` argument. This function blocks until the connection succeeds or fails. If the connections succeeds it returns a object of type `GATTCConnection`.
+
+```python
+bluetooth.connect('112233eeddff') # mac address is accepted as a string
+```
+
+#### bluetooth.callback\(trigger=None, handler=None, arg=None\)
+
+Creates a callback that will be executed when any of the triggers occurs. The arguments are:
+
+* `trigger` can be either `Bluetooth.NEW_ADV_EVENT`, `Bluetooth.CLIENT_CONNECTED`, or `Bluetooth.CLIENT_DISCONNECTED`
+* `handler` is the function that will be executed when the callback is triggered.
+* `arg` is the argument that gets passed to the callback. If nothing is given the bluetooth object itself is used.
+
+An example of how this may be used can be seen in the [`bluetooth.events()`](./#bluetooth-events) method.
+
+#### bluetooth.events\(\)
+
+Returns a value with bit flags identifying the events that have occurred since the last call. Calling this function clears the events.
+
+Example of usage:
+
+```python
+from network import Bluetooth
+
+bluetooth = Bluetooth()
+bluetooth.set_advertisement(name='LoPy', service_uuid=b'1234567890123456')
+
+def conn_cb (bt_o):
+    events = bt_o.events()   # this method returns the flags and clears the internal registry
+    if events & Bluetooth.CLIENT_CONNECTED:
+        print("Client connected")
+    elif events & Bluetooth.CLIENT_DISCONNECTED:
+        print("Client disconnected")
+
+bluetooth.callback(trigger=Bluetooth.CLIENT_CONNECTED | Bluetooth.CLIENT_DISCONNECTED, handler=conn_cb)
+
+bluetooth.advertise(True)
+```
+
+#### bluetooth.set\_advertisement\(\* , name=None, manufacturer\_data=None, service\_data=None, service\_uuid=None\)
+
+Configure the data to be sent while advertising. If left with the default of `None` the data won’t be part of the advertisement message.
+
+The arguments are:
+
+* `name` is the string name to be shown on advertisements.
+* `manufacturer_data` manufacturer data to be advertised \(hint: use it for iBeacons\).
+* `service_data` service data to be advertised.
+* `service_uuid` uuid of the service to be advertised.
+
+Example:
+
+```python
+bluetooth.set_advertisement(name="advert", manufacturer_data="lopy_v1")
+```
+
+#### bluetooth.advertise\(\[Enable\]\)
+
+Start or stop sending advertisements. The `set_advertisement()` method must have been called prior to this one.
+
+#### bluetooth.service\(uuid, \* , isprimary=True, nbr\_chars=1, start=True\)
+
+Create a new service on the internal GATT server. Returns a object of type `BluetoothServerService`.
+
+The arguments are:
+
+* `uuid` is the UUID of the service. Can take an integer or a 16 byte long string or bytes object.
+* `isprimary` selects if the service is a primary one. Takes a `bool` value.
+* `nbr_chars` specifies the number of characteristics that the service will contain.
+* `start` if `True` the service is started immediately.
+
+```python
+bluetooth.service('abc123')
+```
+
+#### bluetooth.disconnect\_client\(\)
+
+Closes the BLE connection with the client.
+
+## Constants
+
+* Bluetooth mode: `Bluetooth.BLE`
+* Advertisement type: `Bluetooth.CONN_ADV`, `Bluetooth.CONN_DIR_ADV`, `Bluetooth.DISC_ADV`, `Bluetooth.NON_CONN_ADV`, `Bluetooth.SCAN_RSP`
+* Address type: `Bluetooth.PUBLIC_ADDR`, `Bluetooth.RANDOM_ADDR`, `Bluetooth.PUBLIC_RPA_ADDR`, `Bluetooth.RANDOM_RPA_ADDR`
+* Advertisement data type: `Bluetooth.ADV_FLAG`, `Bluetooth.ADV_16SRV_PART`, `Bluetooth.ADV_T16SRV_CMPL`, `Bluetooth.ADV_32SRV_PART`, `Bluetooth.ADV_32SRV_CMPL`, `Bluetooth.ADV_128SRV_PART`, `Bluetooth.ADV_128SRV_CMPL`, `Bluetooth.ADV_NAME_SHORT`, `Bluetooth.ADV_NAME_CMPL`, `Bluetooth.ADV_TX_PWR`, `Bluetooth.ADV_DEV_CLASS`, `Bluetooth.ADV_SERVICE_DATA`, `Bluetooth.ADV_APPEARANCE`, `Bluetooth.ADV_ADV_INT`, `Bluetooth.ADV_32SERVICE_DATA`, `Bluetooth.ADV_128SERVICE_DATA`, `Bluetooth.ADV_MANUFACTURER_DATA`
+* Characteristic properties \(bit values that can be combined\): `Bluetooth.PROP_BROADCAST`, `Bluetooth.PROP_READ`, `Bluetooth.PROP_WRITE_NR`, `Bluetooth.PROP_WRITE`, `Bluetooth.PROP_NOTIFY`, `Bluetooth.PROP_INDICATE`, `Bluetooth.PROP_AUTH`, `Bluetooth.PROP_EXT_PROP`
+* Characteristic callback events: `Bluetooth.CHAR_READ_EVENT`, `Bluetooth.CHAR_WRITE_EVENT`, `Bluetooth.NEW_ADV_EVENT`, `Bluetooth.CLIENT_CONNECTED`, `Bluetooth.CLIENT_DISCONNECTED`, `Bluetooth.CHAR_NOTIFY_EVENT`
+* Antenna type: `Bluetooth.INT_ANT`, `Bluetooth.EXT_ANT`
+

firmwareapi/pycom/network/bluetooth/gatt.md

@@ -0,0 +1,8 @@
+# GATT
+
+GATT stands for the Generic Attribute Profile and it defines the way that two Bluetooth Low Energy devices communicate between each other using concepts called Services and Characteristics. GATT uses a data protocol known as the Attribute Protocol \(ATT\), which is used to store/manage Services, Characteristics and related data in a lookup table.
+
+GATT comes into use once a connection is established between two devices, meaning that the device will have already gone through the advertising process managed by GAP. It’s important to remember that this connection is exclusive; i.e. that only one client is connected to one server at a time. This means that the client will stop advertising once a connection has been made. This remains the case, until the connection is broken or disconnected.
+
+The GATT Server, which holds the ATT lookup data and service and characteristic definitions, and the GATT Client \(the phone/tablet\), which sends requests to this server.
+

firmwareapi/pycom/network/bluetooth/gattccharacteristic.md

@@ -0,0 +1,44 @@
+# GATTCCharacteristic
+
+The smallest concept in GATT is the Characteristic, which encapsulates a single data point \(though it may contain an array of related data, such as X/Y/Z values from a 3-axis accelerometer, longitude and latitude from a GPS, etc.\).
+
+The following class allows you to manage characteristics from a Client.
+
+## Methods
+
+#### characteristic.uuid\(\)
+
+Returns the UUID of the service. In the case of 16-bit or 32-bit long UUIDs, the value returned is an integer, but for 128-bit long UUIDs the value returned is a bytes object.
+
+#### characteristic.instance\(\)
+
+Returns the instance ID of the service.
+
+#### characteristic.properties\(\)
+
+Returns an integer indicating the properties of the characteristic. Properties are represented by bit values that can be OR-ed together. See the constants section for more details.
+
+#### characteristic.read\(\)
+
+Read the value of the characteristic, sending a request to the GATT server. Returns a bytes object representing the characteristic value.
+
+#### characteristic.value\(\)
+
+Returns the locally stored value of the characteristic without sending a read request to the GATT server. If the characteristic value hasn't been read from the GATT server yet, the value returned will be 0.
+
+#### characteristic.write\(value\)
+
+Writes the given value on the characteristic. For now it only accepts bytes object representing the value to be written.
+
+```python
+characteristic.write(b'x0f')
+```
+
+#### characteristic.callback\(trigger=None, handler=None, arg=None\)
+
+This method allows to register for notifications on the characteristic.
+
+* `trigger` can must be `Bluetooth.CHAR_NOTIFY_EVENT`.
+* `handler` is the function that will be executed when the callback is triggered.
+* `arg` is the argument that gets passed to the callback. If nothing is given, the characteristic object that owns the callback will be used.
+

firmwareapi/pycom/network/bluetooth/gattcconnection.md

@@ -0,0 +1,51 @@
+# GATTCConnection
+
+The GATT Client is the device that requests data from the server, otherwise known as the master device \(commonly this might be a phone/tablet/PC\). All transactions are initiated by the master, which receives a response from the slave.
+
+## Methods
+
+#### connection.disconnect\(\)
+
+Closes the BLE connection. Returns `None`.
+
+#### connection.isconnected\(\)
+
+Returns `True` if the connection is still open. `False` otherwise.
+
+Example:
+
+```python
+from network import Bluetooth
+import ubinascii
+bluetooth = Bluetooth()
+
+# scan until we can connect to any BLE device around
+bluetooth.start_scan(-1)
+adv = None
+while True:
+    adv = bluetooth.get_adv()
+    if adv:
+        try:
+            bluetooth.connect(adv.mac)
+        except:
+            # start scanning again
+            bluetooth.start_scan(-1)
+            continue
+        break
+print("Connected to device with addr = {}".format(ubinascii.hexlify(adv.mac)))
+```
+
+#### connection.services\(\)
+
+Performs a service search on the connected BLE peripheral \(server\) a returns a list containing objects of the class GATTCService if the search succeeds.
+
+Example:
+
+```python
+# assuming that a BLE connection is already open
+services = connection.services()
+print(services)
+for service in services:
+    print(service.uuid())
+```
+

firmwareapi/pycom/network/bluetooth/gattccservice.md

@@ -0,0 +1,24 @@
+# GATTCService
+
+Services are used to categorise data up into specific chunks of data known as characteristics. A service may have multiple characteristics, and each service has a unique numeric ID called a UUID.
+
+The following class allows control over Client services.
+
+## Methods
+
+#### service.isprimary\(\)
+
+Returns `True` if the service is a primary one. `False` otherwise.
+
+#### service.uuid\(\)
+
+Returns the UUID of the service. In the case of 16-bit or 32-bit long UUIDs, the value returned is an integer, but for 128-bit long UUIDs the value returned is a bytes object.
+
+#### service.instance\(\)
+
+Returns the instance ID of the service.
+
+#### service.characteristics\(\)
+
+Performs a get characteristics request on the connected BLE peripheral a returns a list containing objects of the class GATTCCharacteristic if the request succeeds.
+

firmwareapi/pycom/network/bluetooth/gattscharacteristic.md

@@ -0,0 +1,83 @@
+# GATTSCharacteristic
+
+The smallest concept in GATT is the Characteristic, which encapsulates a single data point \(though it may contain an array of related data, such as X/Y/Z values from a 3-axis accelerometer, longitude and latitude from a GPS, etc.\).
+
+The following class allows you to manage Server characteristics.
+
+## Methods
+
+#### characteristic.value\(\[value\]\)
+
+Gets or sets the value of the characteristic. Can take an integer, a string or a bytes object.
+
+```python
+characteristic.value(123) # set characteristic value to an integer with the value 123
+characteristic.value() # get characteristic value
+```
+
+#### characteristic.callback\(trigger=None, handler=None, arg=None\)
+
+Creates a callback that will be executed when any of the triggers occurs. The arguments are:
+
+* `trigger` can be either `Bluetooth.CHAR_READ_EVENT` or `Bluetooth.CHAR_WRITE_EVENT`.
+* `handler` is the function that will be executed when the callback is triggered.
+* `arg` is the argument that gets passed to the callback. If nothing is given, the characteristic object that owns the callback will be used.
+
+An example of how this could be implemented can be seen in the [`characteristic.events()` ](gattscharacteristic.md#characteristic-events)section.
+
+#### characteristic.events\(\)
+
+Returns a value with bit flags identifying the events that have occurred since the last call. Calling this function clears the events.
+
+An example of advertising and creating services on the device:
+
+```python
+from network import Bluetooth
+
+bluetooth = Bluetooth()
+bluetooth.set_advertisement(name='LoPy', service_uuid=b'1234567890123456')
+
+def conn_cb (bt_o):
+    events = bt_o.events()
+    if  events & Bluetooth.CLIENT_CONNECTED:
+        print("Client connected")
+    elif events & Bluetooth.CLIENT_DISCONNECTED:
+        print("Client disconnected")
+
+bluetooth.callback(trigger=Bluetooth.CLIENT_CONNECTED | Bluetooth.CLIENT_DISCONNECTED, handler=conn_cb)
+
+bluetooth.advertise(True)
+
+srv1 = bluetooth.service(uuid=b'1234567890123456', isprimary=True)
+
+chr1 = srv1.characteristic(uuid=b'ab34567890123456', value=5)
+
+char1_read_counter = 0
+def char1_cb_handler(chr):
+    global char1_read_counter
+    char1_read_counter += 1
+
+    events = chr.events()
+    if  events & Bluetooth.CHAR_WRITE_EVENT:
+        print("Write request with value = {}".format(chr.value()))
+    else:
+        if char1_read_counter < 3:
+            print('Read request on char 1')
+        else:
+            return 'ABC DEF'
+
+char1_cb = chr1.callback(trigger=Bluetooth.CHAR_WRITE_EVENT | Bluetooth.CHAR_READ_EVENT, handler=char1_cb_handler)
+
+srv2 = bluetooth.service(uuid=1234, isprimary=True)
+
+chr2 = srv2.characteristic(uuid=4567, value=0x1234)
+char2_read_counter = 0xF0
+def char2_cb_handler(chr):
+    global char2_read_counter
+    char2_read_counter += 1
+    if char2_read_counter > 0xF1:
+        return char2_read_counter
+
+char2_cb = chr2.callback(trigger=Bluetooth.CHAR_READ_EVENT, handler=char2_cb_handler)
+```
+

firmwareapi/pycom/network/bluetooth/gattsservice.md

@@ -0,0 +1,31 @@
+# GATTSService
+
+The GATT Server allows the device to act as a peripheral and hold its own ATT lookup data, server & characteristic definitions. In this mode, the device acts as a slave and a master must initiate a request.
+
+Services are used to categorise data up into specific chunks of data known as characteristics. A service may have multiple characteristics, and each service has a unique numeric ID called a UUID.
+
+The following class allows control over Server services.
+
+## Methods
+
+#### service.start\(\)
+
+Starts the service if not already started.
+
+#### service.stop\(\)
+
+Stops the service if previously started.
+
+#### service.characteristic\(uuid, \* , permissions, properties, value\)
+
+Creates a new characteristic on the service. Returns an object of the class `GATTSCharacteristic`. The arguments are:
+
+* `uuid` is the UUID of the service. Can take an integer or a 16 byte long string or bytes object.
+* `permissions` configures the permissions of the characteristic. Takes an integer with a combination of the flags.
+* `properties` sets the properties. Takes an integer with an OR-ed combination of the flags.
+* `value` sets the initial value. Can take an integer, a string or a bytes object.
+
+```python
+service.characteristic('temp', value=25)
+```
+

firmwareapi/pycom/network/lora.md

@@ -0,0 +1,486 @@
+# LoRa
+
+This class provides a LoRaWAN 1.0.2 compliant driver for the LoRa network processor in the LoPy and FiPy. Below is an example demonstrating LoRaWAN Activation by Personalisation usage:
+
+```python
+from network import LoRa
+import socket
+import ubinascii
+import struct
+
+# Initialise LoRa in LORAWAN mode.
+# Please pick the region that matches where you are using the device:
+# Asia = LoRa.AS923
+# Australia = LoRa.AU915
+# Europe = LoRa.EU868
+# United States = LoRa.US915
+lora = LoRa(mode=LoRa.LORAWAN, region=LoRa.EU868)
+
+# create an ABP authentication params
+dev_addr = struct.unpack(">l", binascii.unhexlify('00000005'))[0]
+nwk_swkey = ubinascii.unhexlify('2B7E151628AED2A6ABF7158809CF4F3C')
+app_swkey = ubinascii.unhexlify('2B7E151628AED2A6ABF7158809CF4F3C')
+
+# join a network using ABP (Activation By Personalisation)
+lora.join(activation=LoRa.ABP, auth=(dev_addr, nwk_swkey, app_swkey))
+
+# create a LoRa socket
+s = socket.socket(socket.AF_LORA, socket.SOCK_RAW)
+
+# set the LoRaWAN data rate
+s.setsockopt(socket.SOL_LORA, socket.SO_DR, 5)
+
+# make the socket non-blocking
+s.setblocking(False)
+
+# send some data
+s.send(bytes([0x01, 0x02, 0x03]))
+
+# get any data received...
+data = s.recv(64)
+print(data)
+```
+
+{% hint style="danger" %}
+Please ensure that there is an antenna connected to your device before sending/receiving LoRa messages as improper use \(e.g. without an antenna\), may damage the device.
+{% endhint %}
+
+## Additional Examples
+
+For various other complete LoRa examples, check here for additional examples.
+
+## Constructors
+
+#### class network.LoRa\(id=0, ...\)
+
+Create and configure a LoRa object. See init for params of configuration.
+
+```python
+lora = LoRa(mode=LoRa.LORAWAN, region=LoRa.EU868)
+```
+
+## Methods
+
+#### lora.init\(mode, \* ,region=LoRa.EU868, frequency=868000000, tx\_power=14, bandwidth=LoRa.BW\_125KHZ, sf=7, preamble=8, coding\_rate=LoRa.CODING\_4\_5, power\_mode=LoRa.ALWAYS\_ON, tx\_iq=False, rx\_iq=False, adr=False, public=True, tx\_retries=1, device\_class=LoRa.CLASS\_A\)
+
+This method is used to set the LoRa subsystem configuration and to specific raw LoRa or LoRaWAN.
+
+The arguments are:
+
+* `mode` can be either `LoRa.LORA` or `LoRa.LORAWAN`.
+* `region` can take the following values: `LoRa.AS923`, `LoRa.AU915`, `LoRa.EU868` or `LoRa.US915`. If not provided this will default to `LoRaEU868`. If they are not specified, this will also set appropriate defaults for `frequency` and `tx_power`.
+* `frequency` accepts values between `863000000` and `870000000` in the 868 band, or between `902000000` and `928000000` in the 915 band.
+* `tx_power` is the transmit power in dBm. It accepts between 2 and 14 for the 868 band, and between 5 and 20 in the 915 band.
+* `bandwidth` is the channel bandwidth in KHz. In the 868 band the accepted values are `LoRa.BW_125KHZ` and `LoRa.BW_250KHZ`. In the 915 band the accepted values are `LoRa.BW_125KHZ` and `LoRa.BW_500KHZ`.
+* `sf` sets the desired spreading factor. Accepts values between 7 and 12.
+* `preamble` configures the number of pre-amble symbols. The default value is 8.
+* `coding_rate` can take the following values: `LoRa.CODING_4_5`, `LoRa.CODING_4_6`, `LoRa.CODING_4_7` or `LoRa.CODING_4_8`.
+* `power_mode` can be either `LoRa.ALWAYS_ON`, `LoRa.TX_ONLY` or `LoRa.SLEEP`. In `ALWAYS_ON` mode, the radio is always listening for incoming - packets whenever a transmission is not taking place. In `TX_ONLY` the radio goes to sleep as soon as the transmission completes. In `SLEEP` mode the radio is sent to sleep permanently and won’t accept any commands until the power mode is changed.
+* `tx_iq` enables TX IQ inversion.
+* `rx_iq` enables RX IQ inversion.
+* `adr` enables Adaptive Data Rate.
+* `public` selects between the public and private sync word.
+* `tx_retries` sets the number of TX retries in `LoRa.LORAWAN` mode.
+* `device_class` sets the LoRaWAN device class. Can be either `LoRa.CLASS_A` or `LoRa.CLASS_C`.
+
+{% hint style="info" %}
+In `LoRa.LORAWAN` mode, only `adr`, `public`, `tx_retries` and `device_class` are used. All the other params will be ignored as they are handled by the LoRaWAN stack directly. On the other hand, in `LoRa.LORA` mode from those 4 arguments, only the public one is important in order to program the sync word. In `LoRa.LORA` mode `adr`, `tx_retries` and `device_class` are ignored since they are only relevant to the LoRaWAN stack.
+{% endhint %}
+
+For example, you can do:
+
+```python
+# initialize in raw LoRa mode
+lora.init(mode=LoRa.LORA, tx_power=14, sf=12)
+```
+
+or
+
+```python
+# initialize in LoRaWAN mode
+lora.init(mode=LoRa.LORAWAN)
+```
+
+#### lora.join\(activation, auth, \* ,timeout=None, dr=None\)
+
+Join a LoRaWAN network. Internally the stack will automatically retry every 15 seconds until a Join Accept message is received.
+
+The parameters are:
+
+* `activation`: can be either `LoRa.OTAA` or `LoRa.ABP`.
+* `auth`: is a tuple with the authentication data.
+* `timeout`: is the maximum time in milliseconds to wait for the Join Accept message to be received. If no timeout \(or zero\) is given, the call returns immediately and the status of the join request can be checked with `lora.has_joined()`.
+* `dr`: is an optional value to specify the initial data rate for the Join Request. Possible values are 0 to 5 for **EU868**, or 0 to 4 for **US915**.
+
+In the case of `LoRa.OTAA` the authentication tuple is: `(dev_eui, app_eui, app_key)` where `dev_eui` is optional. If it is not provided the LoRa MAC will be used. Therefore, you can do OTAA in 2 different ways:
+
+```python
+lora.join(activation=LoRa.OTAA, auth=(app_eui, app_key), timeout=0)  # the device MAC address is used as DEV_EUI
+```
+
+or
+
+```python
+lora.join(activation=LoRa.OTAA, auth=(dev_eui, app_eui, app_key), timeout=0) # a custom DEV_EUI is specified
+```
+
+Example:
+
+```python
+from network import LoRa
+import socket
+import time
+import ubinascii
+
+# Initialise LoRa in LORAWAN mode.
+# Please pick the region that matches where you are using the device:
+# Asia = LoRa.AS923
+# Australia = LoRa.AU915
+# Europe = LoRa.EU868
+# United States = LoRa.US915
+lora = LoRa(mode=LoRa.LORAWAN, region=LoRa.EU868)
+
+# create an OTAA authentication parameters
+app_eui = ubinascii.unhexlify('ADA4DAE3AC12676B')
+app_key = ubinascii.unhexlify('11B0282A189B75B0B4D2D8C7FA38548B')
+
+# join a network using OTAA (Over the Air Activation)
+lora.join(activation=LoRa.OTAA, auth=(app_eui, app_key), timeout=0)
+
+# wait until the module has joined the network
+while not lora.has_joined():
+    time.sleep(2.5)
+    print('Not yet joined...')
+```
+
+In the case of `LoRa.ABP` the authentication tuple is: `(dev_addr, nwk_swkey, app_swkey)`. Example:
+
+```python
+from network import LoRa
+import socket
+import ubinascii
+import struct
+
+# Initialise LoRa in LORAWAN mode.
+# Please pick the region that matches where you are using the device:
+# Asia = LoRa.AS923
+# Australia = LoRa.AU915
+# Europe = LoRa.EU868
+# United States = LoRa.US915
+lora = LoRa(mode=LoRa.LORAWAN, region=LoRa.EU868)
+
+# create an ABP authentication params
+dev_addr = struct.unpack(">l", ubinascii.unhexlify('00000005'))[0]
+nwk_swkey = ubinascii.unhexlify('2B7E151628AED2A6ABF7158809CF4F3C')
+app_swkey = ubinascii.unhexlify('2B7E151628AED2A6ABF7158809CF4F3C')
+
+# join a network using ABP (Activation By Personalisation)
+lora.join(activation=LoRa.ABP, auth=(dev_addr, nwk_swkey, app_swkey))
+```
+
+#### lora.bandwidth\(\[bandwidth\]\)
+
+Get or set the bandwidth in raw LoRa mode \(`LoRa.LORA`\). Can be either `LoRa.BW_125KHZ` \(0\), `LoRa.BW_250KHZ` \(1\) or `LoRa.BW_500KHZ` \(2\):
+
+```python
+# get raw LoRa Bandwidth
+lora.bandwidth()
+
+# set raw LoRa Bandwidth
+lora.bandwidth(LoRa.BW_125KHZ)
+```
+
+#### lora.frequency\(\[frequency\]\)
+
+Get or set the frequency in raw LoRa mode \(`LoRa.LORA`\). The allowed range is between `863000000` and `870000000` Hz for the 868 MHz band version or between `902000000` and `928000000` Hz for the 915 MHz band version.
+
+```python
+# get raw LoRa Frequency
+lora.frequency()
+
+# set raw LoRa Frequency
+lora.frequency(868000000)
+```
+
+#### lora.coding\_rate\(\[coding\_rate\]\)
+
+Get or set the coding rate in raw LoRa mode \(`LoRa.LORA`\). The allowed values are: `LoRa.CODING_4_5` \(1\), `LoRa.CODING_4_6` \(2\), `LoRa.CODING_4_7` \(3\) and `LoRa.CODING_4_8` \(4\).
+
+```python
+# get raw LoRa Coding Rate
+lora.coding_rate()
+
+# set raw LoRa Coding Rate
+lora.coding_rate(LoRa.CODING_4_5)
+```
+
+#### lora.preamble\(\[preamble\]\)
+
+Get or set the number of preamble symbols in raw LoRa mode \(`LoRa.LORA`\):
+
+```python
+# get raw LoRa preamble symbols
+lora.preamble()
+
+# set raw LoRa preamble symbols
+lora.preamble(LoRa.CODING_4_5)
+```
+
+#### lora.sf\(\[sf\]\)
+
+Get or set the spreading factor value in raw LoRa mode \(`LoRa.LORA`\). The minimum value is 7 and the maximum is 12:
+
+```python
+# get raw LoRa spread factor value
+lora.sf()
+
+# set raw LoRa spread factor value
+lora.sf(7)
+```
+
+#### lora.power\_mode\(\[power\_mode\]\)
+
+Get or set the power mode in raw LoRa mode \(`LoRa.LORA`\). The accepted values are: `LoRa.ALWAYS_ON`, `LoRa.TX_ONLY`, and `LoRa.SLEEP`:
+
+#### lora.stats\(\)
+
+Return a named tuple with useful information from the last received LoRa or LoRaWAN packet. The named tuple has the following form:
+
+`(rx_timestamp, rssi, snr, sftx, sfrx, tx_trials, tx_power, tx_time_on_air, tx_counter, tx_frequency)`
+
+Example:
+
+```python
+lora.stats()
+```
+
+Where:
+
+* `rx_timestamp` is an internal timestamp of the last received packet with microseconds precision.
+* `rssi` holds the received signal strength in dBm.
+* `snr` contains the signal to noise ratio id dB \(as a single precision float\).
+* `sfrx` tells the data rate \(in the case of LORAWAN mode\) or the spreading factor \(in the case of LORA mode\) of the last packet received.
+* `sftx` tells the data rate \(in the case of LORAWAN mode\) or the spreading factor \(in the case of LORA mode\) of the last packet transmitted.
+* `tx_trials` is the number of tx attempts of the last transmitted packet \(only relevant for LORAWAN confirmed packets\).
+* `tx_power` is the power of the last transmission \(in dBm\).
+* `tx_time_on_air` is the time on air of the last transmitted packet \(in ms\).
+* `tx_counter` is the number of packets transmitted.
+* `tx_frequency` is the frequency used for the last transmission.
+
+#### lora.has\_joined\(\)
+
+Returns `True` if a LoRaWAN network has been joined. `False` otherwise.
+
+#### lora.add\_channel\(index, \* , frequency, dr\_min, dr\_max\)
+
+Add a LoRaWAN channel on the specified `index`. If there’s already a channel with that index it will be replaced with the new one.
+
+The arguments are:
+
+* `index`: Index of the channel to add. Accepts values between 0 and 15 for EU and between 0 and 71 for US.
+* `frequency`: Centre frequency in Hz of the channel.
+* `dr_min`: Minimum data rate of the channel \(0-7\).
+* `dr_max`: Maximum data rate of the channel \(0-7\).
+
+Examples:
+
+```python
+lora.add_channel(index=0, frequency=868000000, dr_min=5, dr_max=6)
+```
+
+#### lora.remove\_channel\(index\)
+
+Removes the channel from the specified `index`. On the 868MHz band the channels 0 to 2 cannot be removed, they can only be replaced by other channels using the `lora.add_channel` method. A way to remove all channels except for one is to add the same channel, 3 times on indexes 0, 1 and 2. An example can be seen below:
+
+```python
+lora.remove_channel()
+```
+
+On the 915MHz band there are no restrictions around this.
+
+#### lora.mac\(\)
+
+Returns a byte object with the 8-Byte MAC address of the LoRa radio.
+
+#### lora.callback\(trigger, handler=None, arg=None\)
+
+Specify a callback handler for the LoRa radio. The `trigger` types are `LoRa.RX_PACKET_EVENT`, `LoRa.TX_PACKET_EVENT`, and `LoRa.TX_FAILED_EVENT`
+
+The `LoRa.RX_PACKET_EVENT` event is raised for every received packet. The `LoRa.TX_PACKET_EVENT` event is raised as soon as the packet transmission cycle ends, which includes the end of the receive windows \(even if a downlink is received, the `LoRa.TX_PACKET_EVENT` will come last\). In the case of non-confirmed transmissions, this will occur at the end of the receive windows, but, in the case of confirmed transmissions, this event will only be raised if the `ack` is received. If the `ack` is not received `LoRa.TX_FAILED_EVENT` will be raised after the number of `tx_retries` configured have been performed.
+
+An example of how this callback functions can be seen the in method [`lora.events()`](lora.md#lora-events).
+
+#### lora.ischannel\_free\(rssi\_threshold\)
+
+This method is used to check for radio activity on the current LoRa channel, and if the `rssi` of the measured activity is lower than the `rssi_threshold` given, the return value will be `True`, otherwise `False`. Example:
+
+```python
+lora.ischannel_free(-100)
+```
+
+#### lora.set\_battery\_level\(level\)
+
+Set the battery level value that will be sent when the LoRaWAN MAC command that retrieves the battery level is received. This command is sent by the network and handled automatically by the LoRaWAN stack. The values should be according to the LoRaWAN specification:
+
+* `0` means that the end-device is connected to an external power source.
+* `1..254` specifies the battery level, 1 being at minimum and 254 being at maximum.
+* `255` means that the end-device was not able to measure the battery level.
+
+```python
+lora.set_battery_level(127) # 50% battery
+```
+
+#### lora.events\(\)
+
+This method returns a value with bits sets \(if any\) indicating the events that have triggered the callback. Please note that by calling this function the internal events registry is cleared automatically, therefore calling it immediately for a second time will most likely return a value of 0.
+
+Example:
+
+```python
+def lora_cb(lora):
+    events = lora.events()
+    if events & LoRa.RX_PACKET_EVENT:
+        print('Lora packet received')
+    if events & LoRa.TX_PACKET_EVENT:
+        print('Lora packet sent')
+
+lora.callback(trigger=(LoRa.RX_PACKET_EVENT | LoRa.TX_PACKET_EVENT), handler=lora_cb)
+```
+
+#### lora.nvram\_save\(\)
+
+Save the LoRaWAN state \(joined status, network keys, packet counters, etc\) in non-volatile memory in order to be able to restore the state when coming out of deepsleep or a power cycle.
+
+```python
+lora.nvram_save()
+```
+
+#### lora.nvram\_restore\(\)
+
+Restore the LoRaWAN state \(joined status, network keys, packet counters, etc\) from non-volatile memory. State must have been previously stored with a call to `nvram_save` before entering deepsleep. This is useful to be able to send a LoRaWAN message immediately after coming out of deepsleep without having to join the network again. This can only be used if the current region matches the one saved.
+
+```python
+lora.nvram_restore()
+```
+
+#### lora.nvram\_erase\(\)
+
+Remove the LoRaWAN state \(joined status, network keys, packet counters, etc\) from non-volatile memory.
+
+```python
+lora.nvram_erase()
+```
+
+## Constants
+
+* LoRa stack mode: `LoRa.LORA`, `LoRa.LORAWAN`
+* LoRaWAN join procedure: `LoRa.OTAA`, `LoRa.ABP`
+* Raw LoRa power mode: `LoRa.ALWAYS_ON`, `LoRa.TX_ONLY`, `LoRa.SLEEP`
+* Raw LoRa bandwidth: `LoRa.BW_125KHZ`, `LoRa.BW_250KHZ`, `LoRa.BW_500KHZ`
+* Raw LoRa coding rate: `LoRa.CODING_4_5`, `LoRa.CODING_4_6`, `LoRa.CODING_4_7`, `LoRa.CODING_4_8`
+* Callback trigger types \(may be ORed\): `LoRa.RX_PACKET_EVENT`, `LoRa.TX_PACKET_EVENT`, `LoRa.TX_FAILED_EVENT`
+* LoRaWAN device class: `LoRa.CLASS_A`, `LoRa.CLASS_C`
+* LoRaWAN regions: `LoRa.AS923`, `LoRa.AU915`, `LoRa.EU868`, `LoRa.US915`
+
+## Working with LoRa and LoRaWAN Sockets
+
+LoRa sockets are created in the following way:
+
+```python
+import socket
+s = socket.socket(socket.AF_LORA, socket.SOCK_RAW)
+```
+
+And they must be created after initialising the LoRa network card.
+
+LoRa sockets support the following standard methods from the socket module:
+
+#### socket.close\(\)
+
+Usage:
+
+```python
+s.close()
+```
+
+#### socket.bind\(port\_number\)
+
+Usage:
+
+```python
+s.bind(1)
+```
+
+{% hint style="info" %}
+The `bind()` method is only applicable when the radio is configured in `LoRa.LORAWAN` mode.
+{% endhint %}
+
+#### socket.send\(bytes\)
+
+Usage:
+
+```python
+s.send(bytes([1, 2, 3]))
+```
+
+or
+
+```python
+s.send('Hello')
+```
+
+#### socket.recv\(bufsize\)
+
+Usage:
+
+```python
+s.recv(128)
+```
+
+#### socket.recvfrom\(bufsize\)
+
+This method is useful to know the destination port number of the message received. Returns a tuple of the form: `(data, port)`
+
+Usage:
+
+```python
+s.recvfrom(128)
+```
+
+#### socket.setsockopt\(level, optname, value\)
+
+Set the value of the given socket option. The needed symbolic constants are defined in the socket module \(`SO_*` etc.\). In the case of LoRa the values are always integers. Examples:
+
+```python
+# configuring the data rate
+s.setsockopt(socket.SOL_LORA, socket.SO_DR, 5)
+
+# selecting non-confirmed type of messages
+s.setsockopt(socket.SOL_LORA, socket.SO_CONFIRMED, False)
+
+# selecting confirmed type of messages
+s.setsockopt(socket.SOL_LORA, socket.SO_CONFIRMED, True)
+```
+
+{% hint style="info" %}
+Socket options are only applicable when the LoRa radio is used in LoRa.LORAWAN mode. When using the radio in LoRa.LORA mode, use the class methods to change the spreading factor, bandwidth and coding rate to the desired values.
+{% endhint %}
+
+#### socket.settimeout\(value\)
+
+Sets the socket timeout value in seconds. Accepts floating point values.
+
+Usage:
+
+```python
+s.settimeout(5.5)
+```
+
+#### socket.setblocking\(flag\)
+
+Usage:
+
+```python
+s.setblocking(True)
+```
+

firmwareapi/pycom/network/lte.md

@@ -0,0 +1,125 @@
+# LTE
+
+The LTE class provides access to the LTE-M/NB-IoT modem on the GPy and FiPy. LTE-M/NB-IoT are new categories of cellular protocols developed by the [3GPP](http://www.3gpp.org) and optimised for long battery life power and longer range. These are new protocols currently in the process of being deployed by mobile networks across the world.
+
+The GPy and FiPy support both new LTE-M protocols:
+
+* **Cat-M1**: also known as **LTE-M** defines a 1.4 MHz radio channel size and about 375 kbps of throughput. It is optimised for coverage and long battery life, outperforming 2G/GPRS, while being similar to previous LTE standards.
+* **Cat-NB1** also known as **NB-IoT**, defines a 200 kHz radio channel size and around 60 kbps of uplink speed. It's optimised for ultra low throughput and specifically designed for IoT devices with a very long battery life. NB-IoT shares some features with LTE such as operating in licensed spectrum, but it's a very different protocol. It should be noted that NB-IoT has many restrictions as does not offer full IP connectivity and does not support mobility. When moving between cells, you will need to reconnect.
+
+{% hint style="info" %}
+**Please note:** The GPy and FiPy only support the two protocols above and are not compatible with older LTE standards.
+{% endhint %}
+
+{% hint style="info" %}
+The Sequans modem used on Pycom's cellular enabled modules can only work in one of these modes at a time. In order to switch between the two protocols you need to flash a different firmware to the Sequans modem. Instructions for this can be found [here](../../../tutorials/lte/firmware.md).
+{% endhint %}
+
+## AT Commands
+
+The AT commands for the Sequans Monarch modem on the GPy/FiPy are available in a PDF file.
+
+{% file src="../../../.gitbook/assets/monarch\_4g-ez\_lr5110\_atcommands\_referencemanual\_rev3\_noconfidential.pdf" caption="AT Commands for Sequans" %}
+
+## Constructors
+
+#### class network.LTE\(id=0, ...\)
+
+Create and configure a LTE object. See init for params of configuration.
+
+```python
+from network import LTE
+lte = LTE()
+```
+
+## Methods
+
+#### lte.init\(\*, carrier=None\)
+
+This method is used to set up the LTE subsystem. After a `deinit()` this method can take several seconds to return waiting for the LTE modem to start-up. Optionally specify a carrier name. The available options are: `verizon, at&t, standard`. `standard` is generic for any carrier, and it's also the option used when no arguments are given.
+
+#### lte.deinit\(\)
+
+Disables LTE modem completely. This reduces the power consumption to the minimum. Call this before entering deepsleep.
+
+#### lte.attach\(\*, band=None\)
+
+Enable radio functionality and attach to the LTE Cat M1 network authorised by the inserted SIM card. Optionally specify the band to scan for networks. If no band \(or `None`\) is specified, all 6 bands will be scanned. The possible values for the band are: `3, 4, 12, 13, 20 and 28`.
+
+#### lte.isattached\(\)
+
+Returns `True` if the cellular mode is attached to the network. `False` otherwise.
+
+#### lte.dettach\(\)
+
+Detach the modem from the LTE Cat M1 and disable the radio functionality.
+
+#### lte.connect\(\*, cid=1\)
+
+Start a data session and obtain and IP address. Optionally specify a CID \(Connection ID\) for the data session. The arguments are:
+
+* `cid` is a Connection ID. This is carrier specific, for Verizon use `cid=3`. For others like Telstra it should be `cid=1`.
+
+For instance, to attach and connect to Verizon:
+
+```python
+import time
+from network import LTE
+
+lte = LTE(carrier="verizon")
+lte.attach(band=13)
+
+while not lte.isattached():
+    time.sleep(0.5)
+    print('Attaching...')
+
+lte.connect(cid=3)
+while not lte.isconnected():
+    time.sleep(0.5)
+    print('Connecting...')
+
+# Now use sockets as usual...
+```
+
+#### lte.isconnected\(\)
+
+Returns `True` if there is an active LTE data session and IP address has been obtained. `False` otherwise.
+
+#### lte.disconnect\(\)
+
+End the data session with the network.
+
+#### lte.send\_at\_cmd\(cmd\)
+
+Send an AT command directly to the modem. Returns the raw response from the modem as a string object. **IMPORTANT:** If a data session is active \(i.e. the modem is _connected_\), sending the AT commands requires to pause and then resume the data session. This is all done automatically, but makes the whole request take around 2.5 seconds.
+
+Example:
+
+```python
+lte.send_at_cmd('AT+CEREG?')    # check for network registration manually (sames as lte.isattached())
+```
+
+Optionally the response can be parsed for pretty printing:
+
+```python
+def send_at_cmd_pretty(cmd):
+    response = lte.send_at_cmd(cmd).split('\r\n')
+    for line in response:
+        print(line)
+
+send_at_cmd_pretty('AT!="showphy"')     # get the PHY status
+send_at_cmd_pretty('AT!="fsm"')         # get the System FSM
+```
+
+#### lte.imei\(\)
+
+Returns a string object with the IMEI number of the LTE modem.
+
+#### lte.iccid\(\)
+
+Returns a string object with the ICCID number of the SIM card.
+
+#### lte.reset\(\)
+
+Perform a hardware reset on the cellular modem. This function can take up to 5 seconds to return as it waits for the modem to shutdown and reboot.
+

firmwareapi/pycom/network/server.md

@@ -0,0 +1,50 @@
+# Server
+
+The `Server` class controls the behaviour and the configuration of the FTP and telnet services running on the Pycom device. Any changes performed using this class’ methods will affect both.
+
+Example:
+
+```python
+import network
+server = network.Server()
+server.deinit() # disable the server
+# enable the server again with new settings
+server.init(login=('user', 'password'), timeout=600)
+```
+
+## Quick Usage Example
+
+```python
+from network import Server
+
+# init with new user, password and seconds timeout
+server = Server(login=('user', 'password'), timeout=60)
+server.timeout(300) # change the timeout
+server.timeout() # get the timeout
+server.isrunning() # check whether the server is running or not
+```
+
+## Constructors
+
+#### class network.Server\(id, ...\)
+
+Create a server instance, see `init` for parameters of initialisation.
+
+## Methods
+
+#### server.init\(\* , login=\('micro', 'python'\), timeout=300\)
+
+Init \(and effectively start the server\). Optionally a new `user`, `password` and `timeout` \(in seconds\) can be passed.
+
+#### server.deinit\(\)
+
+Stop the server.
+
+#### server.timeout\(\[timeout\_in\_seconds\]\)
+
+Get or set the server timeout.
+
+#### server.isrunning\(\)
+
+Returns `True` if the server is running \(connected or accepting connections\), `False` otherwise.
+

firmwareapi/pycom/network/sigfox.md

@@ -0,0 +1,279 @@
+# Sigfox
+
+Sigfox is a Low Power Wide Area Network protocol that enables remote devices to connect using ultra-narrow band, UNB technology. The protocol is bi-directional, messages can both be sent up to and down from the Sigfox servers.
+
+{% hint style="info" %}
+When operating in `RCZ2` and `RCZ4` the module can only send messages on the default macro-channel \(this is due to Sigfox network limitations\). Therefore, the device needs to reset automatically to the default macro-channel after every 2 transmissions. However, due to FCC duty cycle limitations, there must a minimum of a 20s delay after resetting to the default macro-channel. Our API takes care of this, \(and in real life applications you should not be in the need to send Sigfox messages that often\), so it will wait for the necessary amount of time to make sure that the duty cycle restrictions are fulfilled.
+
+This means that if you run a piece of test code like:
+
+```python
+for i in range(1, 100):
+  # send something
+  s.send('Hello ' + str(i))
+```
+
+There will be a 20 second delay after every 2 packets.
+{% endhint %}
+
+This class provides a driver for the Sigfox network processor in the Sigfox enabled Pycom devices.
+
+## Quick Usage Example
+
+```python
+from network import Sigfox
+import socket
+
+# init Sigfox for RCZ1 (Europe)
+sigfox = Sigfox(mode=Sigfox.SIGFOX, rcz=Sigfox.RCZ1)
+
+# create a Sigfox socket
+s = socket.socket(socket.AF_SIGFOX, socket.SOCK_RAW)
+
+# make the socket blocking
+s.setblocking(True)
+
+# configure it as uplink only
+s.setsockopt(socket.SOL_SIGFOX, socket.SO_RX, False)
+
+# send some bytes
+s.send(bytes([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]))
+```
+
+{% hint style="danger" %}
+Please ensure that there is an antenna connected to your device before sending/receiving Sigfox messages as in proper use \(e.g. without an antenna\), may damage the device.
+{% endhint %}
+
+## Constructors
+
+#### class network.Sigfox\(id=0, ...\)
+
+Create and configure a Sigfox object. See init for params of configuration. Examples:
+
+```python
+# configure radio for the Sigfox network, using RCZ1 (868 MHz)
+sigfox = Sigfox(mode=Sigfox.SIGFOX, rcz=Sigfox.RCZ1)
+
+# configure radio for FSK, device to device across 912 MHz
+sigfox = Sigfox(mode=Sigfox.FSK, frequency=912000000)
+```
+
+{% hint style="info" %}
+`Sigfox.FSK` mode is not supported on LoPy 4 and FiPy.
+{% endhint %}
+
+## Methods
+
+#### sigfox.init\(mode=Sigfox.SIGFOX, rcz=Sigfox.RCZ1, \* , frequency=None\)
+
+Set the Sigfox radio configuration.
+
+The arguments are:
+
+* `mode` can be either `Sigfox.SIGFOX` or `Sigfox.FSK`. `Sigfox.SIGFOX` uses the Sigfox modulation and protocol while `Sigfox.FSK` allows to create point to point communication between 2 Devices using FSK modulation. _Note:_ `Sigfox.FSK` _mode is not supported on LoPy 4 and FiPy._
+* `rcz` takes the following values: `Sigfox.RCZ1`, `Sigfox.RCZ2`, `Sigfox.RCZ3`, `Sigfox.RCZ4`. The `rcz` argument is only required if the mode is `Sigfox.SIGFOX`.
+* `frequency` sets the frequency value in `FSK` mode. Can take values between 863 and 928 MHz. 
+
+{% hint style="info" %}
+The SiPy comes in 2 different hardware flavours: a +14dBm Tx power version which can only work with `RCZ1` and `RCZ3` and a +22dBm version which works exclusively on `RCZ2` and `RCZ4`.
+{% endhint %}
+
+#### sigfox.mac\(\)
+
+Returns a byte object with the 8-Byte MAC address of the Sigfox radio.
+
+#### sigfox.id\(\)
+
+Returns a byte object with the 4-Byte bytes object with the Sigfox ID.
+
+#### sigfox.rssi\(\)
+
+Returns a signed integer with indicating the signal strength value of the last received packet.
+
+#### sigfox.pac\(\)
+
+Returns a byte object with the 8-Byte bytes object with the Sigfox PAC.
+
+{% hint style="info" %}
+To return human-readable values you should import `ubinascii` and convert binary values to hexidecimal representation. For example:
+
+```python
+print(ubinascii.hexlify(sigfox.mac()))
+```
+{% endhint %}
+
+#### sigfox.frequencies\(\)
+
+Returns a tuple of the form: `(uplink_frequency_hz, downlink_frequency_hz)`
+
+#### sigfox.public\_key\(\[public\]\)
+
+Sets or gets the public key flag. When called passing a `True` value the Sigfox public key will be used to encrypt the packets. Calling it without arguments returns the state of the flag.
+
+```python
+# enable encrypted packets
+sigfox.public_key(True)
+
+# return state of public_key
+sigfox.public_key()
+```
+
+## Constants
+
+* Sigfox radio mode: `sigfox.SIGFOX`, `sigfox.FSK` .
+  * `SIGFOX` to specify usage of the Sigfox Public Network.
+  * `FSK` to specify device to device communication.
+* Sigfox zones: `sigfox.RCZ1`, `sigfox.RCZ2`, `sigfox.RCZ3`, `sigfox.RCZ4`
+  * `RCZ1` to specify Europe, Oman & South Africa.
+  * `RCZ2` for the USA, Mexico & Brazil.
+  * `RCZ3` for Japan.
+  * `RCZ4` for Australia, New Zealand, Singapore, Taiwan, Hong Kong, Colombia & Argentina.
+
+## Working with Sigfox Sockets
+
+Sigfox sockets are created in the following way:
+
+```python
+import socket
+s = socket.socket(socket.AF_SIGFOX, socket.SOCK_RAW)
+```
+
+And they must be created after initialising the Sigfox network card.
+
+Sigfox sockets support the following standard methods from the `socket` module:
+
+#### socket.close\(\)
+
+Use it to close an existing socket.
+
+#### socket.send\(bytes\)
+
+In Sigfox mode the maximum data size is 12 bytes. In FSK the maximum is 64.
+
+```python
+# send a Sigfox payload of bytes
+s.send(bytes([1, 2, 3]))
+
+# send a Sigfox payload containing a string
+s.send('Hello')
+```
+
+#### socket.recv\(bufsize\)
+
+This method can be used to receive a Sigfox downlink or FSK message.
+
+```python
+# size of buffer should be passed for expected payload, e.g. 64 bytes
+s.recv(64)
+```
+
+#### socket.setsockopt\(level, optname, value\)
+
+Set the value of the given socket option. The needed symbolic constants are defined in the socket module \(`SO_*` etc.\). In the case of Sigfox the values are always an integer. Examples:
+
+```python
+# wait for a downlink after sending the uplink packet
+s.setsockopt(socket.SOL_SIGFOX, socket.SO_RX, True)
+
+# make the socket uplink only
+s.setsockopt(socket.SOL_SIGFOX, socket.SO_RX, False)
+
+# use the socket to send a Sigfox Out Of Band message
+s.setsockopt(socket.SOL_SIGFOX, socket.SO_OOB, True)
+
+# disable Out-Of-Band to use the socket normally
+s.setsockopt(socket.SOL_SIGFOX, socket.SO_OOB, False)
+
+# select the bit value when sending bit only packets
+s.setsockopt(socket.SOL_SIGFOX, socket.SO_BIT, False)
+```
+
+Sending a Sigfox packet with a single bit is achieved by sending an empty string, i.e.:
+
+```python
+import socket
+s = socket.socket(socket.AF_SIGFOX, socket.SOCK_RAW)
+
+# send a 1 bit
+s.setsockopt(socket.SOL_SIGFOX, socket.SO_BIT, True)
+s.send('')
+socket.settimeout(value)
+# set timeout for the socket, e.g. 5 seconds
+s.settimeout(5.0)
+socket.setblocking(flag)
+# specifies if socket should be blocking based upon Boolean flag.
+s.setblocking(True)
+```
+
+If the socket is set to blocking, your code will be wait until the socket completes sending/receiving.
+
+## Sigfox Downlink
+
+A Sigfox capable Pycom devices \(SiPy\) can both send and receive data from the Sigfox network. To receive data, a message must first be sent up to Sigfox, requesting a downlink message. This can be done by passing a `True` argument into the `setsockopt()` method.
+
+```python
+s.setsockopt(socket.SOL_SIGFOX, socket.SO_RX, True)
+```
+
+An example of the downlink procedure can be seen below:
+
+```python
+# init Sigfox for RCZ1 (Europe)
+sigfox = Sigfox(mode=Sigfox.SIGFOX, rcz=Sigfox.RCZ1)
+
+# create a Sigfox socket
+s = socket.socket(socket.AF_SIGFOX, socket.SOCK_RAW)
+
+# make the socket blocking
+s.setblocking(True)
+
+# configure it as DOWNLINK specified by 'True'
+s.setsockopt(socket.SOL_SIGFOX, socket.SO_RX, True)
+
+# send some bytes and request DOWNLINK
+s.send(bytes([1, 2, 3]))
+
+# await DOWNLINK message
+s.recv(32)
+```
+
+## Sigfox FSK \(Device to Device\)
+
+To communicate between two Sigfox capable devices, it may be used in FSK mode. Two devices are required to be set to the same frequency, both using FSK.
+
+{% hint style="info" %}
+`Sigfox.FSK` mode is not supported on LoPy 4 and FiPy.
+{% endhint %}
+
+**Device 1**:
+
+```python
+sigfox = Sigfox(mode=Sigfox.FSK, frequency=868000000)
+
+s = socket.socket(socket.AF_SIGFOX, socket.SOCK_RAW)
+s.setblocking(True)
+
+while True:
+  s.send('Device-1')
+  time.sleep(1)
+  print(s.recv(64))
+```
+
+**Device 2**:
+
+```python
+sigfox = Sigfox(mode=Sigfox.FSK, frequency=868000000)
+
+s = socket.socket(socket.AF_SIGFOX, socket.SOCK_RAW)
+s.setblocking(True)
+
+while True:
+  s.send('Device-2')
+  time.sleep(1)
+  print(s.recv(64))
+```
+
+{% hint style="danger" %}
+Remember to use the correct frequency for your region \(868 MHz for Europe, 912 MHz for USA, etc.\)
+{% endhint %}
+

firmwareapi/pycom/network/wlan.md

@@ -0,0 +1,156 @@
+# WLAN
+
+This class provides a driver for the WiFi network processor in the module. Example usage:
+
+```python
+import network
+import time
+# setup as a station
+wlan = network.WLAN(mode=network.WLAN.STA)
+wlan.connect('your-ssid', auth=(network.WLAN.WPA2, 'your-key'))
+while not wlan.isconnected():
+    time.sleep_ms(50)
+print(wlan.ifconfig())
+
+# now use socket as usual
+```
+
+## Quick Usage Example
+
+```python
+import machine
+from network import WLAN
+
+# configure the WLAN subsystem in station mode (the default is AP)
+wlan = WLAN(mode=WLAN.STA)
+# go for fixed IP settings (IP, Subnet, Gateway, DNS)
+wlan.ifconfig(config=('192.168.0.107', '255.255.255.0', '192.168.0.1', '192.168.0.1'))
+wlan.scan()     # scan for available networks
+wlan.connect(ssid='mynetwork', auth=(WLAN.WPA2, 'my_network_key'))
+while not wlan.isconnected():
+    pass
+print(wlan.ifconfig())
+```
+
+## Constructors
+
+#### class network.WLAN\(id=0, ...\)
+
+Create a WLAN object, and optionally configure it. See [`init`](wlan.md#wlan-init-mode-ssid-none-auth-none-channel-1-antenna-none-power_save-false-hidden-false) for params of configuration.
+
+{% hint style="info" %}
+The WLAN constructor is special in the sense that if no arguments besides the `id` are given, it will return the already existing WLAN instance without re-configuring it. This is because WLAN is a system feature of the WiPy. If the already existing instance is not initialised it will do the same as the other constructors an will initialise it with default values.
+{% endhint %}
+
+## Methods
+
+#### wlan.init\(mode, \* , ssid=None, auth=None, channel=1, antenna=None, power\_save=False, hidden=False\)
+
+Set or get the WiFi network processor configuration.
+
+Arguments are:
+
+* `mode` can be either `WLAN.STA`, `WLAN.AP`, or `WLAN.STA_AP`.
+* `ssid` is a string with the SSID name. Only needed when mode is `WLAN.AP`.
+* `auth` is a tuple with \(sec, key\). Security can be `None`, `WLAN.WEP`, `WLAN.WPA`, or `WLAN.WPA2`. The key is a string with the network password.
+  * If `sec` is `WLAN.WEP` the key must be a string representing hexadecimal values \(e.g. `ABC1DE45BF`\). Only needed when mode is `WLAN.AP`.
+* `channel` a number in the range 1-11. Only needed when mode is `WLAN.AP`.
+* `antenna` selects between the internal and the external antenna. Can be either `WLAN.INT_ANT`, `WLAN.EXT_ANT`. With our development boards it defaults to using the internal antenna, but in the case of an OEM module, the antenna pin \(`P12`\) is not used, so it’s free to be
+
+  used for other things.
+
+* `power_save` enables or disables power save functions in `STA` mode.
+* `hidden` only valid in `WLAN.AP` mode to create an access point with a hidden SSID when set to `True`.
+
+For example, you can do:
+
+```python
+# create and configure as an access point
+wlan.init(mode=WLAN.AP, ssid='wipy-wlan', auth=(WLAN.WPA2,'www.wipy.io'), channel=7, antenna=WLAN.INT_ANT)
+```
+
+or
+
+```python
+# configure as an station
+wlan.init(mode=WLAN.STA)
+```
+
+#### wlan.deinit\(\)
+
+Disables the WiFi radio.
+
+#### wlan.connect\(ssid, \* , auth=None, bssid=None, timeout=None, ca\_certs=None, keyfile=None, certfile=None, identity=None\)
+
+Connect to a wifi access point using the given SSID, and other security parameters.
+
+* `auth` is a tuple with `(sec, key)`. Security can be `None`, `WLAN.WEP`, `WLAN.WPA`, `WLAN.WPA2` or `WLAN.WPA2_ENT`. The key is a string with the network password.
+  * If `sec` is `WLAN.WEP` the key must be a string representing hexadecimal values \(e.g. `ABC1DE45BF`\).
+  * If `sec` is `WLAN.WPA2_ENT` then the `auth` tuple can have either 3 elements: `(sec, username, password)`, or just 1: `(sec,)`. When passing the 3 element tuple, the`keyfile` and `certifle` arguments must not be given.
+* `bssid` is the MAC address of the AP to connect to. Useful when there are several APs with the same SSID.
+* `timeout` is the maximum time in milliseconds to wait for the connection to succeed.
+* `ca_certs` is the path to the CA certificate. This argument is not mandatory.
+* `keyfile` is the path to the client key. Only used if `username` and `password` are not part of the `auth` tuple.
+* `certfile` is the path to the client certificate. Only used if `username` and `password` are not part of the `auth` tuple.
+* `identity` is only used in case of `WLAN.WPA2_ENT` security. Needed by the server.
+
+{% hint style="info" %}
+The ESP32 only handles certificates with `pkcs8` format \(but not the "Traditional SSLeay RSAPrivateKey" format\). The private key should be RSA coded with 2048 bits at maximum.
+{% endhint %}
+
+#### wlan.scan\(\)
+
+Performs a network scan and returns a list of named tuples with `(ssid, bssid, sec, channel, rssi)`. Note that channel is always `None` since this info is not provided by the WiPy.
+
+#### wlan.disconnect\(\)
+
+Disconnect from the WiFi access point.
+
+#### wlan.isconnected\(\)
+
+In case of STA mode, returns `True` if connected to a WiFi access point and has a valid IP address. In AP mode returns `True` when a station is connected, `False` otherwise.
+
+#### wlan.ifconfig\(id=0, config=\['dhcp' or configtuple\]\)
+
+When `id` is 0, the configuration will be get/set on the Station interface. When `id` is 1 the configuration will be done for the AP interface.
+
+With no parameters given returns a 4-tuple of `(ip, subnet_mask, gateway, DNS_server)`.
+
+If `dhcp` is passed as a parameter then the DHCP client is enabled and the IP params are negotiated with the AP.
+
+If the 4-tuple config is given then a static IP is configured. For instance:
+
+```python
+wlan.ifconfig(config=('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
+```
+
+#### wlan.mode\(\[mode\]\)
+
+Get or set the WLAN mode.
+
+#### wlan.ssid\(\[ssid\]\)
+
+Get or set the SSID when in AP mode.
+
+#### wlan.auth\(\[auth\]\)
+
+Get or set the authentication type when in AP mode.
+
+#### wlan.channel\(\[channel\]\)
+
+Get or set the channel \(only applicable in AP mode\).
+
+#### wlan.antenna\(\[antenna\]\)
+
+Get or set the antenna type \(external or internal\).
+
+#### wlan.mac\(\)
+
+Get a 6-byte long `bytes` object with the WiFI MAC address.
+
+## Constants
+
+* WLAN mode: `WLAN.STA`, `WLAN.AP`, `WLAN.STA_AP`
+* WLAN network security: `WLAN.WEP`, `WLAN.WPA`, `WLAN.WPA2`, `WLAN.WPA2_ENT`
+* Antenna type: `WLAN.INT_ANT`, `WLAN.EXT_ANT`
+

firmwareapi/pycom/pycom.md

@@ -0,0 +1,153 @@
+# pycom
+
+The `pycom` module contains functions to control specific features of the Pycom devices, such as the heartbeat RGB LED.
+
+## Quick Usage Example
+
+```python
+import pycom
+
+pycom.heartbeat(False)  # disable the heartbeat LED
+pycom.heartbeat(True)   # enable the heartbeat LED
+pycom.heartbeat()       # get the heartbeat state
+pycom.rgbled(0xff00)    # make the LED light up in green color
+```
+
+## Methods
+
+#### pycom.heartbeat\(\[enable\]\)
+
+Get or set the state \(enabled or disabled\) of the heartbeat LED. Accepts and returns boolean values \(`True` or `False`\).
+
+#### pycom.heartbeat\_on\_boot\(\[enable\]\)
+
+Allows you permanently disable or enable the heartbeat LED. Once this setting is set, it will persist between reboots. Note, this only comes into effect on the next boot, it does not stop the already running heartbeat.
+
+#### pycom.rgbled\(color\)
+
+Set the colour of the RGB LED. The colour is specified as 24 bit value representing red, green and blue, where the red colour is represented by the 8 most significant bits. For instance, passing the value `0x00FF00` will light up the LED in a very bright green.
+
+#### pycom.nvs\_set\(key, value\)
+
+Set the value of the specified key in the NVRAM memory area of the external flash. Data stored here is preserved across resets and power cycles. Value can only take 32-bit integers at the moment. Example:
+
+```python
+import pycom
+
+pycom.nvs_set('temp', 25)
+pycom.nvs_set('count', 10)
+```
+
+#### pycom.nvs\_get\(key\)
+
+Get the value the specified key from the NVRAM memory area of the external flash. Example:
+
+```python
+import pycom
+
+pulses = pycom.nvs_get('count')
+```
+
+If a non-existing key is given the returned value will be `None`.
+
+#### pycom.nvs\_erase\(key\)
+
+Erase the given key from the NVRAM memory area.
+
+#### pycom.nvs\_erase\_all\(\)
+
+Erase the entire NVRAM memory area.
+
+#### pycom.wifi\_on\_boot\(\[enable\]\)
+
+Get or set the WiFi on boot flag. When this flag is set to `True`, the AP with the default SSID \(`lopy-wlan-xxx` for example\) will be enabled as part of the boot process. If the flag is set to False, the module will boot with WiFi disabled until it's enabled by the script via the `WLAN` class. This setting is stored in non-volatile memory which preserves it across resets and power cycles. Example:
+
+```python
+import pycom
+
+pycom.wifi_on_boot(True)   # enable WiFi on boot
+pycom.wifi_on_boot()       # get the wifi on boot flag
+```
+
+#### pycom.wdt\_on\_boot\(\[enable\]\)
+
+Enables the WDT at boot time with the timeout in ms set by the function `wdt_on_boot_timeout`. If this flag is set, the application needs to reconfigure the WDT with a new timeout and feed it regularly to avoid a reset.
+
+```python
+import pycom
+
+pycom.wdt_on_boot(True)     # enable WDT on boot
+pycom.wdt_on_boot()         # get the WDT on boot flag
+```
+
+#### pycom.wdt\_on\_boot\_timeout\(\[timeout\]\)
+
+Sets or gets the WDT on boot timeout in milliseconds. The minimum value is 5000 ms.
+
+```python
+import pycom
+
+pycom.wdt_on_boot_timeout(10000)     # set the timeout to 5000ms
+pycom.wdt_on_boot_timeout()          # get the WDT timeout value
+```
+
+#### pycom.pulses\_get\(pin, timeout\)
+
+Return a list of pulses at `pin`. The methods scans for transitions at `pin` and returns a list of tuples, each telling the pin value and the duration in microseconds of that value. `pin` is a pin object, which must have set to `INP` or `OPEN_DRAIN` mode. The scan stops if not transitions occurs within `timeout` milliseconds.
+
+Example:
+
+```python
+# get the raw data from a DHT11/DHT22/AM2302 sensor
+from machine import Pin
+from pycom import pulses_get
+from time import sleep_ms
+
+pin = Pin("G7", mode=Pin.OPEN_DRAIN)
+pin(0)
+sleep_ms(20)
+pin(1)
+data = pulses_get(pin, 100)
+```
+
+#### pycom.ota\_start\(\)
+
+#### pycom.ota\_write\(buffer\)
+
+#### pycom.ota\_finish\(\)
+
+Perform a firmware update. These methods are internally used by a firmware update though FTP. The update starts with a call to `ota_start()`, followed by a series of calls to `ota_write(buffer)`, and is terminated with `ota_finish()`. After reset, the new image gets active. `buffer` shall hold the image data to be written, in arbitrary sizes. A block size of 4096 is recommended.
+
+Example:
+
+```python
+# Firmware update by reading the image from the SD card
+#
+from pycom import ota_start, ota_write, ota_finish
+from os import mount
+from machine import SD
+
+BLOCKSIZE = const(4096)
+APPIMG = "/sd/appimg.bin"
+
+sd = SD()
+mount(sd, '/sd')
+
+with open(APPIMG, "rb") as f:
+    buffer = bytearray(BLOCKSIZE)
+    mv = memoryview(buffer)
+    size=0
+    ota_start()
+    while True:
+        chunk = f.readinto(buffer)
+        if chunk > 0:
+            ota_write(mv[:chunk])
+            size += chunk
+            print("\r%7d " % size, end="")
+        else:
+            break
+    ota_finish()
+```
+
+Instead of reading the data to be written from a file, it can obviously also be received from a server using any suitable protocol, without the need to store it in the devices file system.
+