sascha_hemi/pycom-documentation
1
0
Fork 0
mirror of https://github.com/sascha-hemi/pycom-documentation.git synced 2026-03-21 03:04:13 +01:00
Code Issues Packages Projects Releases Wiki Activity

manual rework

Browse Source
This commit is contained in:
Emmanuel Florent
2019-06-26 10:36:06 +02:00
parent 300ef51502
commit 25b2c660b0
171 changed files with 0 additions and 12644 deletions
Download Patch File Download Diff File Expand all files Collapse all files

215
SUMMARY.md
View File

@@ -1,215 +0,0 @@
# Table of contents
* [Introduction](README.md)
* [Pycom Products](products.md)
## Getting Started
* [Introduction](getting-started/introduction.md)
* [Hardware Setup](getting-started/connection/README.md)
* [LoPy](getting-started/connection/lopy.md)
* [LoPy 4](getting-started/connection/lopy4.md)
* [SiPy](getting-started/connection/sipy.md)
* [GPy](getting-started/connection/gpy.md)
* [FiPy](getting-started/connection/fipy.md)
* [WiPy](getting-started/connection/wipy.md)
* [Software](getting-started/installation/README.md)
* [Drivers](getting-started/installation/drivers.md)
* [Updating Firmware](getting-started/installation/firmwaretool.md)
* [Pymakr](getting-started/installation/pymakr.md)
* [Programming the modules](getting-started/programming/README.md)
* [Introduction to MicroPython](getting-started/programming/micropython.md)
* [MicroPython Examples](getting-started/programming/examples.md)
* [Your first Pymakr project](getting-started/programming/first-project.md)
* [REPL](getting-started/programming/repl/README.md)
* [Serial USB \(UART\)](getting-started/programming/repl/serial.md)
* [Telnet REPL](getting-started/programming/repl/telnet.md)
* [FTP](getting-started/programming/ftp.md)
* [Safe boot](getting-started/programming/safeboot.md)
* [Device Registration](getting-started/registration/README.md)
* [Sigfox](getting-started/registration/sigfox.md)
* [Cellular](getting-started/registration/cellular.md)
* [LoRaWAN](getting-started/registration/lora/README.md)
* [The Things Network](getting-started/registration/lora/ttn.md)
* [Senet](getting-started/registration/lora/senet.md)
* [Troubleshooting Guide](getting-started/troubleshooting-guide.md)
## Pymakr Plugin
* [Installation](pymakr-plugin/installation/README.md)
* [Atom](pymakr-plugin/installation/atom.md)
* [Visual Studio Code](pymakr-plugin/installation/vscode.md)
* [Tools/Features](pymakr-plugin/toolsfeatures.md)
* [Settings](pymakr-plugin/settings.md)
## Pytrack, Pysense, Pyscan
* [Introduction](pytrack-pysense-pyscan/introduction.md)
* [Installing Software](pytrack-pysense-pyscan/installation/README.md)
* [Updating Firmware](pytrack-pysense-pyscan/installation/firmware.md)
* [Installing Drivers - Windows 7](pytrack-pysense-pyscan/installation/drivers.md)
* [Installing Libraries](pytrack-pysense-pyscan/installation/libraries.md)
* [API Reference](pytrack-pysense-pyscan/apireference/README.md)
* [Pytrack](pytrack-pysense-pyscan/apireference/pytrack.md)
* [Pysense](pytrack-pysense-pyscan/apireference/pysense.md)
* [Pyscan](pytrack-pysense-pyscan/apireference/pyscan.md)
* [Sleep](pytrack-pysense-pyscan/apireference/sleep.md)
## Tutorials & Examples
* [Introduction](tutorials-and-examples/introduction.md)
* [All Pycom Device Examples](tutorials-and-examples/all/README.md)
* [REPL](tutorials-and-examples/all/repl.md)
* [WLAN](tutorials-and-examples/all/wlan.md)
* [Bluetooth](tutorials-and-examples/all/ble.md)
* [HTTPS](tutorials-and-examples/all/https.md)
* [MQTT](tutorials-and-examples/all/mqtt.md)
* [AWS](tutorials-and-examples/all/aws.md)
* [ADC](tutorials-and-examples/all/adc.md)
* [I2C](tutorials-and-examples/all/i2c.md)
* [Onewire Driver](tutorials-and-examples/all/owd.md)
* [Threading](tutorials-and-examples/all/threading.md)
* [RGB LED](tutorials-and-examples/all/rgbled.md)
* [Timers](tutorials-and-examples/all/timers.md)
* [PIR Sensor](tutorials-and-examples/all/pir.md)
* [Modbus](tutorials-and-examples/all/modbus.md)
* [OTA update](tutorials-and-examples/all/ota.md)
* [RMT](tutorials-and-examples/all/rmt.md)
* [LoRa Examples](tutorials-and-examples/lora/README.md)
* [LoRa-MAC \(Raw LoRa\)](tutorials-and-examples/lora/lora-mac.md)
* [LoRaWAN with OTAA](tutorials-and-examples/lora/lorawan-otaa.md)
* [LoRaWAN with ABP](tutorials-and-examples/lora/lorawan-abp.md)
* [LoRa-MAC Nano-Gateway](tutorials-and-examples/lora/lora-mac-nano-gateway.md)
* [LoPy to LoPy](tutorials-and-examples/lora/module-module.md)
* [LoRaWAN Nano-Gateway](tutorials-and-examples/lora/lorawan-nano-gateway.md)
* [RN2483 to LoPy](tutorials-and-examples/lora/rn2483-to-lopy.md)
* [Sigfox Examples](tutorials-and-examples/sigfox.md)
* [LTE Examples](tutorials-and-examples/lte/README.md)
* [CAT-M1](tutorials-and-examples/lte/cat-m1.md)
* [NB-IoT](tutorials-and-examples/lte/nb-iot.md)
* [Module IMEI](tutorials-and-examples/lte/imei.md)
* [Modem Firmware Update](tutorials-and-examples/lte/firmware.md)
* [Pytrack Examples](tutorials-and-examples/pytrack.md)
* [Pysense Examples](tutorials-and-examples/pysense.md)
* [Pyscan Examples](tutorials-and-examples/pyscan.md)
## Firmware & API Reference
* [Introduction](firmware-and-api-reference/introduction.md)
* [Pycom Modules](firmware-and-api-reference/pycom/README.md)
* [machine](firmware-and-api-reference/pycom/machine/README.md)
* [ADC](firmware-and-api-reference/pycom/machine/adc.md)
* [DAC](firmware-and-api-reference/pycom/machine/dac.md)
* [I2C](firmware-and-api-reference/pycom/machine/i2c.md)
* [Pin](firmware-and-api-reference/pycom/machine/pin.md)
* [PWM](firmware-and-api-reference/pycom/machine/pwm.md)
* [RTC](firmware-and-api-reference/pycom/machine/rtc.md)
* [SPI](firmware-and-api-reference/pycom/machine/spi.md)
* [UART](firmware-and-api-reference/pycom/machine/uart.md)
* [WDT](firmware-and-api-reference/pycom/machine/wdt.md)
* [Timer](firmware-and-api-reference/pycom/machine/timer.md)
* [SD](firmware-and-api-reference/pycom/machine/sd.md)
* [CAN](firmware-and-api-reference/pycom/machine/can.md)
* [RMT](firmware-and-api-reference/pycom/machine/rmt.md)
* [network](firmware-and-api-reference/pycom/network/README.md)
* [WLAN](firmware-and-api-reference/pycom/network/wlan.md)
* [Server](firmware-and-api-reference/pycom/network/server.md)
* [Bluetooth](firmware-and-api-reference/pycom/network/bluetooth/README.md)
* [GATT](firmware-and-api-reference/pycom/network/bluetooth/gatt.md)
* [GATTCConnection](firmware-and-api-reference/pycom/network/bluetooth/gattcconnection.md)
* [GATTCService](firmware-and-api-reference/pycom/network/bluetooth/gattccservice.md)
* [GATTCCharacteristic](firmware-and-api-reference/pycom/network/bluetooth/gattccharacteristic.md)
* [GATTSService](firmware-and-api-reference/pycom/network/bluetooth/gattsservice.md)
* [GATTSCharacteristic](firmware-and-api-reference/pycom/network/bluetooth/gattscharacteristic.md)
* [LoRa](firmware-and-api-reference/pycom/network/lora.md)
* [Sigfox](firmware-and-api-reference/pycom/network/sigfox.md)
* [LTE](firmware-and-api-reference/pycom/network/lte.md)
* [AES](firmware-and-api-reference/pycom/aes.md)
* [pycom](firmware-and-api-reference/pycom/pycom.md)
* [MicroPython Modules](firmware-and-api-reference/micropython/README.md)
* [micropython](firmware-and-api-reference/micropython/micropython.md)
* [uctypes](firmware-and-api-reference/micropython/uctypes.md)
* [sys](firmware-and-api-reference/micropython/sys.md)
* [uos](firmware-and-api-reference/micropython/uos.md)
* [array](firmware-and-api-reference/micropython/array.md)
* [cmath](firmware-and-api-reference/micropython/cmath.md)
* [math](firmware-and-api-reference/micropython/math.md)
* [gc](firmware-and-api-reference/micropython/gc.md)
* [ubinascii](firmware-and-api-reference/micropython/ubinascii.md)
* [ujson](firmware-and-api-reference/micropython/ujson.md)
* [ure](firmware-and-api-reference/micropython/ure.md)
* [usocket](firmware-and-api-reference/micropython/usocket.md)
* [select](firmware-and-api-reference/micropython/select.md)
* [utime](firmware-and-api-reference/micropython/utime.md)
* [uhashlib](firmware-and-api-reference/micropython/uhashlib.md)
* [ussl](firmware-and-api-reference/micropython/ussl.md)
* [ucrypto](firmware-and-api-reference/micropython/ucrypto.md)
* [ustruct](firmware-and-api-reference/micropython/ustruct.md)
* [\_thread](firmware-and-api-reference/micropython/_thread.md)
* [Builtin](firmware-and-api-reference/micropython/builtin.md)
* [Notes](firmware-and-api-reference/notes.md)
## Product Info, Datasheets
* [Introduction](product-info-datasheets/introduction.md)
* [Development Modules](product-info-datasheets/development/README.md)
* [WiPy 2.0](product-info-datasheets/development/wipy2.md)
* [WiPy 3.0](product-info-datasheets/development/wipy3.md)
* [LoPy](product-info-datasheets/development/lopy.md)
* [LoPy 4](product-info-datasheets/development/lopy4.md)
* [SiPy](product-info-datasheets/development/sipy.md)
* [GPy](product-info-datasheets/development/gpy.md)
* [FiPy](product-info-datasheets/development/fipy.md)
* [OEM Modules](product-info-datasheets/oem/README.md)
* [W01](product-info-datasheets/oem/w01.md)
* [L01](product-info-datasheets/oem/l01.md)
* [L04](product-info-datasheets/oem/l04.md)
* [G01](product-info-datasheets/oem/g01.md)
* [L01 OEM Baseboard Reference](product-info-datasheets/oem/l01_reference.md)
* [Universal OEM Baseboard Reference](product-info-datasheets/oem/universal_reference.md)
* [Expansion Boards and Shields](product-info-datasheets/boards/README.md)
* [Expansion Board 3.0](product-info-datasheets/boards/expansion3.md)
* [Pytrack](product-info-datasheets/boards/pytrack.md)
* [Pysense](product-info-datasheets/boards/pysense.md)
* [Pyscan](product-info-datasheets/boards/pyscan.md)
* [Expansion Board 2.0](product-info-datasheets/boards/expansion2.md)
* [Deep Sleep Shield](product-info-datasheets/boards/deepsleep/README.md)
* [Deep Sleep API](product-info-datasheets/boards/deepsleep/api.md)
* [Notes](product-info-datasheets/notes.md)
## Pybytes
* [Introduction](pybytes/introduction.md)
* [Getting Started with Pybytes](pybytes/getstarted.md)
* [Add a device to Pybytes](pybytes/connect/README.md)
* [Connect to Pybytes: Quick Add](pybytes/connect/quick.md)
* [Connect to Pybytes: Flash Pybytes library manually](pybytes/connect/flash.md)
* [Add Sigfox device](pybytes/connect/sigfox/README.md)
* [DevKit contract](pybytes/connect/sigfox/devkit.md)
* [Custom contract](pybytes/connect/sigfox/custom.md)
* [Visualise data from your device](pybytes/dashboard.md)
* [Integrations](pybytes/integrations/README.md)
* [Amazon IoT](pybytes/integrations/amazon-iot.md)
## Documentation Notes
* [Introduction](documentation-notes/introduction.md)
* [Syntax](documentation-notes/syntax.md)
* [REPL vs Scripts](documentation-notes/replscript.md)
* [Mesh Networks](documentation-notes/mesh-networks.md)
## Advanced Topics
* [Firmware Downgrade](advanced-topics/downgrade.md)
* [CLI Updater](advanced-topics/cli.md)
* [SecureBoot and Encryption](advanced-topics/encryption.md)
## Documents
* [Certificates](documents/certificates.md)
* [License](documents/license.md)
## Have a question?
* [Ask on the Forum](https://forum.pycom.io)

361
advanced-topics/cli.md
View File

@@ -1,361 +0,0 @@
# CLI Updater
## Command Line Update Utility
#### Windows
After installing the [Windows version](https://software.pycom.io/findupgrade?product=pycom-firmware-updater&type=all&platform=win32&redirect=true) of the updater tool, the CLI tool `pycom-fwtool-cli.exe` can be found here:
* 32-Bit Windows: `C:\Program Files\Pycom\Pycom Firmware Update\`
* 64-Bit Windows: `C:\Program Files (x86)\Pycom\Pycom Firmware Update\`
#### macOS
In order to get access to the CLI tool on macOS, you will need to right click on the [Mac version](https://software.pycom.io/findupgrade?product=pycom-firmware-updater&type=all&platform=macos&redirect=true) of the updater tool and click `Show Package Contents`, then navigate to `Contents/Resources`, here you will find the `pycom-fwtool-cli`.
#### Linux
In the [Ubuntu 14.04 LTS](https://software.pycom.io/findupgrade?product=pycom-firmware-updater&type=all&platform=unix&redirect=true) \(and newer\) version of the updater tool, `pycom-fwtool-cli` is installed in `/usr/local/bin`. In the [Generic Linux](https://software.pycom.io/findupgrade?product=pycom-firmware-updater&type=all&platform=unix&redirect=true) package, the tool is extracted into folder `./pyupgrade`
### Usage
```text
usage: pycom-fwtool-cli [-h] [-v] [-d] [-q] [-p PORT] [-s SPEED] [-c] [-x]
[--ftdi] [--pic] [-r]
{list,chip_id,wmac,smac,sigfox,exit,flash,copy,write,write_remote,wifi,pybytes,cb,nvs,ota,lpwan,erase_fs,erase_all}
...
Update your Pycom device with the specified firmware image file For more
details please see https://docs.pycom.io/chapter/advance/cli.html
positional arguments:
{list,chip_id,wmac,smac,sigfox,exit,flash,copy,write,write_remote,wifi,pybytes,cb,nvs,ota,lpwan,erase_fs,erase_all}
list Get list of available COM ports
chip_id Show ESP32 chip_id
wmac Show WiFi MAC
smac Show LPWAN MAC
sigfox Show sigfox details
exit Exit firmware update mode
flash Write firmware image to flash
copy Read/Write flash memory partition
write Write to flash memory
wifi Get/Set default WIFI parameters
pybytes Read/Write pybytes configuration
cb Read/Write config block
nvs Read/Write non volatile storage
ota Read/Write ota block
lpwan Get/Set LPWAN parameters [ EU868 US915 AS923 AU915]
erase_fs Erase flash file system area
erase_all Erase entire flash!
optional arguments:
-h, --help show this help message and exit
-v, --verbose show verbose output from esptool
-d, --debug show debuggin output from fwtool
-q, --quiet suppress success messages
-p PORT, --port PORT the serial port to use
-s SPEED, --speed SPEED
baudrate
-c, --continuation continue previous connection
-x, --noexit do not exit firmware update mode
--ftdi force running in ftdi mode
--pic force running in pic mode
-r, --reset use Espressif reset mode
```
## How to use the Parameters
{% hint style="info" %}
The CLI tool uses a combination of global and command specific parameters. The **order of parameters** is **important** to avoid ambiguity.
`pycom-fwtool-cli [global parameters] [command] [command parameters]`
While `pycom-fwtool-cli -h` shows help for global parameters and a list of available commands, command specific parameters can be viewed using `pycom-fwtool-cli [command] -h`
The parameter `-r, --reset` has been added as a courtesy for users of 3rd party ESP32 products. This functionality is **not supported** by the Expansion Board 2.0 and may cause this tool to crash or hang in certain circumstances.
{% endhint %}
### Global Parameters
```text
`-h / --help` : shows above help (you can also get detailed help for each sub-command
`-v / --verbose` : show verbose output from esptool.
`-d / --debug` : show debug output from fwtool.
`-q / --quiet` : suppress most output, used for scripting
`-p / --port` : specifies the serial port to be used. Can also be set via **environment variable ESPPORT**
`-s / --speed` : specifies the serial speed to be used. Can also be set via **environment variable ESPBAUD**
`-c / --continuation` : continue previous connection in FTDI mode. This allows running multiple commands sequentially without having to reset the module. This option is ignored in PIC mode as the module can be reset via the serial connection.
`-x / --noexit` : This will prevent the PIC from leaving firmware update mode.
`--ftdi` : This will force the CLI updater to run in FTDI mode.
`--pic` : This will force the CLI updater to run in PIC mode.
`-r, --reset` : This will force the CLI updater to use Espressif's workaround to switch into Firmware update mode. This reset method is intended for 3rd party hardware only and is not supported by the Expansion Board 2.0
```
### Commands
#### list
Get list of available serial ports ports.
```bash
usage: pycom-fwtool-cli list [-h]
optional arguments:
-h, --help show this help message and exit
```
**Example:** On macOS:
```bash
$ pycom-fwtool-cli list
/dev/cu.usbmodemPy343431 [Pytrack] [USB VID:PID=04D8:F013 SER=Py343434 LOCATION=20-2]
/dev/cu.Bluetooth-Incoming-Port [n/a] [n/a]
```
On Windows:
```text
COM6 [Pytrack] [USB VID:PID=04D8:F013 SER=Py343434 LOCATION=20-2]
```
{% hint style="info" %}
This is the only command that does not require any additional parameters.
All other commands require that **the serial port is specified either through the** `-p` **/** `--port` **option or through environment variable** `ESPPORT` You can optionally specify the speed either through `-s` / `--speed` or via environment variable `ESPBAUD`. The default speed is `921600`. The maximum speed for read operations on PIC based expansion boards & shields is `230400`. The speed will be reduced automatically if necessary.
#### Special note for Expansion Board 2.0
You will need to have a **jumper wire** connected between `G23` and `GND` to use any of the commands below. You will also need to **press the reset button** either before running each command or at least before running the first command. To avoid having to press the reset button again after each command, you can use the `-c` / `--continuation` option. The first command connecting to the device **MUST NOT** use the `-c` / `--continuation` option. This is to make sure a program called `_stub_` is uploaded onto the device. This `_stub_` cannot be uploaded more than once, so you need to tell the cli tool that the `_stub_` is already running, which is done through using the `-c` / `--continuation` option.
{% endhint %}
#### chip\_id
Shows the unique ID of the ESP32 on the connected module.
```text
usage: pycom-fwtool-cli -p PORT exit [-h]
optional arguments:
-h, --help show this help message and exit
```
#### wmac
Shows the WiFi MAC of the connected module.
```text
usage: pycom-fwtool-cli -p PORT wmac [-h]
optional arguments:
-h, --help show this help message and exit
```
#### smac
Shows the LPWAN MAC of the connected module.
```text
usage: pycom-fwtool-cli -p PORT smac [-h]
optional arguments:
-h, --help show this help message and exit
```
#### sigfox
Show sigfox details
```text
usage: pycom-fwtool-cli -p PORT sigfox [-h]
optional arguments:
-h, --help show this help message and exit
```
#### exit
If a Pysense/Pytrack/Expansion 3 has previously been left in firmware update mode by using the `-x` option, this command can be used to exit the firmware update mode.
```text
usage: pycom-fwtool-cli -p PORT exit [-h]
optional arguments:
-h, --help show this help message and exit
```
#### flash
Writes firmware image to flash, must be as a `.tar(.gz)` file as provided by Pycom. These files can be found on [GitHub](https://github.com/pycom/pycom-micropython-sigfox/releases).
```text
usage: pycom-fwtool-cli -p PORT flash [-h] [-t TAR]
optional arguments:
-h, --help show this help message and exit
-t TAR, --tar TAR perform the upgrade from a tar[.gz] file
```
#### copy
Read/Write flash memory partition from/to local file
```text
usage: pycom-fwtool-cli -p PORT [-h] [-p PARTITION] [-f FILE] [-r] [-b]
optional arguments:
-h, --help show this help message and exit
-p PARTITION, --partition PARTITION
The partition to read/write (all, fs, nvs, factory,
secureboot, bootloader, partitions, otadata, fs1,
ota_0, config)
-f FILE, --file FILE name of the binary file (default: <wmac>-<part>.bin)
-r, --restore restore partition from binary file
-b, --backup backup partition to binary file (default)
```
#### write
Write to a specific location in flash memory.
```text
usage: pycom-fwtool-cli -p PORT write [-h] [-a ADDRESS] [--contents CONTENTS]
optional arguments:
-h, --help show this help message and exit
-a ADDRESS, --address ADDRESS
address to write to
--contents CONTENTS contents of the memory to write (base64)
```
#### wifi
Get/Set default WiFi parameters.
```text
usage: pycom-fwtool-cli wifi [-h] [--ssid SSID] [--pwd PWD] [--wob [WOB]]
optional arguments:
-h, --help show this help message and exit
--ssid SSID Set Wifi SSID
--pwd PWD Set Wifi PWD
--wob [WOB] Set Wifi on boot
```
#### pybytes
Read/Write pybytes configuration.
```text
usage: pycom-fwtool-cli pybytes [-h] [--token TOKEN] [--mqtt MQTT] [--uid UID]
[--nwprefs NWPREFS] [--extraprefs EXTRAPREFS]
optional arguments:
-h, --help show this help message and exit
--token TOKEN Set Device Token
--mqtt MQTT Set mqttServiceAddress
--uid UID Set userId
--nwprefs NWPREFS Set network preferences
--extraprefs EXTRAPREFS
Set extra preferences
```
{% hint style="info" %}
Note: The local `pybytes_config.json` file is overwritten when making any modifications using this command \(requires Pybytes firmware `1.17.5.b6` or higher and Firmware updater `1.14.3`\).
{% endhint %}
#### cb
Read/Write config block \(LPMAC, Sigfox PAC & ID, etc.\). You can find the structure of this block [here.](https://github.com/pycom/pycom-micropython-sigfox/blob/master/esp32/pycom_config.h#L24)
```text
usage: pycom-fwtool-cli -p PORT cb [-h] [-f FILE] [-b] [-r]
optional arguments:
-h, --help show this help message and exit
-f FILE, --file FILE name of the backup file
-b, --backup backup cb partition to file
-r, --restore restore cb partition from file
```
If neither `-b` or `-r` is provided, the command will default to backup. If no file name is provided, `<WMAC>.cb` is used.
To backup your config block: `$pycom-fwtool-cli -p PORT cb`
To restore your config block: `$pycom-fwtool-cli -p PORT cb -r -f backup.cb`
#### nvs
Read/Write non-volatile storage.
```text
usage: pycom-fwtool-cli -p PORT nvs [-h] [-f FILE] [-b] [-r]
optional arguments:
-h, --help show this help message and exit
-f FILE, --file FILE name of the backup file
-b, --backup backup cb partition to file
-r, --restore restore cb partition from file
```
If neither `-b` or `-r` is provided, the command will default to backup. If no file name is provided, `<WMAC>.nvs` is used.
To backup your NVS: `$ pycom-fwtool-cli -p PORT nvs`
To restore your NVS: `$ pycom-fwtool-cli -p PORT nvs -r -f backup.nvs`
#### ota
Read/Write ota block, this contains data relating to OTA updates such as the hash of the OTA firmware.
```text
usage: pycom-fwtool-cli ota [-h] [-f FILE] [-b] [-r]
optional arguments:
-h, --help show this help message and exit
-f FILE, --file FILE name of the backup file
-b, --backup backup cb partition to file
-r, --restore restore cb partition from file
```
If neither `-b` nor `-r` is provided, the command will default to backup. If no file name is provided, `<WMAC>.ota` is used.
To backup your OTA block: `$pycom-fwtool-cli -p PORT ota`
To restore your OTA block: `$pycom-fwtool-cli -p PORT ota -r -f backup.ota`
#### lpwan
Get/Set LPWAN parameters saved to non-volatile storage. Please see [here](../firmware-and-api-reference/pycom/network/lora.md##loranvramsave) for more details.
```text
usage: pycom-fwtool-cli -p PORT lpwan [-h] [--region REGION]
optional arguments:
-h, --help show this help message and exit
--region REGION Set default LORA region
--erase_region Erase default LORA region
--lora_region Output only LORA region
```
#### erase\_fs
Erase flash file system area. This is useful if some code running on the device is preventing access to the REPL.
```text
usage: pycom-fwtool-cli -p PORT erase_fs [-h]
optional arguments:
-h, --help show this help message and exit
```
#### erase\_all
Erase entire flash, only use this if you are sure you know what you are doing. This will remove your devices lpwan mac addresses etc.
```text
usage: pycom-fwtool-cli erase_all [-h]
optional arguments:
-h, --help show this help message and exit
```

39
advanced-topics/downgrade.md
View File

@@ -1,39 +0,0 @@
# Firmware Downgrade
The firmware upgrade tool usually updates your device to the latest available firmware version. If you require to downgrade your device to a previous firmware there are two methods to achieve this.
{% hint style="info" %}
If you are using an Expansion Board 1.0 or 2.0, you will need to have a jumper connected between `G23` and `GND` to use either procedure below. You will also need to press the reset button before beginning.
{% endhint %}
You can obtain previous firmware versions here:
* [WiPy](https://software.pycom.io/downloads/WiPy.html)
* [LoPy](https://software.pycom.io/downloads/LoPy.html)
* [SiPy](https://software.pycom.io/downloads/SiPy.html)
* [GPy](https://software.pycom.io/downloads/GPy.html)
* [FiPy](https://software.pycom.io/downloads/FiPy.html)
* [LoPy4](https://software.pycom.io/downloads/LoPy4.html)
{% hint style="info" %}
Prior to version `1.16.0.b1` the firmware for modules with LoRa functionality was frequency specific. From `1.16.0.b1` and onward, the firmware is region agnostic and this can either be set programatically or via the config block \(see [here](cli.md#lpwan)\).
{% endhint %}
## GUI
As of version `1.12.0.b0` of the firmware update tool, you can now provide a `.tar` or `.tar.gz` archive of the firmware you wish to upload to the board.
When you start the update tool you will see the following screen:
![](../.gitbook/assets/downgrade_gui%20%281%29.png)
When you tick the `Flash from local file` option, an address bar will appear. Click the `...` button and locate the `.tar(.gz)` file with the firmware you wish to flash to your device. From this point the updater will behave just like a regular update but using the local file instead of downloading the latest.
## Command line
You can also use the [CLI](cli.md) version of the update tool to downgrade your device. Will need to get a `.tar` or `.tar.gz` archive of the firmware you wish to upload to the board. Then run the following commands:
```bash
$ pycom-fwtool-cli -v -p PORT flash -t /path/to/firmware/archive.tar.gz
```

103
advanced-topics/encryption.md
View File

@@ -1,103 +0,0 @@
# SecureBoot and Encryption
## Summary
In order to encrypt your firmware, you will need to build it from source. Our firmware source code can be found [here](https://github.com/pycom/pycom-micropython-sigfox/), along with instructions on how to build it. Below you will find specific instructions on how generate keys, build and flash encrypted firmware.
1. Obtain keys \(for Secure Boot and Flash Encryption\)
2. Flash keys and parameters in `efuses`
3. Compile bootloader and application with `make SECURE=on`
4. Flash: bootloader-digest at address `0x0` and encrypted; all the others \(partitions and application\) encrypted, too.
## Prerequisites
Firstly you will need to setup the tool chain and download the source code. detailed instructions on how to achieve this can be found [here](https://github.com/pycom/pycom-micropython-sigfox/blob/master/README.md#the-esp32-version_). Once you have complete this, you will need to open a terminal in the `esp32` folder of the firmware source code repo.
Next you will need keys for Flash Encryption and Secure Boot; they can be generated randomly with the following commands:
```bash
python $IDF_PATH/components/esptool_py/esptool/espsecure.py generate_flash_encryption_key flash_encryption_key.bin
python $IDF_PATH/components/esptool_py/esptool/espsecure.py generate_signing_key secure_boot_signing_key.pem
```
The Secure Boot key `secure_boot_signing_key.pem` has to be transformed into `secure-bootloader-key.bin`, to be burnt into efuses. This can be done in 2 ways:
```bash
python $IDF_PATH/components/esptool_py/esptool/espsecure.py extract_public_key --keyfile secure_boot_signing_key.pem signature_verification_key.bin
```
or, as an artifact of the make build process, on the same directory level as Makefile
```bash
make BOARD=GPY SECURE=on TARGET=boot
```
To flash the keys \(`flash_encryption_key.bin` and `secure-bootloader-key.bin`\) into the efuses \(write and read protected\) run the following commands \(ignoring the lines that start with `#`\):
_**Note: Irreversible operations**_
```bash
# Burning Encryption Key
python $IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 burn_key flash_encryption flash_encryption_key.bin
# Burning Secure Boot Key
python $IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 burn_key secure_boot secure-bootloader-key.bin
# Enabling Flash Encryption mechanism
python $IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 burn_efuse FLASH_CRYPT_CNT
# Configuring Flash Encryption to use all address bits together with Encryption key (max value 0x0F)
python $IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 burn_efuse FLASH_CRYPT_CONFIG 0x0F
# Enabling Secure Boot mechanism
python $IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 burn_efuse ABS_DONE_0
```
**If the keys are not written in efuse, before flashing the bootloader, then random keys will be generated by the ESP32, they can never be read nor re-written, so bootloader can never be updated. Even more, the application can be re-flashed \(by USB\) just 3 more times.**
## Makefile options
```bash
make BOARD=GPY SECURE=on SECURE_KEY=secure_boot_signing_key.pem ENCRYPT_KEY=flash_encryption_key.bin TARGET=[boot|app]
```
* `SECURE=on` is the main flag; it's not optional
* if `SECURE=on` the following defaults are set:
* encryption is enable
* `secure_boot_signing_key.pem` is the secure boot key, located relatively to Makefile
* `flash_encryption_key.bin` is the flash encryption key, located relatively to Makefile
For flashing the bootloader digest and the encrypted versions of all binaries:
```bash
make BOARD=GPY SECURE=on flash
```
## Flashing
For flashing the `bootloader-reflash-digest.bin` has to be written at address 0x0, instead of the `bootloader.bin` \(at address `0x1000`\).
Build is done using `SECURE=on` option; additionally, all the binaries are pre-encrypted.
```bash
make BOARD=GPY clean
make BOARD=GPY SECURE=on TARGET=boot
make BOARD=GPY SECURE=on TARGET=app
make BOARD=GPY SECURE=on flash
```
Manual flash command:
```bash
python $IDF_PATH/components/esptool_py/esptool/esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 --before no_reset --after no_reset write_flash -z --flash_mode dio --flash_freq 80m --flash_size detect 0x0 build/GPY/release/bootloader/bootloader-reflash-digest.bin_enc 0x8000 build/GPY/release/lib/partitions.bin_enc 0x10000 build/GPY/release/gpy.bin_enc_0x10000
```
## OTA update
The OTA should be done using the pre-encrypted application image.
Because the encryption is done based on the physical flash address, there are 2 application binaries generated:
* `gpy.bin_enc_0x10000` which has to be written at default factory address: `0x10000`
* `gpy.bin_enc_0x1A0000` which has to be written at the `ota_0` partition address \(`0x1A0000`\)
{% hint style="info" %}
Hint: on MicroPython interface, the method `pycom.ota_slot()` responds with the address of the next OTA partition available \(either `0x10000` or `0x1A0000`\).
{% endhint %}

4
documentation-notes/introduction.md
View File

@@ -1,4 +0,0 @@
# Introduction
The Pycom documentation aims to be straightforward and to adhere to typical Python documentation to allow for ease of understanding. However, there may be some unusual features for those not used to Python documentation or that are new to the MicroPython Language. This section of the documentation aims to provide clarity for any of the design specifics that might be confusing for those new to Python and this style of documentation.

4
documentation-notes/mesh-networks.md
View File

@@ -1,4 +0,0 @@
# Mesh Networks
Mesh Networking is currently under development. Please click [here](https://docs.pycom.io/v/development_release/tutorials/lora/lora-mesh) for the documentation. Please keep in mind that this document is still only informational.

34
documentation-notes/replscript.md
View File

@@ -1,34 +0,0 @@
# REPL vs Scripts
Users of this documentation should be aware that examples given in the docs are under the expectation that they are being executed using the MicroPython REPL. This means that when certain functions are called, their output may not necessarily be printed to the console if they are run from a script. When using the REPL many classes/functions automatically produce a printed output displaying the return value of the function to the console. The code snippet below demonstrates some examples of classes/functions that might display this behaviour.
## Basic Arithmetic
```python
1 + 1 # REPL will print out '2' to console
1 + 1 # Script will not return anything the console
print(1 + 1) # Both the REPL and a script will return '2' to the console
```
## Calling Methods
```python
import ubinascii
ubinascii.hexlify(b'12345') # REPL will print out "b'3132333435'" to the console
ubinascii.hexlify(b'12345') # Script will not return any the console
```
In order to use these functions that do not print out any values, you will need to either wrap them in a `print()` statement or assign them to variables and call them later when you wish to use them.
For example:
```python
# immediately print to console when using a script
print(1 + 1)
# or save variable to for later
value = 1 + 1
# do something here...
print(value)
```

95
documentation-notes/syntax.md
View File

@@ -1,95 +0,0 @@
# Syntax
The Pycom documentation follows standard Python Library format using the popular Sphinx Docs tool. There are some notable points regarding the syntax of classes, methods and constants. Please see the notes below and familiarise yourself with the specific details before reviewing the documentation.
## Keyword Arguments
`Keyword Arguments` refer to the arguments that are passed into a constructor \(upon referencing a class object\). When passing values into a MicroPython constructor it is not always required to specify the name of the argument and instead rely on the order of the arguments passed as to describe what they refer to. In the example below, it can be seen that the argument `mode` is passed into the `i2c.init()` method without specifying a name.
The values of the arguments \(as seen in the examples/docs\) refer to the default values that are passed into the constructor if nothing is provided.
```python
i2c.init(mode, * , baudrate=100000, pins=(SDA, SCL))
```
An example of how this method might be called:
```python
i2c.init(I2C.MASTER, pins=('P12', 'P11'))
```
It can be seen that a value for `baudrate` was not passed into the method and thus MicroPython will assume a default value of `100000`. Also the first argument `mode` was not specified by name, as the constructor does not require it, denoted by the lack of an `=` symbol in the constructor documentation.
## Passing Arguments into a Method
It is important to note that there are certain class methods that can only accept a `keyword` for certain arguments as well as some that only accept a `value`. This is intentional by design but is not always apparent to the user calling specific methods. The differences between the two are outlined below, with examples referencing where differences might apply and what to be aware of.
## Keyword
An astrik `*` in a method description \(in the docs\), denotes that the following arguments require a keyword, i.e. `pin='P16'` in the example below.
```python
adc.channel(* , pin, attn=ADC.ATTN_0DB)
```
```python
from machine import ADC
adc = ADC() # create an ADC object
apin = adc.channel(pin='P16') # create an analog pin on P16
```
`pin` is a required argument and the method `channel` will not execute unless it is passed as with a keyword.
Another example shows how the `PWM` class, `pwm.channel()` requires a keyword argument for `pin` but does not for `id`.
```python
from machine import PWM
pwm = PWM(0, frequency=5000)
pwm_c = pwm.channel(0, pin='P12') # no keyword argument requires for id (0) but is required for pin (pin='P12')
```
## Value
The documentation may refer to a method that takes an argument listed by name but does allow for a keyword to be passed. For example, the `pycom` class contains a method `rgbled`. This lists that the method accepts a value for `color`, however this may not be specified by `keyword`, only `value`. This is intentional as the `value` being passed is the only argument valid for this method
```python
pycom.rgbled(color)
```
If the argument is passed into the method with a keyword, it will return an error stating TypeError: function does not take keyword arguments.
```python
import pycom
pycom.rgbled(color=0xFF0000) # Incorrect
pycom.rgbled(0xFF0000) # Correct
```
Another example of a method that only accepts value input. In this case, the `RTC.init()` method require a value \(`tuple`\) input for the `datetime`. It will not accept a keyword.
```python
rtc.init(datetime)
```
```python
from machine import RTC
rtc = RTC()
rtc.init(datetime=(2014, 5, 1, 4, 13, 0, 0, 0)) # Incorrect
rtc.init((2014, 5, 1, 4, 13, 0, 0, 0)) # Correct
```
## Constants
The `constants` section of a library within the docs refers to specific values from that library’s class. These might be used when constructing an object from that class or when utilising a method from within that class. These are generally listed by the library name followed by the specific value. See the example below:
```python
I2C.MASTER()
```
{% hint style="info" %}
Be aware that you can only reference these constants upon importing and constructing a object from a library.
{% endhint %}

104
documents/certificates.md
View File

@@ -1,104 +0,0 @@
# Certificates
## CE RED
### Development Boards
#### LoPy
{% file src="../.gitbook/assets/16-213298\_expertise\_pycom\_lopy-1.0r.pdf" caption="LoPy CE RED Certificate" %}
#### WiPy 2.0
{% file src="../.gitbook/assets/16-213297\_expertise\_pycom\_wipy-2.0r.pdf" caption="WiPy 2.0 CE RED Certificate" %}
#### WiPy 3.0
{% file src="../.gitbook/assets/17-214126\_red-certificate\_pycom\_wipy-3.0.pdf" caption="WiPy 3.0 CE RED Certificate" %}
#### SiPy
{% file src="../.gitbook/assets/17-210585\_expertise\_sipy\_sipy-1.0.pdf" caption="SiPy CE RED Certificate" %}
#### GPy
{% file src="../.gitbook/assets/c03-b0-red-final \(1\).pdf" caption="GPy CE RED Certificate" %}
#### FiPy
{% file src="../.gitbook/assets/fipy\_c03-b0-red-final.pdf" caption="FiPy CE RED Certificate" %}
### OEM Modules
#### L01
{% file src="../.gitbook/assets/17-213356\_red-certificate\_pycom\_l01-1.0.pdf" caption="L01 CE RED Certificate" %}
#### W01
{% file src="../.gitbook/assets/17-213357\_red-certificate\_pycom\_w01-1.0.pdf" caption="W01 CE RED Certificate" %}
#### G01
{% file src="../.gitbook/assets/c03-b0-red-final.pdf" caption="G01 CE RED Certificate" %}
## FCC
### Development Boards
#### LoPy
{% file src="../.gitbook/assets/2090acc16\_grant.pdf" caption="LoPy FCC Certificate" %}
{% file src="../.gitbook/assets/2090bcc16\_grant.pdf" caption="LoPy FCC Certificate" %}
{% file src="../.gitbook/assets/2090ccc16\_grant.pdf" caption="LoPy FCC Certificate" %}
#### WiPy 2.0
{% file src="../.gitbook/assets/2091acc16\_grant.pdf" caption="WiPy 2.0 FCC Certificate" %}
{% file src="../.gitbook/assets/2091bcc16\_grant.pdf" caption="WiPy 2.0 FCC Certificate" %}
#### GPy
{% file src="../.gitbook/assets/pycom-2ajmtgpy01r-fcc-grant-dss.pdf" caption="GPy FCC Certificate" %}
{% file src="../.gitbook/assets/pycom-2ajmtgpy01r-fcc-grant-dts.pdf" caption="GPy FCC Certificate" %}
{% file src="../.gitbook/assets/pycom-2ajmtgpy01r-fcc-grant-tnb.pdf" caption="GPy FCC Certificate" %}
#### FiPy
{% file src="../.gitbook/assets/pycom-2ajmtfipy01r-fcc-grant-dss.pdf" caption="FiPy FCC Certificate" %}
{% file src="../.gitbook/assets/pycom-2ajmtfipy01r-fcc-grant-dts.pdf" caption="FiPy FCC Certificate" %}
{% file src="../.gitbook/assets/pycom-2ajmtfipy01r-fcc-grant-dxx.pdf" caption="FiPy FCC Certificate" %}
{% file src="../.gitbook/assets/pycom-2ajmtfipy01r-fcc-grant-tnb.pdf" caption="FiPy FCC Certificate" %}
### OEM Modules
#### L01
{% file src="../.gitbook/assets/172181411\_aa\_00\_final.pdf" caption="L01 FCC Certificate" %}
{% file src="../.gitbook/assets/172181413\_aa\_00\_final.pdf" caption="L01 FCC Certificate" %}
{% file src="../.gitbook/assets/172181414\_aa\_00\_final.pdf" caption="L01 FCC Certificate" %}
#### W01
{% file src="../.gitbook/assets/172181407\_aa\_00\_final.pdf" caption="W01 FCC Certificate" %}
{% file src="../.gitbook/assets/172181408\_aa\_00\_final.pdf" caption="W01 FCC Certificate" %}
#### G01
{% file src="../.gitbook/assets/pycom-2ajmtg01r-fcc-grant-dss.pdf" caption="G01 FCC Certificate" %}
{% file src="../.gitbook/assets/pycom-2ajmtg01r-fcc-grant-dts.pdf" caption="G01 FCC Certificate" %}
{% file src="../.gitbook/assets/pycom-2ajmtg01r-fcc-grant-tnb.pdf" caption="G01 FCC Certificate" %}

16
documents/license.md
View File

@@ -1,16 +0,0 @@
# License
The MIT License \(MIT\)
Copyright \(c\) 2013-2015 Damien P. George, and others
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files \(the “Software”\), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Copyright \(c\) 2017, Pycom Limited.
This software is licensed under the GNU GPL version 3 or any later version, with permitted additional terms. For more information see the Pycom Licence v1.0 document supplied with this file, or available at [https://www.pycom.io/opensource/licensing](https://www.pycom.io/opensource/licensing)

15
firmware-and-api-reference/introduction.md
View File

@@ -1,15 +0,0 @@
# 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.

10
firmware-and-api-reference/micropython/README.md
View File

@@ -1,10 +0,0 @@
# 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 %}

86
firmware-and-api-reference/micropython/_thread.md
View File

@@ -1,86 +0,0 @@
# \_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")
```

22
firmware-and-api-reference/micropython/array.md
View File

@@ -1,22 +0,0 @@
# 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.

126
firmware-and-api-reference/micropython/builtin.md
View File

@@ -1,126 +0,0 @@
# 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\(\)

47
firmware-and-api-reference/micropython/cmath.md
View File

@@ -1,47 +0,0 @@
# 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

24
firmware-and-api-reference/micropython/gc.md
View File

@@ -1,24 +0,0 @@
# 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.

163
firmware-and-api-reference/micropython/math.md
View File

@@ -1,163 +0,0 @@
# 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

59
firmware-and-api-reference/micropython/micropython.md
View File

@@ -1,59 +0,0 @@
# 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.

49
firmware-and-api-reference/micropython/select.md
View File

@@ -1,49 +0,0 @@
# 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.

62
firmware-and-api-reference/micropython/sys.md
View File

@@ -1,62 +0,0 @@
# 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.

28
firmware-and-api-reference/micropython/ubinascii.md
View File

@@ -1,28 +0,0 @@
# 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.

22
firmware-and-api-reference/micropython/ucrypto.md
View File

@@ -1,22 +0,0 @@
# 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 %}

138
firmware-and-api-reference/micropython/uctypes.md
View File

@@ -1,138 +0,0 @@
# 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\).

44
firmware-and-api-reference/micropython/uhashlib.md
View File

@@ -1,44 +0,0 @@
# 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.

18
firmware-and-api-reference/micropython/ujson.md
View File

@@ -1,18 +0,0 @@
# 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.

101
firmware-and-api-reference/micropython/uos.md
View File

@@ -1,101 +0,0 @@
# 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

57
firmware-and-api-reference/micropython/ure.md
View File

@@ -1,57 +0,0 @@
# 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.

166
firmware-and-api-reference/micropython/usocket.md
View File

@@ -1,166 +0,0 @@
# 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.
#### socket.dnsserver(*, dnsIndex, ip_addr)
When no arguments are passed this function returns the configured DNS servers Primary (Index=0) and backup (Index = 1)
to set primary and Backup DNS servers specify the Index and Ip Address.
Example:
```
>>> socket.dnsserver()
('10.0.0.1', '8.8.8.8')
```
Setting DNS servers:
```
>>> socket.dnsserver(1, '0.0.0.0')
>>> socket.dnsserver()
('10.0.0.1', '0.0.0.0')
```

40
firmware-and-api-reference/micropython/ussl.md
View File

@@ -1,40 +0,0 @@
# 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`

30
firmware-and-api-reference/micropython/ustruct.md
View File

@@ -1,30 +0,0 @@
# 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.

87
firmware-and-api-reference/micropython/utime.md
View File

@@ -1,87 +0,0 @@
# 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 %}

16
firmware-and-api-reference/notes.md
View File

@@ -1,16 +0,0 @@
# 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 %}

4
firmware-and-api-reference/pycom/README.md
View File

@@ -1,4 +0,0 @@
# 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.

62
firmware-and-api-reference/pycom/aes.md
View File

@@ -1,62 +0,0 @@
# 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 %}

106
firmware-and-api-reference/pycom/machine/README.md
View File

@@ -1,106 +0,0 @@
# 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`

100
firmware-and-api-reference/pycom/machine/adc.md
View File

@@ -1,100 +0,0 @@
---
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 %}

132
firmware-and-api-reference/pycom/machine/can.md
View File

@@ -1,132 +0,0 @@
# 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 \(&gt;= 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`

46
firmware-and-api-reference/pycom/machine/dac.md
View File

@@ -1,46 +0,0 @@
# 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.

128
firmware-and-api-reference/pycom/machine/i2c.md
View File

@@ -1,128 +0,0 @@
# 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.

155
firmware-and-api-reference/pycom/machine/pin.md
View File

@@ -1,155 +0,0 @@
# 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.
* `*`
* Pin value: `0` or `1`
* `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`

34
firmware-and-api-reference/pycom/machine/pwm.md
View File

@@ -1,34 +0,0 @@
# 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.

134
firmware-and-api-reference/pycom/machine/rmt.md
View File

@@ -1,134 +0,0 @@
---
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`

79
firmware-and-api-reference/pycom/machine/rtc.md
View File

@@ -1,79 +0,0 @@
# 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`

53
firmware-and-api-reference/pycom/machine/sd.md
View File

@@ -1,53 +0,0 @@
# 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 %}

87
firmware-and-api-reference/pycom/machine/spi.md
View File

@@ -1,87 +0,0 @@
# 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`

127
firmware-and-api-reference/pycom/machine/timer.md
View File

@@ -1,127 +0,0 @@
# 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 %}

135
firmware-and-api-reference/pycom/machine/uart.md
View File

@@ -1,135 +0,0 @@
# 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`

28
firmware-and-api-reference/pycom/machine/wdt.md
View File

@@ -1,28 +0,0 @@
# 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.

4
firmware-and-api-reference/pycom/network/README.md
View File

@@ -1,4 +0,0 @@
# 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.

253
firmware-and-api-reference/pycom/network/bluetooth/README.md
View File

@@ -1,253 +0,0 @@
# 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.
{% hint style="info" %}
To use an external antenna, set `P12 as output pin.`
```python
Pin('P12', mode=Pin.OUT)(True)
```
{% endhint %}
### 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 &gt; 0, then the BLE radio will listen for advertisements until the specified value in seconds elapses. If timeout &lt; 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`.
Connections are initiated by the central device. There is a maximum of 4 simultaneous connections.
```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`

8
firmware-and-api-reference/pycom/network/bluetooth/gatt.md
View File

@@ -1,8 +0,0 @@
# 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.

44
firmware-and-api-reference/pycom/network/bluetooth/gattccharacteristic.md
View File

@@ -1,44 +0,0 @@
# 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.

51
firmware-and-api-reference/pycom/network/bluetooth/gattcconnection.md
View File

@@ -1,51 +0,0 @@
# 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())
```

24
firmware-and-api-reference/pycom/network/bluetooth/gattccservice.md
View File

@@ -1,24 +0,0 @@
# 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.

83
firmware-and-api-reference/pycom/network/bluetooth/gattscharacteristic.md
View File

@@ -1,83 +0,0 @@
# 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)
```

31
firmware-and-api-reference/pycom/network/bluetooth/gattsservice.md
View File

@@ -1,31 +0,0 @@
# 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)
```

486
firmware-and-api-reference/pycom/network/lora.md
View File

@@ -1,486 +0,0 @@
# 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)
```

188
firmware-and-api-reference/pycom/network/lte.md
View File

@@ -1,188 +0,0 @@
# 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-and-examples/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\(detach=True, reset = False\)
Disables LTE modem completely. This reduces the power consumption to the minimum. Call this before entering deepsleep.
- `detach` : detach from network.
- `reset` : reset LTE modem.
#### lte.attach\(\*, band=None, apn=None, cid=None, type=LTE.IP, legacyattach=True\)
Enable radio functionality and attach to the LTE network authorised by the inserted SIM card. Optionally specify:
- `band` : to scan for networks. If no band \(or `None`\) is specified, all 8 bands will be scanned. The possible values for the band are: `3, 4, 5, 8, 12, 13, 20 and 28`.
- `apn` : Specify the APN (Access point Name).
- `cid` : connection ID, see `LTE.connect()`. when the ID is set here it will be remembered when doint connect so no need to specify again
- `type` : PDP context type either `LTE.IP` or `LTE.IPV4V6`. These are options to specify PDP type ‘Packet Data protocol’ either IP [Internet Protocol] or IPV4V6 ver4,6 , that depends actually on what does the Network support.
- `legacyattach` : When kept = True the API `LTE.isattached()` will return True when attached to the Network AND Network registration status is home or roaming, when flag is False, API `LTE.isattached()` will return True when attached to the Network only.
---
*NOTE* :
When carrier is specified in `LTE()` or `LTE.init()` (eg. `lte = LTE(carrier=verizon)`) No need to specify band, apn or type these parameters are already programmed in to the LTE modem for each carrier.
---
#### lte.isattached\(\)
Returns `True` if the cellular mode is attached to the network. `False` otherwise.
#### lte.detach\(reset=False\)
Detach the modem from the LTE Cat M1 and disable the radio functionality.
- `reset` : set to True to reset the LTE modem.
#### 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, delay=10000\)
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
```
- `delay` : specify maximum Timeout in ms to wait response from modem.
#### 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.
#### lte.pppsuspend\(\)
Suspend PPP session with LTE modem. this function can be used when needing to send AT commands which is not supported in PPP mode.
#### lte.pppresume\(\)
Resumes PPP session with LTE modem.
#### lte.factory\_reset\(\)
Reset modem configuration to Factory settings.
#### lte.modem\_upgrade\_mode\(\)
Puts the modem in to modem upgrade mode and bridging LTE modem UART port to FiPy/GPy UART0 to enable upgrading Firmware over USB port.
---
*NOTE* :
In this mode all All tasks on the board are halted and a reset is required to regain functionality.
---
#### lte.reconnect\_uart\(\)
Reconnect esp32 UART 2 to LTE modem UART port.
#### lte.ue\_coverage\(\)
Check Network Coverage for UE device (i.e LTE modem).
`True`: There is Network Coverage.
`False`: No Netwok Coverage.
## Constants
- `LTE.IP` : Internet Protocol IP
- `LTE.IPV4V6` : Internet protocol ver. 4/6

50
firmware-and-api-reference/pycom/network/server.md
View File

@@ -1,50 +0,0 @@
# 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.

279
firmware-and-api-reference/pycom/network/sigfox.md
View File

@@ -1,279 +0,0 @@
# 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 %}

172
firmware-and-api-reference/pycom/network/wlan.md
View File

@@ -1,172 +0,0 @@
# 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)
```
{% hint style="info" %}
To use an external antenna, set `P12 as output pin.`
```python
Pin('P12', mode=Pin.OUT)(True)
```
{% endhint %}
#### 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\).
{% hint style="info" %}
To use an external antenna, set `P12 as output pin.`
```python
Pin('P12', mode=Pin.OUT)(True)
```
{% endhint %}
#### 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`

153
firmware-and-api-reference/pycom/pycom.md
View File

@@ -1,153 +0,0 @@
# 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.

14
getting-started/connection/README.md
View File

@@ -1,14 +0,0 @@
# Hardware Setup
This chapter of the documentation will show you how to connect you Pycom module. For each device there are detailed instructions on how to connect your module to one of our base boards, a USB UART adapter or WiFi as well as what antennas you might need to connect. Please select your module below to be taken to the appropriate guide.
{% page-ref page="lopy.md" %}
{% page-ref page="sipy.md" %}
{% page-ref page="gpy.md" %}
{% page-ref page="fipy.md" %}
{% page-ref page="wipy.md" %}

108
getting-started/connection/fipy.md
View File

@@ -1,108 +0,0 @@
# FiPy
## Basic connection
{% tabs %}
{% tab title="Exp Board 2.0" %}
* When using the expansion board with a FiPy, you will need to remove the CTS and RTS jumpers as these interfere with communication with the cellular modem.
* Look for the reset button on the module \(located at a corner of the board, next to the LED\).
* Locate the USB connector on the expansion board.
* Insert the FiPy module on the the expansion board with the reset button pointing towards the USB connector. It should firmly click into place and the pins should now no longer be visible.
![](../../.gitbook/assets/expansion_board_2_fipy.png)
{% endtab %}
{% tab title="Exp Board 3.0" %}
* Before connecting your module to an Expansion Board 3.0, you should update the firmware on the Expansion Board 3.0. Instructions on how to do this can be found [here](../../pytrack-pysense-pyscan/installation/firmware.md).
* When using the expansion board with a FiPy, you will need to remove the CTS and RTS jumpers as these interfere with communication with the cellular modem.
* Look for the reset button on the module \(located at a corner of the board, next to the LED\).
* Locate the USB connector on the expansion board.
* Insert the FiPy module on the Expansion Board with the reset button pointing towards the USB connector. It should firmly click into place and the pins should now no longer be visible.
![](../../.gitbook/assets/expansion_board_3_fipy.png)
{% endtab %}
{% tab title="Pytrack/Pysense/Pyscan" %}
* Before connecting your module to a Pysense/Pytrack/Pyscan board, you should update the firmware on the Pysense/Pytrack/Pyscan. Instructions on how to do this can be found [here](../../pytrack-pysense-pyscan/installation/firmware.md).
* Look for the reset button on the FiPy module \(located at a corner of the board, next to the LED\).
* Locate the USB connector on the Pysense/Pytrack/Pyscan.
* Insert the module on the Pysense/Pytrack/Pyscan with the reset button pointing towards the USB connector. It should firmly click into place and the pins should now no longer be visible. ![](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LIfiUlGe6_zTmmvcuEa%2F-LKMXk1KQvBgjpw04I3u%2F-LIqVauBuoNMgcByrNql%2FPysense_FiPy.png?generation=1534772069160637&alt=media)![](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LIfiUlGe6_zTmmvcuEa%2F-LKMXk1KQvBgjpw04I3u%2F-LIqVdDdxkK38AlRxtkc%2FPytrack_FiPy.png?generation=1534772071490748&alt=media)
{% endtab %}
{% tab title="USB UART Adapter" %}
* Firstly you will need to connect power to your FiPy. You will need to supply `3.5v`-`5.5v` to the `Vin` pin.
{% hint style="danger" %}
Do **not** feed `3.3v` directly to the `3.3v` supply pin, this will damage the regulator.
{% endhint %}
* The connect the `RX` and `TX` of your USB UART to the `TX` and `RX` of the FiPy respectively.
{% hint style="warning" %}
Please ensure you have the signal level of the UART adapter set to `3.3v` before connecting it.
{% endhint %}
* In order to put the FiPy into bootloader mode to update the device firmware you will need to connect `P2` to `GND`. We recommend you connect a button between the two to make this simpler.
![](../../.gitbook/assets/uart_fipy.png)
{% endtab %}
{% tab title="WiFi" %}
**Note:** This method of connection is not recommended for first time users. It is possible to lock yourself out of the device, requiring a USB connection.
* In order to access the FiPy via WiFi you only need to provide `3.5v` - `5.5v` on the `Vin` pin of the FiPy:
![](../../.gitbook/assets/bare_fipy.png)
* By default, when the FiPy boots, it will create a WiFi access point with the following credentials:
* SSID: `fipy-wlan`
* password: `www.pycom.io`
* Once connected to this network you will be able to access the telnet and FTP servers running on the FiPy. For both of these the login details are:
* username: `micro`
* password: `python`
{% endtab %}
{% endtabs %}
## Antennas
### Lora/Sigfox
{% hint style="danger" %}
If you intend on using the LoRa/Sigfox connectivity of the FiPy you **must** connect a LoRa/Sigfox antenna to your FiPy before trying to use LoRa/Sigfox otherwise you risk damaging the device.
{% endhint %}
{% hint style="info" %}
The FiPy only supports LoRa on the 868MHz or 915MHz bands. It does not support 433MHz. For this you will require a LoPy4.
{% endhint %}
* Firstly you will need to connect the U.FL to SMA pig tail to the FiPy using the U.FL connector on the same side of the FiPy as the LED.
![](../../.gitbook/assets/lora_sigfox_pigtail_fipy.png)
* If you are using a pycase, you will next need to put the SMA connector through the antenna hole, ensuring you align the flat edge correctly, and screw down the connector using the provided nut.
* Finally you will need to screw on the antenna to the SMA connector.
![](../../.gitbook/assets/lora_sigfox_pigtail_ant_fipy.png)
### LTE Cat-M1/NB-IoT
{% hint style="danger" %}
If you intend on using the LTE CAT-M1 or NB-IoT connectivity of the FiPy you **must** connect a LTE CAT-M1/NB-IoT antenna to your FiPy before trying to use LTE Cat-M1 or NB-IoT otherwise you risk damaging the device.
{% endhint %}
* You will need to connect the antenna to the FiPy using the U.FL connector on the under side of the FiPy.
![](../../.gitbook/assets/lte_ant_fipy.png)
### WiFi/Bluetooth \(optional\)
All Pycom modules, including the FiPy, come with a on-board WiFi antenna as well as a U.FL connector for an external antenna. The external antenna is optional and only required if you need better performance or are mounting the FiPy in such a way that the WiFi signal is blocked. Switching between the antennas is done via software, instructions for this can be found [here.](../../firmware-and-api-reference/pycom/network/wlan.md)
![](../../.gitbook/assets/wifi_pigtail_ant_fipy.png)
### SIM card <a id="sim-card"></a>
If you intend on using the LTE CAT-M1 or NB-IoT connectivity of the FiPy you will need to insert a SIM card into your FiPy. It should be noted that the FiPy does not support regular LTE connectivity and you may require a special SIM. It is best to contact your local cellular providers for more information on acquiring a LTE CAT-M1/NB-IoT enabled nano SIM.
![](../../.gitbook/assets/sim_fipy.png)

85
getting-started/connection/gpy.md
View File

@@ -1,85 +0,0 @@
# GPy
## Basic connection
{% tabs %}
{% tab title="Exp Board 2.0" %}
* Look for the reset button on the module \(located at a corner of the board, next to the LED\).
* Locate the USB connector on the expansion board.
* Insert the GPy module on the the expansion board with the reset button pointing towards the USB connector. It should firmly click into place and the pins should now no longer be visible.
![](../../.gitbook/assets/expansion_board_2_gpy.png)
{% endtab %}
{% tab title="Exp Board 3.0" %}
* Before connecting your module to an Expansion Board 3.0, you should update the firmware on the Expansion Board 3.0. Instructions on how to do this can be found [here](../../pytrack-pysense-pyscan/installation/firmware.md).
* Look for the reset button on the module \(located at a corner of the board, next to the LED\).
* Locate the USB connector on the expansion board.
* Insert the GPy module on the Expansion Board with the reset button pointing towards the USB connector. It should firmly click into place and the pins should now no longer be visible.
![](../../.gitbook/assets/expansion_board_3_gpy.png)
{% endtab %}
{% tab title="Pytrack/Pysense/Pyscan" %}
* Before connecting your module to a Pysense/Pytrack/Pyscan board, you should update the firmware on the Pysense/Pytrack/Pyscan. Instructions on how to do this can be found [here](../../pytrack-pysense-pyscan/installation/firmware.md).
* Look for the reset button on the GPy module \(located at a corner of the board, next to the LED\).
* Locate the USB connector on the Pysense/Pytrack/Pyscan.
* Insert the module on the Pysense/Pytrack/Pyscan with the reset button pointing towards the USB connector. It should firmly click into place and the pins should now no longer be visible. ![](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LIfiUlGe6_zTmmvcuEa%2F-LKMXk1KQvBgjpw04I3u%2F-LIqejpmTIS1tbGw0Vrl%2FPysense_GPy.png?generation=1534772072781141&alt=media)![](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LIfiUlGe6_zTmmvcuEa%2F-LKMXk1KQvBgjpw04I3u%2F-LIqekpWIfccll6qkt85%2FPytrack_GPy.png?generation=1534772080535030&alt=media)
{% endtab %}
{% tab title="USB UART Adapter" %}
* Firstly you will need to connect power to your GPy. You will need to supply `3.5v`-`5.5v` to the `Vin` pin.
{% hint style="danger" %}
Do **not** feed `3.3v` directly to the `3.3v` supply pin, this will damage the regulator.
{% endhint %}
* The connect the `RX` and `TX` of your USB UART to the `TX` and `RX` of the GPy respectively.
{% hint style="warning" %}
Please ensure you have the signal level of the UART adapter set to `3.3v` before connecting it.
{% endhint %}
* In order to put the GPy into bootloader mode to update the device firmware you will need to connect `P2` to `GND`. We recommend you connect a button between the two to make this simpler.
{% endtab %}
{% tab title="WiFi" %}
**Note:** This method of connection is not recommended for first time users. It is possible to lock yourself out of the device, requiring a USB connection.
* In order to access the GPy via WiFi you only need to provide `3.5v` - `5.5v` on the `Vin` pin of the GPy:
![](../../.gitbook/assets/bare_gpy.png)
* By default, when the GPy boots, it will create a WiFi access point with the following credentials:
* SSID:`gpy-wlan`
* password: `www.pycom.io`
* Once connected to this network you will be able to access the telnet and FTP servers running on the GPy. For both of these the login details are:
* username: `micro`
* password: `python`
{% endtab %}
{% endtabs %}
## Antennas
### LTE Cat-M1/NB-IoT
{% hint style="danger" %}
If you intend on using the LTE CAT-M1 or NB-IoT connectivity of the GPy you **must** connect a LTE CAT-M1/NB-IoT antenna to your GPy before trying to use LTE Cat-M1 or NB-IoT otherwise you risk damaging the device.
{% endhint %}
* You will need to connect the antenna to the GPy using the U.FL connector on the same side of the GPy as the LED.
![](../../.gitbook/assets/lte_ant_gpy.png)
### WiFi/Bluetooth \(optional\)
All Pycom modules, including the GPy, come with a on-board WiFi antenna as well as a U.FL connector for an external antenna. The external antenna is optional and only required if you need better performance or are mounting the GPy in such a way that the WiFi signal is blocked. Switching between the antennas is done via software, instructions for this can be found [here.](../../firmware-and-api-reference/pycom/network/wlan.md)
![](../../.gitbook/assets/wifi_pigtail_ant_gpy.png)
### SIM card <a id="sim-card"></a>
If you intend on using the LTE CAT-M1 or NB-IoT connectivity of the GPy you will need to insert a SIM card into your GPy. It should be noted that the GPy does not support regular LTE connectivity and you may require a special SIM. It is best to contact your local cellular providers for more information on acquiring a LTE CAT-M1/NB-IoT enabled nano SIM.
![](../../.gitbook/assets/sim_gpy.png)

94
getting-started/connection/lopy.md
View File

@@ -1,94 +0,0 @@
# LoPy
## Basic connection
{% tabs %}
{% tab title="Exp Board 2.0" %}
* Look for the reset button on the module \(located at a corner of the board, next to the LED\).
* Locate the USB connector on the expansion board.
* Insert the LoPy module on the the expansion board with the reset button pointing towards the USB connector. It should firmly click into place and the pins should now no longer be visible.
![](../../.gitbook/assets/expansion_board_2_lopy.png)
{% endtab %}
{% tab title="Exp Board 3.0" %}
* Before connecting your module to an Expansion Board 3.0, you should update the firmware on the Expansion Board 3.0. Instructions on how to do this can be found [here](../../pytrack-pysense-pyscan/installation/firmware.md).
* Look for the reset button on the module \(located at a corner of the board, next to the LED\).
* Locate the USB connector on the expansion board.
* Insert the LoPy module on the Expansion Board with the reset button pointing towards the USB connector. It should firmly click into place and the pins should now no longer be visible.
![](../../.gitbook/assets/expansion_board_3_lopy.png)
{% endtab %}
{% tab title="Pytrack/Pysense/Pyscan" %}
* Before connecting your module to a Pysense/Pytrack/Pyscan board, you should update the firmware on the Pysense/Pytrack/Pyscan. Instructions on how to do this can be found [here](../../pytrack-pysense-pyscan/installation/firmware.md).
* Look for the reset button on the LoPy module \(located at a corner of the board, next to the LED\).
* Locate the USB connector on the Pysense/Pytrack/Pyscan.
* Insert the module on the Pysense/Pytrack/Pyscan with the reset button pointing towards the USB connector. It should firmly click into place and the pins should now no longer be visible. ![](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LIfiUlGe6_zTmmvcuEa%2F-LKMXk1KQvBgjpw04I3u%2F-LIq_ZvQtB3k9-QzXSEi%2FPysense_LoPy.png?generation=1534772084691543&alt=media)![](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LIfiUlGe6_zTmmvcuEa%2F-LKMXk1KQvBgjpw04I3u%2F-LIq_aBQabbigN5pR8W2%2FPytrack_LoPy.png?generation=1534772068406423&alt=media)
{% endtab %}
{% tab title="USB UART Adapter" %}
* Firstly you will need to connect power to your LoPy. You will need to supply `3.5v`-`5.5v` to the `Vin` pin.
{% hint style="danger" %}
Do _not_ feed `3.3v` directly to the `3.3v` supply pin, this will damage the regulator.
{% endhint %}
* The connect the `RX` and `TX` of your USB UART to the `TX` and `RX` of the LoPy respectively.
{% hint style="warning" %}
Please ensure you have the signal level of the UART adapter set to `3.3v` before connecting it.
{% endhint %}
* In order to put the LoPy into bootloader mode to update the device firmware you will need to connect `P2` to `GND`. We recommend you connect a button between the two to make this simpler.
![](../../.gitbook/assets/uart_lopy.png)
{% endtab %}
{% tab title="WiFi" %}
**Note:** This method of connection is not recommended for first time users. It is possible to lock yourself out of the device, requiring a USB connection.
* In order to access the LoPy via WiFi you only need to provide `3.5v` - `5.5v` on the `Vin` pin of the LoPy:
![](../../.gitbook/assets/bare_lopy.png)
* By default, when the LoPy boots, it will create a WiFi access point with the following credentials:
* SSID: `lopy-wlan`
* password: `www.pycom.io`
* Once connected to this network you will be able to access the telnet and FTP servers running on the LoPy. For both of these the login details are:
* username: `micro`
* password: `python`
{% endtab %}
{% endtabs %}
## Antennas
### Lora
{% hint style="danger" %}
If you intend on using the LoRa connectivity of the LoPy you **must** connect a LoRa antenna to your LoPy before trying to use LoRa otherwise you risk damaging the device.
{% endhint %}
{% hint style="danger" %}
The LoPy only supports LoRa on the 868MHz or 915MHz bands. It does not support 433MHz. For this you will require a LoPy4.
{% endhint %}
* Firstly you will need to connect the U.FL to SMA pig tail to the LoPy using the U.FL connector on the same side of the LoPy as the LED.
![](../../.gitbook/assets/lora_pigtail_lopy.png)
* If you are using a pycase, you will next need to put the SMA connector through the antenna hole, ensuring you align the flat edge correctly, and screw down the connector using the provided nut.
* Finally you will need to screw on the antenna to the SMA connector.
![](../../.gitbook/assets/lora_pigtail_ant_lopy.png)
### WiFi/Bluetooth \(optional\)
All Pycom modules, including the LoPy, come with a on-board WiFi antenna as well as a U.FL connector for an external antenna. The external antenna is optional and only required if you need better performance or are mounting the LoPy in such a way that the WiFi signal is blocked. Switching between the antennas is done via software, instructions for this can be found [here.](../../firmware-and-api-reference/pycom/network/wlan.md)
![](../../.gitbook/assets/wifi_pigtail_ant_lopy.png)
## Deep Sleep current issue
The LoPy, SiPy, and WiPy 2.0 experience an issue where the modules maintain a high current consumption in deep sleep mode. This issue has been resolved in all newer products. The cause for this issue is the DC to DC switch mode converter remains in a high performance mode even when the device is in deep sleep. The flash memory chip also does not power down. A more detailed explanation can be found [here.](https://forum.pycom.io/topic/1022/root-causes-of-high-deep-sleep-current)

92
getting-started/connection/lopy4.md
View File

@@ -1,92 +0,0 @@
# LoPy 4
## Basic connection
{% tabs %}
{% tab title="Exp Board 2.0" %}
* Look for the reset button on the module \(located at a corner of the board, next to the LED\).
* Locate the USB connector on the expansion board.
* Insert the LoPy4 module on the the expansion board with the reset button pointing towards the USB connector. It should firmly click into place and the pins should now no longer be visible.
![](../../.gitbook/assets/expansion_board_2_lopy4.png)
{% endtab %}
{% tab title="Exp Board 3.0" %}
* Before connecting your module to an Expansion Board 3.0, you should update the firmware on the Expansion Board 3.0. Instructions on how to do this can be found [here](../../pytrack-pysense-pyscan/installation/firmware.md).
* Look for the reset button on the module \(located at a corner of the board, next to the LED\).
* Locate the USB connector on the expansion board.
* Insert the LoPy4 module on the Expansion Board with the reset button pointing towards the USB connector. It should firmly click into place and the pins should now no longer be visible.
![](../../.gitbook/assets/expansion_board_3_lopy4.png)
{% endtab %}
{% tab title="Pytrack/Pysense/Pyscan" %}
* Before connecting your module to a Pysense/Pytrack/Pyscan board, you should update the firmware on the Pysense/Pytrack/Pyscan. Instructions on how to do this can be found [here](../../pytrack-pysense-pyscan/installation/firmware.md).
* Look for the reset button on the LoPy4 module \(located at a corner of the board, next to the LED\).
* Locate the USB connector on the Pysense/Pytrack/Pyscan.
* Insert the module on the Pysense/Pytrack/Pyscan with the reset button pointing towards the USB connector. It should firmly click into place and the pins should now no longer be visible.
![](../../.gitbook/assets/assets-2f-lifiulge6_ztmmvcuea-2f-lkmxk1kqvbgjpw04i3u-2f-liqbk7blltxqntvqzh_-2fpysense_lopy4.png) ![](../../.gitbook/assets/assets-2f-lifiulge6_ztmmvcuea-2f-lkmxk1kqvbgjpw04i3u-2f-liqbluw130dl1amaklt-2fpytrack_lopy4.png)
{% endtab %}
{% tab title="USB UART Adapter" %}
* Firstly you will need to connect power to your LoPy4. You will need to supply `3.5v`-`5.5v` to the `Vin` pin.
{% hint style="danger" %}
Do **not** feed `3.3v` directly to the `3.3v` supply pin, this will damage the regulator.
{% endhint %}
* The connect the `RX` and `TX` of your USB UART to the `TX` and `RX` of the LoPy4 respectively.
{% hint style="warning" %}
Please ensure you have the signal level of the UART adapter set to `3.3v` before connecting it.
{% endhint %}
* In order to put the LoPy4 into bootloader mode to update the device firmware you will need to connect `P2` to `GND`. We recommend you connect a button between the two to make this simpler.
![](../../.gitbook/assets/uart_lopy4.png)
{% endtab %}
{% tab title="WiFi" %}
**Note:** This method of connection is not recommended for first time users. It is possible to lock yourself out of the device, requiring a USB connection.
* In order to access the LoPy4 via WiFi you only need to provide `3.5v` - `5.5v` on the `Vin` pin of the LoPy4:
![](../../.gitbook/assets/bare_lopy4.png)
* By default, when the LoPy4 boots, it will create a WiFi access point with the following credentials:
* SSID: `lopy4-wlan`
* password: `www.pycom.io`
* Once connected to this network you will be able to access the telnet and FTP servers running on the LoPy4. For both of these the login details are:
* username: `micro`
* password: `python`
{% endtab %}
{% endtabs %}
## Antennas
### Lora/Sigfox
{% hint style="danger" %}
If you intend on using the LoRa/Sigfox connectivity of the LoPy4 you **must** connect a LoRa/Sigfox antenna to your LoPy4 before trying to use LoRa/Sigfox otherwise you risk damaging the device.
{% endhint %}
* Firstly you will need to connect the U.FL to SMA pig tail to the LoPy4 using one of the two the U.FL connectors on the same side of the LoPy4 as the LED. The one on the left hand side is for 433MHz \(LoRa only\), the one of the right hand side is for 868MHz/915MHz \(LoRa & Sigfox\). **Note:** This is different from the LoPy.
![](../../.gitbook/assets/lora_sigfox_pigtail_lopy4.png)
* If you are using a pycase, you will next need to put the SMA connector through the antenna hole, ensuring you align the flat edge correctly, and screw down the connector using the provided nut.
* Finally you will need to screw on the antenna to the SMA connector.
![](../../.gitbook/assets/lora_sigfox_pigtail_ant_lopy4.png)
{% hint style="danger" %}
Since the LoRa chip only runs on one frequency band at a time you only need to connect an antenna to the appropriate U.FL connecor. You should be supplied with a the antenna that suits the band you intend using.
{% endhint %}
### WiFi/Bluetooth \(optional\)
All Pycom modules, including the LoPy4, come with a on-board WiFi antenna as well as a U.FL connector for an external antenna. The external antenna is optional and only required if you need better performance or are mounting the LoPy4 in such a way that the WiFi signal is blocked. Switching between the antennas is done via software, instructions for this can be found [here.](../../firmware-and-api-reference/pycom/network/wlan.md)
![](../../.gitbook/assets/wifi_pigtail_ant_lopy4.png)

90
getting-started/connection/sipy.md
View File

@@ -1,90 +0,0 @@
# SiPy
## Basic connection
{% tabs %}
{% tab title="Exp Board 2.0" %}
* Look for the reset button on the module \(located at a corner of the board, next to the LED\).
* Locate the USB connector on the expansion board.
* Insert the SiPy module on the the expansion board with the reset button pointing towards the USB connector. It should firmly click into place and the pins should now no longer be visible.
![](../../.gitbook/assets/expansion_board_2_sipy.png)
{% endtab %}
{% tab title="Exp Board 3.0" %}
* Before connecting your module to an Expansion Board 3.0, you should update the firmware on the Expansion Board 3.0. Instructions on how to do this can be found [here](../../pytrack-pysense-pyscan/installation/firmware.md).
* Look for the reset button on the module \(located at a corner of the board, next to the LED\).
* Locate the USB connector on the expansion board.
* Insert the SiPy module on the Expansion Board with the reset button pointing towards the USB connector. It should firmly click into place and the pins should now no longer be visible.
![](../../.gitbook/assets/expansion_board_3_sipy.png)
{% endtab %}
{% tab title="Pytrack/Pysense/Pyscan" %}
* Before connecting your module to a Pysense/Pytrack/Pyscan board, you should update the firmware on the Pysense/Pytrack/Pyscan. Instructions on how to do this can be found [here](../../pytrack-pysense-pyscan/installation/firmware.md).
* Look for the reset button on the SiPy module \(located at a corner of the board, next to the LED\).
* Locate the USB connector on the Pysense/Pytrack/Pyscan.
* Insert the module on the Pysense/Pytrack/Pyscan with the reset button pointing towards the USB connector. It should firmly click into place and the pins should now no longer be visible. ![](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LIfiUlGe6_zTmmvcuEa%2F-LKMXk1KQvBgjpw04I3u%2F-LIqd_e51Wyuw40k6yJv%2FPysense_SiPy.png?generation=1534772077104600&alt=media)![](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LIfiUlGe6_zTmmvcuEa%2F-LKMXk1KQvBgjpw04I3u%2F-LIqdauW7rAnQlc-AL07%2FPytrack_SiPy.png?generation=1534772072530754&alt=media)
{% endtab %}
{% tab title="USB UART Adapter" %}
* Firstly you will need to connect power to your SiPy. You will need to supply `3.5v`-`5.5v` to the `Vin` pin.
{% hint style="danger" %}
Do **not** feed `3.3v` directly to the `3.3v` supply pin, this will damage the regulator.
{% endhint %}
* The connect the `RX` and `TX` of your USB UART to the `TX` and `RX` of the SiPy respectively.
{% hint style="warning" %}
Please ensure you have the signal level of the UART adapter set to `3.3v` before connecting it.
{% endhint %}
* In order to put the SiPy into bootloader mode to update the device firmware you will need to connect `P2` to `GND`. We recommend you connect a button between the two to make this simpler.
![](../../.gitbook/assets/uart_sipy.png)
{% endtab %}
{% tab title="WiFi" %}
**Note:** This method of connection is not recommended for first time users. It is possible to lock yourself out of the device, requiring a USB connection.
* In order to access the SiPy via WiFi you only need to provide `3.5v` - `5.5v` on the `Vin` pin of the SiPy:
![](../../.gitbook/assets/bare_sipy.png)
* By default, when the SiPy boots, it will create a WiFi access point with the following credentials:
* SSID: `sipy-wlan`
* password: `www.pycom.io`
* Once connected to this network you will be able to access the telnet and FTP servers running on the SiPy. For both of these the login details are:
* username: `micro`
* password: `python`
{% endtab %}
{% endtabs %}
## Antennas
### Sigfox
{% hint style="danger" %}
If you intend on using the Sigfox connectivity of the SiPy you **must** connect a Sigfox antenna to your SiPy before trying to use Sigfox otherwise you risk damaging the device.
{% endhint %}
* Firstly you will need to connect the U.FL to SMA pig tail to the SiPy using the U.FL connector on the same side of the SiPy as the LED.
![](../../.gitbook/assets/sigfox_pigtail_sipy.png)
* If you are using a pycase, you will next need to put the SMA connector through the antenna hole, ensuring you align the flat edge correctly, and screw down the connector using the provided nut.
* Finally you will need to screw on the antenna to the SMA connector.
![](../../.gitbook/assets/sigfox_pigtail_ant_sipy.png)
### WiFi/Bluetooth \(optional\)
All Pycom modules, including the FiPy, come with a on-board WiFi antenna as well as a U.FL connector for an external antenna. The external antenna is optional and only required if you need better performance or are mounting the FiPy in such a way that the WiFi signal is blocked. Switching between the antennas is done via software, instructions for this can be found [here.](../../firmware-and-api-reference/pycom/network/wlan.md)
![](../../.gitbook/assets/wifi_pigtail_ant_sipy.png)
## Deep Sleep current issue
The LoPy, SiPy, and WiPy 2.0 experience an issue where the modules maintain a high current consumption in deep sleep mode. This issue has been resolved in all newer products. The cause for this issue is the DC to DC switch mode converter remains in a high performance mode even when the device is in deep sleep. The flash memory chip also does not power down. A more detailed explanation can be found [here.](https://forum.pycom.io/topic/1022/root-causes-of-high-deep-sleep-current)

84
getting-started/connection/wipy.md
View File

@@ -1,84 +0,0 @@
# WiPy
## Basic connection
{% tabs %}
{% tab title="Exp Board 2.0" %}
* Look for the reset button on the module \(located at a corner of the board, next to the LED\).
* Locate the USB connector on the expansion board.
* Insert the WiPy module on the the expansion board with the reset button pointing towards the USB connector. It should firmly click into place and the pins should now no longer be visible.
![](../../.gitbook/assets/expansion_board_2_wipy.png)
{% endtab %}
{% tab title="Exp Board 3.0" %}
* Before connecting your module to an Expansion Board 3.0, you should update the firmware on the Expansion Board 3.0. Instructions on how to do this can be found [here](../../pytrack-pysense-pyscan/installation/firmware.md).
* Look for the reset button on the module \(located at a corner of the board, next to the LED\).
* Locate the USB connector on the expansion board.
* Insert the WiPy module on the Expansion Board with the reset button pointing towards the USB connector. It should firmly click into place and the pins should now no longer be visible.
![](../../.gitbook/assets/expansion_board_3_wipy.png)
{% endtab %}
{% tab title="Pytrack/Pysense/Pyscan" %}
* Before connecting your module to a Pysense/Pytrack/Pyscan board, you should update the firmware on the Pysense/Pytrack/Pyscan. Instructions on how to do this can be found [here](../../pytrack-pysense-pyscan/installation/firmware.md).
* Look for the reset button on the WiPy module \(located at a corner of the board, next to the LED\).
* Locate the USB connector on the Pysense/Pytrack/Pyscan.
* Insert the module on the Pysense/Pytrack/Pyscan with the reset button pointing towards the USB connector. It should firmly click into place and the pins should now no longer be visible. ![](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LIfiUlGe6_zTmmvcuEa%2F-LKMXk1KQvBgjpw04I3u%2F-LIqfutE_BZ6gjVdmiv0%2FPysense_WiPy.png?generation=1534772071067482&alt=media)![](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LIfiUlGe6_zTmmvcuEa%2F-LKMXk1KQvBgjpw04I3u%2F-LIqfvoSjvxTIwgw2MSg%2FPytrack_WiPy.png?generation=1534772075484372&alt=media)
{% endtab %}
{% tab title="USB UART Adapter" %}
* Firstly you will need to connect power to your WiPy. You will need to supply `3.5v`-`5.5v` to the `Vin` pin.
{% hint style="danger" %}
Do **not** feed `3.3v` directly to the `3.3v` supply pin, this will damage the regulator.
{% endhint %}
* The connect the `RX` and `TX` of your USB UART to the `TX` and `RX` of the WiPy respectively.
{% hint style="warning" %}
Please ensure you have the signal level of the UART adapter set to `3.3v` before connecting it.
{% endhint %}
* In order to put the WiPy into bootloader mode to update the device firmware you will need to connect `P2` to `GND`. We recommend you connect a button between the two to make this simpler.
![](../../.gitbook/assets/uart_wipy.png)
{% endtab %}
{% tab title="WiFi" %}
**Note:** This method of connection is not recommended for first time users. It is possible to lock yourself out of the device, requiring a USB connection.
* In order to access the WiPy via WiFi you only need to provide `3.5v` - `5.5v` on the `Vin` pin of the WiPy:
![](../../.gitbook/assets/bare_wipy.png)
* By default, when the WiPy boots, it will create a WiFi access point with the following credentials:
* SSID: `wipy-wlan`
* password: `www.pycom.io`
* Once connected to this network you will be able to access the telnet and FTP servers running on the WiPy. For both of these the login details are:
* username: `micro`
* password: `python`
{% endtab %}
{% endtabs %}
## Antennas
### WiFi/Bluetooth \(optional\)
All Pycom modules, including the WiPy, come with a on-board WiFi antenna as well as a U.FL connector for an external antenna. The external antenna is optional and only required if you need better performance or are mounting the WiPy in such a way that the WiFi signal is blocked. Switching between the antennas is done via software, instructions for this can be found [here.](../../firmware-and-api-reference/pycom/network/wlan.md)
![](../../.gitbook/assets/wifi_pigtail_ant_wipy.png)
## Deep Sleep current issue
The LoPy, SiPy, and WiPy 2.0 experience an issue where the modules maintain a high current consumption in deep sleep mode. This issue has been resolved in all newer products. The cause for this issue is the DC to DC switch mode converter remains in a high performance mode even when the device is in deep sleep. The flash memory chip also does not power down. A more detailed explanation can be found [here.](https://forum.pycom.io/topic/1022/root-causes-of-high-deep-sleep-current)
## WiPy 2.0 vs WiPy 3.0
The WiPy 3.0 is an upgraded version of the WiPy 2.0 with the following changes:
* The FLASH has been upgraded from 4MB to 8MB.
* The RAM has been upgraded from 512KB to 4MB.
* The deepsleep current consumption issue has been fixed
* The antenna select pin has moved to GPIO21 \(P12\)

8
getting-started/installation/README.md
View File

@@ -1,8 +0,0 @@
# Software
To get you up and running, Pycom provides a suite of tools to assist with developing and programming your Pycom Devices:
1. [**Drivers:**](drivers.md) If you are using Microsoft Windows, you might be required to install drivers for our products to function correctly.
2. [**Pycom firmware update utility:**](firmwaretool.md) This tool automates the process of upgrading the firmware of your Pycom device. It is important that you use this tool before you attempt to use your device. Not only to ensure you have the most stable and feature packed firmware, but also to ensure all the functionality of your device is enable. E.g. this tool also activates your two year free sigfox connectivity.
3. [**Development Environment:**](pymakr.md) Pymakr is a plug-in for Atom and Visual Studio Code developed by Pycom to make development for Pycom modules super easy. It allows you to use your favourite text editor while simplifying the process of uploading code to the device.

56
getting-started/installation/drivers.md
View File

@@ -1,56 +0,0 @@
# Drivers
## Linux
You should not need to install any drivers for our devices to be recognised by Linux. You may how ever need to adjust permissions to make sure you have access to the serial port. On most distributions this can be done by adding your user to the `dialout` user group. Please check the specific instructions for your linux distribution for how to do this.
## macOS
On macOS you shouldn't need to do anything special to get our device to work.
## Windows
All our products will work out of the box for Windows 8/10/+. If using Windows 7, drivers to support the Pysense/Pytrack/Pyscan/Expansion Board 3.0 boards will need to be installed.
### Download
Please download the driver software from the link below.
[Pysense/Pytrack/Pyscan/Expansion Board 3.0 Serial Driver \(save the file to your computer\)](https://raw.githubusercontent.com/pycom/pycom-documentation/master/pytrackpysense/installation/pycom.inf)
{% file src="../../.gitbook/assets/pycom.inf" caption="Pysense/Pytrack/Pyscan/Expansion Board 3.0 Serial Driver" %}
### Installation
First navigate open the Windows start menu and search/navigate to \`Device Manager. You should see your Pytrack/Pysense in the dropdown under **other devices**.
![](../../.gitbook/assets/win7-1.png)
Right click the device and select `Update Driver Software`.
![](../../.gitbook/assets/win7-2%20%281%29.png)
Select the option to **Browse my computer for driver software**.
![](../../.gitbook/assets/win7-3.png)
Next you will need to navigate to where you downloaded the driver to \(e.g. **Downloads** Folder\).
![](../../.gitbook/assets/win7-4%20%281%29.png)
Specify the folder in which the drivers are contained. If you haven't extracted the `.zip` file, please do this before selecting the folder.
![](../../.gitbook/assets/win7-5%20%281%29.png)
You may receive a warning, suggesting that Windows can't verify the publisher of this driver. Click `Install this driver software anyway` as this link points to our official driver.
![](../../.gitbook/assets/win7-6%20%281%29.png)
If the installation was successful, you should now see a window specifying that the driver was correctly installed.
![](../../.gitbook/assets/win7-7.png)
To confirm that the installation was correct, navigate back to the `Device Manager` and click the dropdown for other devices. The warning label should now be gone and Pytrack/Pysense should be installed.
![](../../.gitbook/assets/win7-8.png)

56
getting-started/installation/firmwaretool.md
View File

@@ -1,56 +0,0 @@
# Updating Firmware
We strongly recommend you to upgrade your firmware to the latest version as we are constantly making improvements and adding new features to the devices.
Here are the download links to the update tool. Please download the appropriate one for your OS and follow the instructions on the screen.
* [Windows](https://software.pycom.io/findupgrade?product=pycom-firmware-updater&type=all&platform=win32&redirect=true)
* [macOS](https://software.pycom.io/findupgrade?product=pycom-firmware-updater&type=all&platform=macos&redirect=true) \(10.11 or Higher\)
* [Linux](https://software.pycom.io/findupgrade?product=pycom-firmware-updater&type=all&platform=unix&redirect=true) \(requires `dialog` and `python-serial` package\)
{% hint style="info" %}
Previous versions of firmware are available for download [**here**](../../advanced-topics/downgrade.md).
{% endhint %}
## Updating Device Firmware
The basic firmware upgrade procedure can be found below, please follow these steps carefully:
After you’re done with upgrading, you can use the Pymakr Plugins to upload and run programs in your device.
{% tabs %}
{% tab title="Expansion Board 2.0" %}
1. Disconnect your device from your computer
2. Insert module into the Expansion Board
3. Connect a jumper cable or wire between `G23` and `GND`
4. Reconnect the board via USB to your computer, this puts the device in ‘firmware update mode’.
5. Run the Firmware Upgrade tool
![](../../.gitbook/assets/firmware-update.png)
6. Remove the `G23` to `GND` jumper cable/wire
7. Reboot the device \(button or power off then on\), your device is now ready to use
If you are having any issues, make sure the **TX and RX jumpers** are present on your Expansion Board, as the jumpers sometimes come loose in the box during transport. Without these jumpers, the updater will fail.
{% endtab %}
{% tab title=" Pysense/Pytrack/Pyscan/Expansion Board 3.0" %}
{% hint style="info" %}
When using a Pysense/Pytrack/Pyscan/Expansion Board 3.0 to update your module you are not required to make a connection between `G23` and `GND`, the Pysense/Pytrack/Pyscan/Expansion Board 3.0 will do this automatically.
{% endhint %}
1. Before connecting your module to a Pysense/Pytrack board, you should update the firmware on the Pysense/Pytrack. Instructions on how to do this can be found [here](../../pytrack-pysense-pyscan/installation/firmware.md).
2. Disconnect your device from your computer
3. Insert module into Expansion Board
4. Reconnect the board via USB to your computer
5. Run the Firmware Upgrade tool
![](../../.gitbook/assets/firmware-update-2.png)
6. Disconnect the USB cable from the board and reconnect it, your device is now ready to use
{% endtab %}
{% endtabs %}
After you’re done with upgrading, you can use the Pymakr Plugins to upload and run programs in your device.

12
getting-started/installation/pymakr.md
View File

@@ -1,12 +0,0 @@
# Pymakr
![](../../.gitbook/assets/pymakr-logo-1%20%281%29.png)
## Pymakr Plugins <a id="pymakr-plugins"></a>
To make it as easy as possible Pycom has developed a plugin for two popular text editors, called Pymakr. These plugins have been built and are available for the following platforms:
{% page-ref page="../../pymakr-plugin/installation/atom.md" %}
{% page-ref page="../../pymakr-plugin/installation/vscode.md" %}

26
getting-started/introduction.md
View File

@@ -1,26 +0,0 @@
# Introduction
So, you've decided to order a Pycom development module. Firstly we would like to congratulate you in making an excellent decision. If you haven't yet placed your order we highly recommend you check out the [products](../products.md) page before you place your order to ensure you know which accessories you might require.
![](../.gitbook/assets/getting_started%20%281%29.png)
## [Step 1: Setting up the hardware](connection/)
In the first part of this getting started guide, we will take you through setting up your device. Firstly we will cover how to connect the module to your computer either via USB or WiFi. Secondly we will explain how to connect various accessories such as antennas or SIM cards to your module.
## [Step 2: Setting up your computer](installation/)
Now that your module is successfully connected, you will need to install some software on your computer to interface with it. The second part of this guide will guide you through installing drivers; performing firmware updates for your module/accessories to ensure you have the most stable and feature packed version; and how to setup the software use to program the device.
## [Step 3: Using your module](programming/)
Now that you have a connected module and all the required software installed it is time to begin programming your device. This part of the guide will get you started with a basic example and point you in the right direction for getting your device connected to your chosen network.
## [Step 4: Connecting to a network](registration/)
Now that you familiar with programming your device you will no doubt be keen to get it connected to one of the advertised wireless networks. This usually requires some registration. This step will detail how to get registered and connected to various wireless networks.
{% hint style="info" %}
You can navigate through this guide using the arrow buttons at the bottom of the page.
{% endhint %}

16
getting-started/programming/README.md
View File

@@ -1,16 +0,0 @@
# Programming the modules
Now that you have connected and updated your pycom module and installed all the required software on your computer, we can begin programming your Pycom module.
If this is your first time using a Pycom module we highly recommend you read through the following pages:
* [**Introduction to MicroPython:**](micropython.md) This page will explain what Micropython is and its relation to Python.
* [**MicroPython Examples:**](examples.md) We also recommend you browse these short MicroPython examples to familiarise yourself with its syntax. This is not meant as a comprehensive guide to MicroPython programming but rather a reference to those who already know programming. If you are new to python, or programming all together, we highly recommend searching the internet for Python tutorials. There are many very good tutorials available for free and the skills you learn will be easily transferable to our platform.
* [**Your first Pymakr project:**](first-project.md) Once you understand what MicroPython is, this guide will take you through setting up your first Pymakr project to blink the on-board RGB LED. This guide will explain the structure of a MicroPython project as well as how to upload it to your module.
Once you are familiar with MicroPython and Pymakr, the recommended way of uploading code to your module, you can explore the pages below. These will discuss in greater detail the various mechanisms for running code on your device as well as how to recover it if something goes wrong.
* [**REPL:**](repl/) The REPL \(Read Evaluate Print Loop\) is an interactive terminal that allows you to type in and test your code directly on the device, just like interactive python interpreter. It can be accessed via [UART](repl/serial.md) or [Telnet](repl/telnet.md). This is accessed easiest by using Pymakr but if you wish to use other tools, this page will explain how.
* [**FTP:**](ftp.md) All Pycom modules start up with a WiFi access point enabled, and a simple FTP server running on it. Once connected to the WiFi network, you can use FTP to transfer files over to your device wirelessly. This can be very useful if you do not have physical access to your device.
* [**Safe Boot:**](safeboot.md) It is possible that some code you upload to your module will prevent you accessing the REPL or FTP server, preventing you from updating your scripts. This guide will detail how to safe boot your module and how to remove the offending scripts from it.

108
getting-started/programming/examples.md
View File

@@ -1,108 +0,0 @@
# MicroPython Examples
To get you started with Python \(MicroPython\) syntax, we've provided you with a number of code examples.
## Variable Assignment
As with Python 3.5, variables can be assigned to and referenced. Below is an example of setting a variable equal to a string and then printing it to the console.
```python
variable = "Hello World"
print(variable)
```
## Conditional Statements
Conditional statements allow control over which elements of code run depending on specific cases. The example below shows how a temperature sensor might be implemented in code.
```python
temperature = 15
target = 10
if temperature > target:
print("Too High!")
elif temperature < target:
print("Too Low!")
else:
print("Just right!")
```
## Loops \(For & While loop\)
Loops are another important feature of any programming language. This allows you to cycle your code and repeat functions/assignments/etc.
`for` loops allow you to control how many times a block of code runs for within a range.
```python
x = 0
for y in range(0, 9):
x += 1
print(x)
```
`while` loops are similar to `for` loops, however they allow you to run a loop until a specific conditional is `true/false`. In this case, the loop checks if `x` is less than `9` each time the loop passes.
```python
x = 0
while x < 9:
x += 1
print(x)
```
## Functions
Functions are blocks of code that are referred to by name. Data can be passed into it to be operated on \(i.e. the parameters\) and can optionally return data \(the return value\). All data that is passed to a function is explicitly passed.
The function below takes two numbers and adds them together, outputting the result.
```python
def add(number1, number2):
return number1 + number2
add(1, 2) # expect a result of 3
```
The next function takes an input name and returns a string containing a welcome phrase.
```python
def welcome(name):
welcome_phrase = "Hello, " + name + "!"
print(welcome_phrase)
welcome("Alex") # expect "Hello, Alex!"
```
## Data Structures
Python has a number of different data structures for storing and manipulating variables. The main difference \(regarding data structures\) between C and Python is that Python manages memory for you. This means there’s no need to declare the sizes of lists, dictionaries, strings, etc.
### Lists
A data structure that holds an ordered collection \(sequence\) of items.
```python
networks = ['lora', 'sigfox', 'wifi', 'bluetooth', 'lte-m']
print(networks[2]) # expect 'wifi'
```
### Dictionaries
A dictionary is like an address-book where you can find the address or contact details of a person by knowing only his/her name, i.e. keys \(names\) are associate with values \(details\).
```python
address_book = {'Alex':'2604 Crosswind Drive','Joe':'1301 Hillview Drive','Chris':'3236 Goldleaf Lane'}
print(address_book['Alex']) # expect '2604 Crosswind Drive'
```
### Tuple
Similar to lists but are immutable, i.e. you cannot modify tuples after instantiation.
```python
pycom_devices = ('wipy', 'lopy', 'sipy', 'gpy', 'fipy')
print(pycom_devices[0]) # expect 'wipy'
```
{% hint style="info" %}
For more Python examples, check out these [tutorials](https://www.tutorialspoint.com/python3/). Be aware of the implementation differences between MicroPython and Python 3.5.
{% endhint %}

113
getting-started/programming/first-project.md
View File

@@ -1,113 +0,0 @@
# Your first Pymakr project
This guide will take you through how to setup your first project with Pymakr and make the on-board RGB LED flash various colours.
## Creating a project in Pymakr
1. Firstly you will need to create a new, empty, directory on your computer.
For this example we will create one called `RGB-Blink`.
2. Next you will need to open either Atom or Visual Studio Code depending on
which you setup previously.
3. Once the text editor has loaded you will need to click `File` &gt; `Open`, and open the directory you created in step 1
{% hint style="info" %}
If you are using Atom, it is important to check at this point that Atom has successfully identified the project. The name of the directory you created in step 1 \(`RGB-Blink` in this case\) should be shown in the Pymakr pane like so:
![](../../.gitbook/assets/atom_project.png)
If this is not the case you can press `alt-ctrl-r` on Windows/Linux or `ctrl-alt-cmd-l` on macOS, in order to reload Atom and fix the issue.
{% endhint %}
4. Now that you have a project created, we need to add some files to it. A standard MicroPython project has the following structure:
```text
RGB-Blink
|-lib
| |- some_library.py
|-boot.py
|-main.py
```
* `boot.py` This is the first script that runs on your module when it
turns on. This is often used to connect a module a a WiFi network so that
Telnet and FTP can be used without connecting to the WiFi AP created by the
module and not cluttering up the `main.py` file. As a beginner you do not
need to use a `boot.py`.
* `main.py` This script runs directly after `boot.py` and should contain
the main code you wish to run on your device.
* `lib` It is often a good idea to split out re-usable code into libraries.
If you want to create or use libraries created by others, you will need to
create a `lib` directory and put the library files in this. It is important
that you put `.py` files directly into `lib` rather than creating a directory
tree. By default MicroPython will not detect any libraries within
sub-directories.
For this example, you will just need to create a `main.py` file.
Now that the project structure is setup, you may wish to configure project specific settings for Pymakr e.g. Which serial port to use. On Atom you need to click the `^` button on the Pymakr pane, then click `Project Settings`. On Visual Studio Code you need to click the `All commands` button on the bottom of the windows, then click `Pymakr > Project Settings`. This creates a file called `pymakr.conf` inside your project and populates it with default settings copied over from your global settings. A detailed explanation of these settings can be found [here](../../pymakr-plugin/settings.md).
## Controlling the on-board LED
Now that you have setup and configured your project, we can move on to programming your module. The first thing we will need to do is import some libraries in order to interact with the on-board LED. The Pycom firmware comes with a large amount of libraries for standard functionality built-in. You can find out more about these in the [API documentation](../../firmware-and-api-reference/introduction.md). For this example you will need to open the `main.py` file and add the following code:
```python
import pycom
import time
```
This will import two libraries, `Pycom` which is responsible for Pycom specific features, such as the on-board LED and `time` which is a standard library used timing and delays.
You may have noticed that when you power up your Pycom module, the on-board LED blinks blue on a regular basis. This "heartbeat" is used as a way of know that your module has powered up and started correctly. Before we can change the colour of this LED we need to disable this heart beat. Below your imports you will need to add the following:
```python
pycom.heartbeat(False)
```
Now it's time to test your code. On the Pymakr pane/bottom of the window you will see a `run` button. \(If you haven't connected to your device yet, you will need to do that first\). When you click the run button, the code in the currently open file will be executed on the device, but it won't copy it to the device. After running this code, you should see that that on-board LED stops blinking blue.
Now that we can confirm the device is connected and Pymakr is able to run code on it, we can complete our script to blink the LED like so:
```python
import pycom
import time
pycom.heartbeat(False)
while True:
pycom.rgbled(0xFF0000) # Red
time.sleep(1)
pycom.rgbled(0x00FF00) # Green
time.sleep(1)
pycom.rgbled(0x0000FF) # Blue
time.sleep(1)
```
Once you run the above script, it will run forever. You will notice this prevents you from accessing the interactive REPL on the device \(You cannot see the `>>>` prompt\). In order to stop the script, click onto the Pymakr terminal, and press `ctrl-c` on your keyboard. This should stop the script running and return you to the interactive REPL.
## Uploading to your module
In the previous section we got code running on on your Pycom module using the `run` feature of Pymakr. This is useful for quick testing but has a couple of drawbacks. Firstly the code does not remain on the device permanently. If you reboot the device, it will no longer be running your code. Secondly, it will only work if you are using libraries built into the firmware. If you need any extra libraries, these need to be copied to the device first. This is where the `upload` feature comes in. If instead of `run` you click `upload`, Pymakr will upload all the files in the project \(so long as their type is in the `sync_file_types` setting for your project\). These then persist on your device even between reboots, and allows you to use libraries from the `lib` folder in your project.
If you need to remove files from your device you have two options, either connect via FTP and manage your files that way or format the device's internal flash like so:
```python
import os
os.mkfs('/flash')
```

41
getting-started/programming/ftp.md
View File

@@ -1,41 +0,0 @@
# FTP
There is a small internal file system accessible with each Pycom device, called `/flash`. This is stored within the external serial flash memory. If a microSD card is also connected and mounted, it will be available as well. When the device starts up, it will always boot from the `boot.py` located in the `/flash` file system.
The file system is accessible via the native FTP server running on each Pycom device. Open an FTP client and connect to:
* url: `ftp://192.168.4.1`
* username: `micro`
* password: `python`
See [network.server](../../firmware-and-api-reference/pycom/network/server.md) for information on how to change the defaults. The recommended clients are:
* macOS/Linux: default FTP client
* Windows: Filezilla and FireFTP
For example, from a macOS/Linux terminal:
```bash
$ ftp 192.168.4.1
```
The FTP server doesn’t support active mode, only passive mode. Therefore, if using the native unix FTP client, immediately after logging in, run the following command:
```bash
ftp> passive
```
The FTP server only supports one connection at a time. If using other FTP clients, please check their documentation for how to limit the maximum allowed connections to one at a time.
## FileZilla
If using FileZilla, it's important to configure the settings correctly.
Do not use the quick connect button. Instead, open the site manager and create a new configuration. Within the `General` tab, ensure that encryption is set to: `Only use plain FTP (insecure)`.
![](../../.gitbook/assets/filezilla-settings-1.png)
In the `Transfer Settings` tab, limit the max number of connections to one. Other FTP clients may behave in a similar ways; visit their documentation for more specific information.
![](../../.gitbook/assets/filezilla-settings-2.png)

26
getting-started/programming/micropython.md
View File

@@ -1,26 +0,0 @@
# Introduction to MicroPython
Our boards work with [MicroPython](https://micropython.org/); a Python 3.5 implementation that is optimised to run on micro controllers. This allows for much faster and more simple development process than using C.
![](../../.gitbook/assets/micropython%20%281%29.jpg)
## Booting into MicroPython
When booting, two files are executed automatically: first `boot.py` and then `main.py`. These are placed in the `/flash` folder on the board. Any other files or libraries can be placed here as well, and can be included or used from `boot.py` or `main.py`.
The folder structure in `/flash` looks like the picture below. The files can be managed either using FTP or using the Pymakr Plugin.
![](../../.gitbook/assets/mp-filestructure%20%281%29.png)
## Tips & Tricks
Micropython shares majority of the same syntax as Python 3.5. The intention of this design is to provide compatibility upwards from Micropython to Python 3.5, meaning that code written for Micropython should work in a similar manner in Python 3.5. There are some minor variations and these should taken viewed as implementation differences.
Micropython also has a number of Micropython specific libraries for accessing hardware level features. Specifics relating to those libraries can be found in the Firmware API Reference section of this documentation.
{% hint style="info" %}
Micropython, unlike C/C++ or Arduino, **does not use braces {} to indicate blocks of code** specified for class and function definitions or flow control. Blocks of code are denoted by line indentation, which is strictly enforced.
The number of spaces in the indentation is variable but all statements within a block must be indented the same amount.
{% endhint %}

24
getting-started/programming/repl/README.md
View File

@@ -1,24 +0,0 @@
# REPL
REPL stands for Read Evaluate Print Loop, and is the name given to the interactive MicroPython prompt that is accessible on the Pycom devices. Using the REPL is by far the easiest way to test out Python code and run commands. You can use the REPL in addition to writing scripts in `main.py`.
The following pages will explain how to use the REPL with both Serial USB and Telnet connections.
The REPL includes the following features:
* Input history: use arrow up and arrow down to scroll through the history
* Tab completion: press tab to auto-complete variables or module names
* Halt any executing code: with `Ctrl-C`
* Copy/paste code or output: `Ctrl-C` and `Ctrl-V`
{% hint style="info" %}
There are a number of useful shortcuts for interacting with the MicroPython REPL. See below for the key combinations;
* `Ctrl-A` on a blank line will enter raw REPL mode. This is similar to permanent paste mode, except that characters are not echoed back.
* `Ctrl-B` on a blank like goes to normal REPL mode.
* `Ctrl-C` cancels any input, or interrupts the currently running code.
* `Ctrl-D` on a blank line will do a soft reset.
* `Ctrl-E` enters ‘paste mode’ that allows you to copy and paste chunks of text. Exit this mode using `Ctrl-D`.
* `Ctrl-F` performs a "safe-boot" of the device that prevents `boot.py` and `main.py` from executing
{% endhint %}

54
getting-started/programming/repl/serial.md
View File

@@ -1,54 +0,0 @@
# Serial USB \(UART\)
To use the REPL, a Pycom device must be connected to the host computer with a USB connection either to an Expansion Board or to serial converter \(a diagram of how to do this can be found the the [getting started](../../introduction.md) page for your module\).
In order to connect to the REPL over USB serial, there are multiple methods. Detailed below are the explanations of how to do it in MacOS, Linux and Windows.
## All platforms
By far the easiest way to access the USB UART REPL is via the our [Pymakr plug-in](../../../pymakr-plugin/installation/) for Atom and Visual Studio Code. This adds a pane to the bottom of the editors that allows you to directly access the REPL and any output from the device. Detailed instructions on how to setup Pymakr can be found [here](../../../pymakr-plugin/installation/).
## macOS and Linux
To open a serial USB connection from macOS, any serial tool may be used; in this example, the terminal tool `screen` will be used.
Open a terminal instance and run the following commands:
```bash
$ screen /dev/tty.usbmodem* 115200
```
Upon exiting `screen`, press `CTRL-A CTRL-\`. If the keyboard does not support the `\`-key \(i.e. an obscure combination for `\` like `ALT-SHIFT-7` is required\), the key combination can be remapped for the `quit` command:
* create `~/.screenrc`
* add bind `q` to the `exit` command
This will allow screen to exited by pressing `CTRL-A Q`.
{% hint style="info" %}
On Linux, `picocom` or `minicom` may be used instead of `screen`. The usb serial address might also be listed as `/dev/ttyUSB01` or a higher increment for `ttyUSB`. Additionally, the elevated permissions to access the device \(e.g. group uucp/dialout or use `sudo`\) may be required.
{% endhint %}
## Windows
A terminal emulator is needed to open the connection from Windows; the easiest option is to download the free program, [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html).
### COM Port
To use PuTTY the serial port \(COM port\) in which the Pycom device is connected, must be located. In Windows, this information can be found from the 'Device Manager' program.
1. Open the Windows start menu and search for 'Device Manager'
2. The COM port for the Pycom device will be listed as 'USB Serial Device' or a similar name
3. Copy/Write down the associated COM port \(e.g. `COM4`\)
### Using Putty
1. With PuTTY open, click on `Session` in the left-hand panel
2. Next click the `Serial` radio button on the right and enter the associated
COM port \(e.g. `COM4`\) in the `Serial Line` box
3. Finally, click the `Open` button
![](../../../.gitbook/assets/putty.png)

41
getting-started/programming/repl/telnet.md
View File

@@ -1,41 +0,0 @@
# Telnet REPL
Pycom devices also support a connection via `telnet`, using the device's on board WiFi/WLAN. Connect to the device's WiFi Access Point \(AP\) and using the following credentials to connect to the AP. The WiFi `SSID` will appear upon powering on a Pycom Device for the first time \(e.g. `lopy-`\). To re-enable this feature at a later date, please see [network.WLAN](../../../firmware-and-api-reference/pycom/network/wlan.md).
* password: `www.pycom.io`
## Telnet Server
Additionally, to use the MircoPython REPL over telnet, further authentication is required. The default credentials for the telnet server are:
* username: `micro`
* password: `python`
See [network.server](../../../firmware-and-api-reference/pycom/network/server.md) for info on how to change the default authentication.
## All platforms
By far the easiest way to access the Telnet REPL is via the our [Pymakr plug-in](../../../pymakr-plugin/installation/) for Atom and Visual Studio Code. This adds a pane to the bottom of the editors that allows you to directly access the REPL and any output from the device. Detailed instructions on how to setup Pymakr can be found [here](../../../pymakr-plugin/installation/).
## macOS and Linux
Once the host machine is connected to the Pycom device's Access Point, a telnet connection may be opened from a terminal instance.
```bash
$ telnet 192.168.4.1
```
Upon connection, the telnet program will prompt for the `username` and `password` in the section above.
## Windows
A terminal emulator is needed to open a telnet connection from Windows; the easiest option is to download the free program, [PuTTY](http://www.putty.org/).
1. With PuTTY open, select telnet as connection type and leave the default port \(`23`\)
2. Next enter the IP address of the Pycom device \(e.g. `192.168.4.1`\)
3. Finally click `Open`
{% hint style="info" %}
When using a Pycom device with a personal, home or office WiFi access point, the telnet connection may still be used. In this instance, the user will need to determine the Pycom device's local IP address and substitute this for `192.168.4.1`, referred to in the earlier sections.
{% endhint %}

53
getting-started/programming/safeboot.md
View File

@@ -1,53 +0,0 @@
# Safe boot
If powering up normally or upon pressing the reset button, a Pycom module will boot into standard mode; the `boot.py` file will be executed first, followed by `main.py`. It is possible to alter the boot procedure of the module by tying certain pins `high` or `low` when the module boots.
## Bootloader
If you updated your device before using it, you have already put the device into bootloader mode. This is achieved by connecting `G23` to `GND` while the device boots. If you used a Pysense/Pytrack to update, it did this automatically for you. You only need to put your Pycom module into bootloader mode if you are updating its firmware, or are programming your own low level code. This is not required if you are updating your MicroPython code.
## Safe Boot
Some times the code you have written will prevent you gaining access to the REPL or prevent you updating your code. Some example may be:
* You disabled the WiFi/UART
* Your code gets stuck before reaching the REPL
* You set a socket as blocking but never receive any data
In order to fix this you can safe boot your module. This will prevent `boot.py` and `main.py` from being executed and will drop you straight into the interactive REPL. After reset, if `P12` pin is held `high` \(i.e. connect it to the `3V3` output pin\), the heartbeat LED will begin flashing orange slowly. If after 3 seconds the pin is still held high, the LED will start blinking faster. In this mode the module will do the same as previously explained but it will also select the previous OTA image to boot if you have updated the module via the OTA update procedure \(updates performed via the firmware update tool do not count\). This is useful if you flashed a OTA update that breaks the device.
Pin `P12` released during:
| 1st 3 secs window | 2nd 3 secs window |
| :--- | :--- |
| Disable `boot.py` and `main.py` | Same as previous but using previous OTA firmware |
The selection made during safe boot is not persistent, therefore after the next normal reset, the latest firmware will proceed to run again.
If problems occur within the filesystem or you wish to factory reset your module to remove your code, run following code in the REPL:
```python
>>> import os
>>> os.mkfs('/flash')
```
{% hint style="danger" %}
Be aware, resetting the flash filesystem will delete all files inside the internal device storage \(not the SD card\) and they cannot be recovered.
{% endhint %}
## Reset
Pycom devices support both soft and hard resets. A soft reset clears the state of the MicroPython virtual machine but leaves hardware peripherals unaffected. To do a soft reset, press `Ctrl+D` on the REPL or from within a script, run:
```python
>>> import sys
>>> sys.exit()
```
A hard reset is the same as performing a power cycle to the device. In order to hard reset the device, press the `reset` switch or run:
```python
>>> import machine
>>> machine.reset()
```

16
getting-started/registration/README.md
View File

@@ -1,16 +0,0 @@
# Device Registration
Some of our devices require registration before you can utilise specific features such as certain types of networking. Please see the list below for setup guides to ensure that your device is registered and activated on the various platforms required to access all of the available features.
[![](../../.gitbook/assets/sigfox-logo.png)](sigfox.md)
[![](../../.gitbook/assets/lorawan_logo.png)](lora/)
[![](../../.gitbook/assets/image.png)](cellular.md)
[![](../../.gitbook/assets/image-1.png)](cellular.md)
{% hint style="info" %}
**Not all Pycom devices require activation**; most features work immediately out of the box!
{% endhint %}

12
getting-started/registration/cellular.md
View File

@@ -1,12 +0,0 @@
# Cellular
In order to use your GPy/FiPy on a cellular network you are required to get a SIM card from a local provider.
_Note: This might differ from a standard SIM you can buy in a store, our devices do not support standard LTE._
Currently we are not able to provide any specific details about how to get such a SIM card and how to register it as most deployments are closed trials, each carrier has it’s own rules \(for example, whether they require special SIMs or not\).
We recommend contacting your local cellular providers to check their plans surrounding LTE CAT-M1 and NB-IoT. By contacting them, you will show the carriers that there is local interest in deploying such networks.
You can find a map of deployed networks and open labs [here](https://www.gsma.com/iot/deployment-map/#deployments).

42
getting-started/registration/lora/README.md
View File

@@ -1,42 +0,0 @@
# LoRaWAN
## Raw LoRa
When using raw LoRa, you do not have to register your module in any way. The modules can talk to each other directly.
## LoRaWAN
In order to connect your LoRa capable Pycom module to a LoRaWAN network you will have to register your device with the desired network. We are unable to provide instructions for all LoRaWAN networks but below you will find some generic instructions, along with links to any specific guides we are aware of.
### Generic instructions
Firstly you will need to get your modules `Device EUI`, this can be achieved using the following code:
```python
from network import LoRa
import ubinascii
lora = LoRa(mode=LoRa.LORAWAN)
print(ubinascii.hexlify(lora.mac()).upper().decode('utf-8'))
```
The output will be a hex string like: `70B3D5499585FCA1`. Once you have this you will need to provide it to your LoRaWAN network which will then provide you with the details need to connect via Over-the-Air Activation \(OTAA\) or Activation by Personalisation \(ABP\)
#### OTAA
If you wish to connect via OTAA \(which is the recommended method\) the network will provide you with an `Application EUI` and `Application Key`. The former identifies what application your device is connecting to, the latter is a shared secret key unique to your device to generate the session keys that prove its identity to the network. Once you have these you can use the [LoRaWAN OTAA example](../../../tutorials-and-examples/lora/lorawan-otaa.md) code to connect to the network.
#### ABP
With ABP the encryption keys enabling communication with the network are preconfigured in the device. The network will need to provide you with a `Device Address`, `Network Session Key` and `Application Session Key`. Once you have these you can use the [LoRaWAN ABP example](../../../tutorials-and-examples/lora/lorawan-abp.md) code to connect to the network.
### Networks
[![](../../../.gitbook/assets/ttn-logo.png)](ttn.md)
[![](../../../.gitbook/assets/senet-logo-2.png)](senet.md)
{% hint style="info" %}
If you cannot find your favourite LoRaWAN network in the list above, please consider writing a tutorial for how to connect a Pycom module with it and contribute it to this documentation via a [GitHub pull request](https://github.com/pycom/pycom-documentation).
{% endhint %}

76
getting-started/registration/lora/senet.md
View File

@@ -1,76 +0,0 @@
# Senet
![](../../../.gitbook/assets/senet-logo.png)
## The Senet Developer Portal
Connecting your device begins by creating an account on the Senet Developer Portal. This will grant you free access for up to 10 devices and 5 gateways to support application development activities. [Sign-Up](https://portal.senetco.io/)
Complete Senet Developer Portal documentation is available on line at [Docs](https://docs.senetco.io/docs).
Once your account has been activated, you may want to onboard a gateway, if Senet public network access in unavailable. Onboarding your device consists of registering the device through your portal account and then provisioning your device with the information provided at the completion of the registration process. Senet supports both Over-The-Air-Activation \(OTAA\) and Activation-By-Personalization \(ABP\). As ABP is useful only in a very narrow set of use-cases, this tutorial will walk you through OTAA registration and provisioning.
## Device Identity and Security Elements
All LoRaWAN 1.0.x end-devices require three provisioning elements to join a network. Devices typically come from the factory with a unique, 64-bit EUI \(called a DevEUI\) which is the device's globally unique identifier. In the case of the Senet Developer Portal, the two additional elements \(The Application EUI or AppEUI and Application Key or AppKey\) will be generated and provided to you after registration \(in typical production environments, these additional elements are also provided during manufacturing and provisioned into the network backend\).
* Device EUI \(DevEUI\)
* Application EUI \(AppEUI\)
* Application Key \(AppKey\)
### Device EUI
This comes from the device itself and can be obtained from `lora.mac()`.
To obtain the required hexadecimal representation you can run the following code on your LoPy:
```python
from network import LoRa
import ubinascii
lora = LoRa()
print("DevEUI: %s" % (ubinascii.hexlify(lora.mac()).decode('ascii')))
```
Use this value during the first step of device registration.
![](../../../.gitbook/assets/senet-register.png)
### Application EUI and Application Key
The Application EUI uniquely identifies the security broker \(called a Join Server in LoRaWAN terminology\) which is interogated by the network when the device attempts to join the network. The Application Key is the shared secret \(between the end-device and the Join-Server\) which forms the basis for LoRaWAN security and is used to generate the application and network session keys used for privacy and message integrity.
At the completion of your device registration process on the Senet Developer Portal, you will be presented with the Application EUI and the Application Key which you will need to provision in your device. This information is always available after the fact in the device details screen.
![](../../../.gitbook/assets/senet-register-complete.png)
## Provisioning the LoPy or FiPy
After device registration is complete, configure the device for optimal operation and provision the AppEUI and AppKey.
```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.US915)
# create an OTAA authentication parameters
app_eui = ubinascii.unhexlify('00250C0000010001')
app_key = ubinascii.unhexlify('00112233445566778899AABBCCDDEEFF')
# initialize LoRa
lora.init(mode=LoRa.LORAWAN, adr=True, public=True)
# join a network using OTAA (Over the Air Activation)
lora.join(activation=LoRa.OTAA, auth=(app_eui, app_key), dr=0, timeout=0)
```
You are now ready to start sending messages from your device! Each device may be provisioned to stream the datagrams to the backend service of your choice in a variety of standard and custom formats.

78
getting-started/registration/lora/ttn.md
View File

@@ -1,78 +0,0 @@
# The Things Network
In order to use The Things Network \(TTN\) you should navigate to their website and create/register an account. Enter a username and an email address to verify with their platform.
![](../../../.gitbook/assets/ttn-1.png)
Once an account has been registered, you can register your Pycom module as either a node or a nano-gateway. The steps below will detail how to do this.
## Create an application
In order to register your device to connect to the things network, you must first create an application for these devices to belong to. This way the Network will know where to send the devices data to.
Selecting the `Applications` tab at the top of the TTN console, will bring up a screen for registering applications. Click register and a new page, similar to the one below, will open.
![](../../../.gitbook/assets/ttn-5.png)
Enter a unique `Application ID` as well as a Description & Handler Registration.
Now the Pycom module nodes can be registered to send data up to the new Application.
## Register a Device
To connect nodes to a things network gateway, devices need to be added to the application. To do this, navigate to the `Devices` tab on the `Application` home page and click the `Register Device` button.
![](../../../.gitbook/assets/ttn-6.png)
In the `Register Device` panel, complete the forms for the `Device ID` and the `Device EUI`. The `Device ID` is user specified and is unique to the device in this application. The `Device EUI` should be a globally unique identifier for the device. You can run the following on you Pycom module to retrieve its EUI.
```python
from network import LoRa
import ubinascii
lora = LoRa()
print("DevEUI: %s" % (ubinascii.hexlify(lora.mac()).decode('ascii')))
```
Once the device has been added, change the `Activation Method` between `OTAA` and `ABP` depending on user preference. This option can be found under the `Settings` tab.
## Register a Nano-Gateway
You can also setup your Pycom module to act as a gateway with The Things Network. The code required to do this can be found [here](../../../tutorials-and-examples/lora/lorawan-nano-gateway.md).
Inside the TTN Console, there are two options, `Applications` and `Gateways`. Select `Gateways` and then click on `register Gateway`. This will allow for the set up and registration of a new nano-gateway.
![](../../../.gitbook/assets/ttn-2%20%281%29.png)
On the Register Gateway page, you will need to set the following settings:
![](../../../.gitbook/assets/ttn-gatewayreg-11-2017-2.jpg)
These are unique to each gateway, location and country specific frequency. Please verify that correct settings are selected otherwise the gateway will not connect to TTN.
**You need to tick the "I'm using the legacy packet forwarder" to enable the right settings.** This is because the Nano-Gateway uses the 'de facto' standard Semtech UDP protocol.
| Option | Value |
| :--- | :--- |
| Protocol | Packet Forwarder |
| Gateway EUI | User Defined \(must match `config.py`\) |
| Description | User Defined |
| Frequency Plan | Select Country \(e.g. EU - 868 MHz\) |
| Location | User Defined |
| Antenna Placement | Indoor or Outdoor |
Most LoRaWAN network servers expect a Gateway ID in the form of a unique 64-bit hexadecimal number \(called a EUI-64\). The recommended practice is to produce this ID from your board by expanding the WiFi MAC address \(a 48-bit number, called MAC-48\). You can obtain that by running this code prior to configuration:
```python
from network import WLAN
import binascii
wl = WLAN()
binascii.hexlify(wl.mac())[:6] + 'FFFE' + binascii.hexlify(wl.mac())[6:]
```
Once these settings have been applied, click `Register Gateway`. A Gateway Overview page will appear, with the configuration settings showing. Next click on the `Gateway Settings` and configure the Router address to match that of the gateway \(default: `router.eu.thethings.network`\).
![](../../../.gitbook/assets/ttn-4%20%281%29.png)
The `Gateway` should now be configured.

70
getting-started/registration/sigfox.md
View File

@@ -1,70 +0,0 @@
# Sigfox
Before you start, update your device to the latest firmware. Select _stable_ firmware in Firmware updater. After firmware update is done, _Sigfox ID_ and _Sigfox PAC_ were assigned to your device.
Copy _Sigfox ID_ and _Sigfox PAC_ from the last screen of firmware updater.
![](../../.gitbook/assets/fwupdater.png)
_Sigfox ID_ and _Sigfox Pac_ is assigned to your device just once during the first update process. _Sigfox ID_ and _Sigfox Pac_ will not change after successive firmware updates.
After first firmware update you can also get your _Sigfox ID_ and _Sigfox PAC_ through a couple of commands via the REPL.
```python
from network import Sigfox
import binascii
# initalise Sigfox for RCZ1 (You may need a different RCZ Region)
sigfox = Sigfox(mode=Sigfox.SIGFOX, rcz=Sigfox.RCZ1)
# print Sigfox Device ID
print(binascii.hexlify(sigfox.id()))
# print Sigfox PAC number
print(binascii.hexlify(sigfox.pac()))
```
## Creating account at Sigfox backend
You need to register to the Sigfox Backend. Navigate to [https://backend.sigfox.com/activate](https://backend.sigfox.com/activate)
![](../../.gitbook/assets/sigfoxactivate%20%281%29.png)
Find the specific country country where the device will be activated. Enter the device's _Sigfox ID_ and _Sigfox PAC_.
You should see green microchip if you entered correct _Sigfox ID_ and _Sigfox PAC_
![](../../.gitbook/assets/sigfoxidpac.png)
Then provide the required information including email address and complete registration.
{% hint style="info" %}
When registering your other devices \(not your first device\), you already have created Sigfox Account before. Be sure you are login with your Sigfox account. In that way all of your devices will be added to same Sigfox Account.
{% endhint %}
![](../../.gitbook/assets/sigfoxregistrationform.png)
After registration, you will receive confirmation email with _password_ to Sigfox backend [https://backend.sigfox.com/auth/login](https://backend.sigfox.com/auth/login)
Use your email and password to login to Sigfox backend.
![](../../.gitbook/assets/sigfoxbackend.png)
If you enter correct credentials then you should be able to login to Sigfox backend.
## Transferring your device to new Sigfox account
You may want to transfer your devices to new Sigfox account.
Once you register your device on Sigfox backend, then your Sigfox PAC was used, and is not valid anymore. You need to get new Sigfox PAC. We don't update Sigfox PAC assigned to your device \(which can be seen on last page of Firmware updater or read from device\).
To get new Sigfox PAC navigate to your device on Sigfox backend. On _device_ click on Sigfox Id of device you want to transfer.
![](../../.gitbook/assets/sigfoxtableid%20%281%29.png)
Now you can see your new Sigfox PAC.
![](../../.gitbook/assets/newsigfoxpac%20%281%29.png)
Once you know your new Sigfox PAC go to [https://backend.sigfox.com/activate](https://backend.sigfox.com/activate) and register device with different account.

98
getting-started/troubleshooting-guide.md
View File

@@ -1,98 +0,0 @@
# Troubleshooting Guide
## How to ask for help
Always provide these details when asking for help. This helps us understand your setup and save time.
* Run `os.uname()` on your module to get the version numbers
* Your module’s type & version \(e.g. FiPy 1.0\)
* Any shields, or devices connected \(e.g. Pytrack, Extension Board 3.0 with “x" sensor\)
* Your Operating System’s version
* Pymakr version
* Atom / VSCode version
* Have you looked at our [documentation](https://docs.pycom.io) and similar issues on the [forum](https://forum.pycom.io)?
## Firmware Update
#### Firmware file has unexpected sha1 checksum.
If you're trying to update to the latest `development` firmware, make sure you use the development release of the Firmware Updater.
#### My module is recognised as the wrong type
Open a support ticket with the details and send us the result of this code:
```python
import machine, binascii
binascii.hexlify(machine.unique_id())
```
## Connecting to the module
#### Module stuck in bootloader mode
Normally, the firmware updater switches back to application mode at the end of an upgrade. If that doesn't happen for some reason, re-plugging the USB cable also puts the device back into application mode.
## Pymakr
Make sure you have the latest version of Pymakr and [Atom](https://atom.io)/[VSCode](https://code.visualstudio.com) installed.
**Synchronising a project results in ‘Failed to allocate memory’ error**
Synchronising takes a bit of memory, so this error can occur when code running on the board already is taking a substantial amount of memory.
**Solution:** use safe boot with [REPL](https://docs.pycom.io/gettingstarted/programming/repl) or [Expansion Board](https://docs.pycom.io/product-info/boards/expansion3) when synchronising
### Atom
**Failed to load package: Cannot find module ‘serialport’**
In some cases, this is caused by the Atom Package Manager \(apm\) using Python 3.x, while `node-gyp` \(used for compiling the `serialport` lib\) needs Python 2.x. To confirm this, `apm —version` can be run to check which Python version apm is using.
**Solution:** Tell the package manager to use python 2 instead. Running the following command switches apm to 2.7:
```text
echo “python=/usr/bin/python2.7” >> ~/.atom/.apmrc
```
Now reinstall Pymakr or run apm install from the Pymakr package located in `~/.atom/packages/pymakr`
**Could not locate the bindings file**
If the installation of the `serialport` library failed, it reverts back to the precompiled version that is included in the plugin. This is compiled for the latest versions of Atom and loses compatibility with older versions.
**Solution:** upgrade to the latest Atom \(1.19.0 or higher\) or install the previous version of the plugin \(`apm install pymakr@1.0.3`\)
**Any error where the traceback contains \.atom\packages\Pymakr\ with a capital “P”**
This happened after `Pymakr` renamed to `pymakr` \(lowercase\) starting at version 1.2.5, but Atom remembers the old folder name inside the packages folder.
**Solution:**
* Uninstall Pymakr
* Remove folder: `~/.atom/.apm/Pymkr`
* Empty folder: `~/.config/Atom/Cache`
* Reinstall pymakr
**Cannot connect to Pycom board via REPL**
In the case of a board that has already has code uploaded to it and is running a loop/non-exiting script, the board may not boot into a REPL.
**Solution:** If the board is currently running code, you will need to exit the current script before proceeding: 1. Ensure your board is connected to your computer 2. Press the reset button on the device 3. Press `ctrl-c` on within the Pymakr console to exit the current script/program
The REPL should then appear with the `>>>` prompt and you will be able to run/sync your code.
**Cannot connect to Pycom on Linux**
If you’re a Linux user and can’t connect to your board, there might be a permission issue to access the serial port.
**Solution:** Run the following command `sudo usermod -a -G dialout $USER`
### VSCode
**Terminal not opening**
If the Pymakr terminal is not opening or giving an error, this might be because NodeJS is not installed on your system. This is because the terminal process is running separate from VSCode and depends on your systems NodeJS install.
**Solution:** install NodeJS. For Windows 64 machines, install a 32 bit version of NodeJS \(for example `nvm install 7.8.0 32` when using `nvm`\).

16
product-info-datasheets/boards/README.md
View File

@@ -1,16 +0,0 @@
# Expansion Boards and Shields
This section contains all of the datasheets for the Pycom Expansion Boards and Shields. This includes the Expansion Board, Pytrack, Pysense and Deep Sleep Shield.
{% page-ref page="expansion3.md" %}
{% page-ref page="pytrack.md" %}
{% page-ref page="pysense.md" %}
{% page-ref page="pyscan.md" %}
{% page-ref page="expansion2.md" %}
{% page-ref page="deepsleep/" %}

20
product-info-datasheets/boards/deepsleep/README.md
View File

@@ -1,20 +0,0 @@
# Deep Sleep Shield
The schematic of the Deep Sleep Shield is available as a PDF File.
{% file src="../../../.gitbook/assets/deepsleep-schematic.pdf" caption="Deep Sleep Schematic" %}
## Pinout
The pinout of the Deep Sleep Shield is available as a PDF File
{% file src="../../../.gitbook/assets/deepsleep-pinout.pdf" caption="Deep Sleep Pinout" %}
![](../../../.gitbook/assets/deepsleep-pinout%20%281%29.png)
{% hint style="info" %}
To correctly connect a WiPy 2.0, LoPy or SiPy to the Deep Sleep Shield, align the white triangle on the Shield with the LED of the Pycom Device. Once the Pycom Device is seated onto the Deep Sleep Shield, this can then be connected to the Expansion Board
{% endhint %}
![](../../../.gitbook/assets/deepsleep-image-1.jpg)

95
product-info-datasheets/boards/deepsleep/api.md
View File

@@ -1,95 +0,0 @@
# Deep Sleep API
This chapter describes the library which controls the Deep Sleep Shield. This includes the controls for external interrupts and timer setup of the deep sleep functionality.
To use this library, please upload the associated [Deep Sleep Library](https://github.com/pycom/pycom-libraries/tree/master/deepsleep) to `/lib` on the target Pycom device.
## Quick Example
```python
from deepsleep import DeepSleep
import deepsleep
ds = DeepSleep()
# get the wake reason and the value of the pins during wake up
wake_s = ds.get_wake_status()
print(wake_s)
if wake_s['wake'] == deepsleep.PIN_WAKE:
print("Pin wake up")
elif wake_s['wake'] == deepsleep.TIMER_WAKE:
print("Timer wake up")
else: # deepsleep.POWER_ON_WAKE:
print("Power ON reset")
ds.enable_pullups('P17') # can also do ds.enable_pullups(['P17', 'P18'])
ds.enable_wake_on_fall('P17') # can also do ds.enable_wake_on_fall(['P17', 'P18'])
ds.go_to_sleep(60) # go to sleep for 60 seconds
```
## DeepSleep
The Deep Sleep Shield allows for waking up via a user trigger and also via an external interrupt \(i.e. Accelerometer, Button\).
### Constructors
#### class DeepSleep\(\)
Creates a DeepSleep object, that will control the board's sleep features. For example;
```python
ds = DeepSleep()
```
### Methods
#### deepsleep.enable\_auto\_poweroff\(\)
This method allows for a critical battery voltage to be set. For example, if the external power source \(e.g. LiPo Cell\) falls below `3.3V`, turn off the Pycom device. This is intended to protect the hardware from under voltage.
#### deepsleep.enable\_pullups\(pins\)
This method allows for pull-up pins to be enabled. For example, if an external trigger occurs, wake the Pycom device from Deep Sleep. `pins` may be passed into the method as a list, i.e. `['P17', 'P18']`.
#### deepsleep.disable\_pullups\(pins\)
This method allows for pull-up pins to be disabled. For example, if an external trigger occurs, wake the Pycom device from Deep Sleep. `pins` may be passed into the method as a list, i.e. `['P17', 'P18']`.
#### deepsleep.enable\_wake\_on\_raise\(pins\)
This method allows for pull-up pins to trigger on a rising voltage. For example, if an external rising voltage triggers occurs, wake the Pycom device from Deep Sleep. `pins` may be passed into the method as a list, i.e. `['P17', 'P18']`.
#### deepsleep.disable\_wake\_on\_raise\(pins\)
This method allows for disabling pull-up pins that trigger on a rising voltage. `pins` may be passed into the method as a list, i.e. `['P17', 'P18']`.
#### deepsleep.enable\_wake\_on\_fall\(pins\)
This method allows for pull-up pins to trigger on a falling voltage. For example, if an external falling voltage triggers occurs, wake the Pycom device from Deep Sleep. `pins` may be passed into the method as a list, i.e. `['P17', 'P18']`.
#### deepsleep.disable\_wake\_on\_fall\(pins\)
This method allows for disabling pull-up pins that trigger on a falling voltage. `pins` may be passed into the method as a list, i.e. `['P17', 'P18']`.
#### deepsleep.get\_wake\_status\(\)
This method returns the status of the pins at wakeup from deep sleep. The method returns a `dict` with the states of `wake`, `P10`, `P17`, `P18`.
#### deepsleep.set\_min\_voltage\_limit\(value\)
This method relates to the `enable_auto_poweroff` method and allows the user to specify the minimum power off voltage as a value.
#### deepsleep.go\_to\_sleep\(seconds\)
This method sends the board into deep sleep for a period of `seconds` or until an external interrupt has triggered \(see `set_pullups`\).
#### deepsleep.hw\_reset\(\)
This method resets the PIC controller and resets it to the state previous to the pins/min-voltage being set.
{% hint style="info" %}
Please note that more functionality is being added weekly to these libraries. If a required feature is not available, feel free to contribute with a pull request at the [Pycom Libraries](https://github.com/pycom/pycom-libraries) GitHub repository.
{% endhint %}

28
product-info-datasheets/boards/expansion2.md
View File

@@ -1,28 +0,0 @@
# Expansion Board 2.0
![](../../.gitbook/assets/assets-lil0igdl11z7jos_jpx-lkn7scqkkkb6tqb3uyo-lkn86jsexys_ho7ct7c-expansion2.png)
## Datasheet
The datasheet of the Expansion Board is available as a PDF File.
{% file src="../../.gitbook/assets/expansion2-specsheet.pdf" caption="Expansion Board 2 Datasheet" %}
## Pinout
The pinout of the Expansion Board is available as a PDF File
{% file src="../../.gitbook/assets/expansion2-pinout.pdf" caption="Expansion Board 2 Pinout" %}
![](../../.gitbook/assets/expansion2-pinout-1.png)
{% hint style="danger" %}
Be gentle when plugging/unplugging from the USB connector. Whilst the USB connector is soldered and is relatively strong, if it breaks off it can be very difficult to fix.
{% endhint %}
## Battery Charger
The Expansion Board features a single cell Li-Ion/Li-Po charger. When the board is being powered via the micro USB connector, the Expansion Board will charge the battery \(if connected\). When the `CHG` jumper is present the battery will be charged at `450mA`. If this value is too high for your application, removing the jumper lowers the charge current to `100mA`.

48
product-info-datasheets/boards/expansion3.md
View File

@@ -1,48 +0,0 @@
# Expansion Board 3.0
## ![](../../.gitbook/assets/assets-lil0igdl11z7jos_jpx-lkn7scqkkkb6tqb3uyo-lkn82uldmpus0lnq1kx-expansion3.png)
## Datasheet
The datasheet of the Expansion Board is available as a PDF File.
{% file src="../../.gitbook/assets/expansion3-specsheet-1.pdf" caption="Expansion Board 3 Datasheet" %}
## Pinout
The pinout of the Expansion Board is available as a PDF File
{% file src="../../.gitbook/assets/expansion3-pinout.pdf" caption="Expansion Board 3 Pinout" %}
![](../../.gitbook/assets/expansion3-pinout-1.png)
{% hint style="danger" %}
Be gentle when plugging/unplugging from the USB connector. Whilst the USB connector is soldered and is relatively strong, if it breaks off it can be very difficult to fix.
{% endhint %}
## Battery Charger
The Expansion Board features a single cell Li-Ion/Li-Po charger. When the board is being powered via the micro USB connector, the Expansion Board will charge the battery \(if connected\). When the `CHG` jumper is present the battery will be charged at `450mA`. If this value is too high for your application, removing the jumper lowers the charge current to `100mA`.
{% hint style="info" %}
To use the battery, pull `P8/G15` high \(connect to `3v3`\). If you want to use the SD card as well, use a 10k pull-up.
{% endhint %}
## Differences between v2.0 and v3.0
* The FTDI chip as been replaced with a custom programmed PIC like on the
Pysense/Pytrack/Pyscan boards. This allows our firmware update tool to
automatically put the module into bootloader mode.
* Added a "Safe boot" button to enter safe boot easier. This button connects
`P12` to `3.3v` and if pressed and held while the reset button is pressed on
a Pycom module, the module will enter safe boot.
## Troubleshooting
* If PIC stays in bootloader mode, the [`dfu-util` update](../../pytrack-pysense-pyscan/installation/firmware.md) should be performed

47
product-info-datasheets/boards/pyscan.md
View File

@@ -1,47 +0,0 @@
# Pyscan
![](../../.gitbook/assets/assets-lil0igdl11z7jos_jpx-lkn7scqkkkb6tqb3uyo-lkn83hfia61dsuyojco-pyscan-new.png)
## Datasheet
The datasheet of the Pyscan is available as a PDF File.
{% file src="../../.gitbook/assets/pyscan-specsheet.pdf" caption="Pyscan Datasheet" %}
## Pyscan Libraries
* Pyscan libraries to use the RFID/NFC reader are located [here](https://github.com/pycom/pycom-libraries/tree/master/pyscan)
* The accelerometer library is [here](https://github.com/pycom/pycom-libraries/blob/master/pytrack/lib/LIS2HH12.py)
{% hint style="info" %}
For the time being, we recommend to upload the `MFRC630.mpy` file via FTP due to current limitations of Pymakr that will be fixed shortly.
{% endhint %}
Libraries for the rest of the components will be added soon.
## Pyscan components:
* **Accelerometer**: ST LIS2HH12
* **Ambient light sensor**: Lite-on LTR-329ALS-01
* **RFID/NFC reader**: NXP MFRC63002HN, 151
## Driver
The Windows 7 driver for Pyscan is located [here](../../pytrack-pysense-pyscan/installation/firmware.md).
For other Operating Systems there's no driver required.
## Pinout
The pinout of the Pyscan is available as a PDF File
{% file src="../../.gitbook/assets/pyscan-pinout.pdf" caption="Pyscan Pinout" %}
![](../../.gitbook/assets/pyscan-pinout-1.png)
## Battery Charger
The board features a single cell Li-Ion/Li-Po charger. When the board is being powered via the micro USB connector, it will charge the battery \(if connected\).

24
product-info-datasheets/boards/pysense.md
View File

@@ -1,24 +0,0 @@
# Pysense
![](../../.gitbook/assets/assets-lil0igdl11z7jos_jpx-lkn7scqkkkb6tqb3uyo-lkn83hclnq-gurt2p_m-pysense.png)
## Datasheet
The datasheet of the Pysense is available as a PDF File.
{% file src="../../.gitbook/assets/pysense-specsheet.pdf" caption="Pysense Datasheet" %}
## Pinout
The pinout of the Pysense is available as a PDF File
{% file src="../../.gitbook/assets/pysense-pinout.pdf" caption="Pysense Pinout" %}
![](../../.gitbook/assets/pysense-pinout-1.png)
## Battery Charger
The board features a single cell Li-Ion/Li-Po charger. When the board is being powered via the micro USB connector, it will charge the battery \(if connected\).

24
product-info-datasheets/boards/pytrack.md
View File

@@ -1,24 +0,0 @@
# Pytrack
![](../../.gitbook/assets/assets-lil0igdl11z7jos_jpx-lkn7scqkkkb6tqb3uyo-lkn83ejihh1jeasccad-pytrack.png)
## Datasheet
The datasheet of the Pytrack is available as a PDF File.
{% file src="../../.gitbook/assets/pytrack-specsheet-1.pdf" caption="Pytrack Datasheet" %}
## Pinout
The pinout of the Pytrack is available as a PDF File
{% file src="../../.gitbook/assets/pytrack-pinout.pdf" caption="Pytrack Pinout" %}
![](../../.gitbook/assets/pytrack-pinout-1.png)
## Battery Charger
The board features a single cell Li-Ion/Li-Po charger. When the board is being powered via the micro USB connector, it will charge the battery \(if connected\).

18
product-info-datasheets/development/README.md
View File

@@ -1,18 +0,0 @@
# Development Modules
This section contains all of the datasheets for the Pycom Development Devices. This includes the WiPy 2.0 and 3.0, LoPy, LoPy 4, SiPy, GPy, and FiPy.
{% page-ref page="wipy2.md" %}
{% page-ref page="wipy3.md" %}
{% page-ref page="lopy.md" %}
{% page-ref page="lopy4.md" %}
{% page-ref page="sipy.md" %}
{% page-ref page="gpy.md" %}
{% page-ref page="fipy.md" %}

Some files were not shown because too many files have changed in this diff Show More