From 25b2c660b06a26f9f9ab8dc2699fed8bc5c17bdb Mon Sep 17 00:00:00 2001 From: Emmanuel Florent Date: Wed, 26 Jun 2019 10:36:06 +0200 Subject: [PATCH] manual rework --- SUMMARY.md | 215 ------- advanced-topics/cli.md | 361 ------------ advanced-topics/downgrade.md | 39 -- advanced-topics/encryption.md | 103 ---- documentation-notes/introduction.md | 4 - documentation-notes/mesh-networks.md | 4 - documentation-notes/replscript.md | 34 -- documentation-notes/syntax.md | 95 --- documents/certificates.md | 104 ---- documents/license.md | 16 - firmware-and-api-reference/introduction.md | 15 - .../micropython/README.md | 10 - .../micropython/_thread.md | 86 --- .../micropython/array.md | 22 - .../micropython/builtin.md | 126 ---- .../micropython/cmath.md | 47 -- firmware-and-api-reference/micropython/gc.md | 24 - .../micropython/math.md | 163 ------ .../micropython/micropython.md | 59 -- .../micropython/select.md | 49 -- firmware-and-api-reference/micropython/sys.md | 62 -- .../micropython/ubinascii.md | 28 - .../micropython/ucrypto.md | 22 - .../micropython/uctypes.md | 138 ----- .../micropython/uhashlib.md | 44 -- .../micropython/ujson.md | 18 - firmware-and-api-reference/micropython/uos.md | 101 ---- firmware-and-api-reference/micropython/ure.md | 57 -- .../micropython/usocket.md | 166 ------ .../micropython/ussl.md | 40 -- .../micropython/ustruct.md | 30 - .../micropython/utime.md | 87 --- firmware-and-api-reference/notes.md | 16 - firmware-and-api-reference/pycom/README.md | 4 - firmware-and-api-reference/pycom/aes.md | 62 -- .../pycom/machine/README.md | 106 ---- .../pycom/machine/adc.md | 100 ---- .../pycom/machine/can.md | 132 ----- .../pycom/machine/dac.md | 46 -- .../pycom/machine/i2c.md | 128 ---- .../pycom/machine/pin.md | 155 ----- .../pycom/machine/pwm.md | 34 -- .../pycom/machine/rmt.md | 134 ----- .../pycom/machine/rtc.md | 79 --- .../pycom/machine/sd.md | 53 -- .../pycom/machine/spi.md | 87 --- .../pycom/machine/timer.md | 127 ---- .../pycom/machine/uart.md | 135 ----- .../pycom/machine/wdt.md | 28 - .../pycom/network/README.md | 4 - .../pycom/network/bluetooth/README.md | 253 -------- .../pycom/network/bluetooth/gatt.md | 8 - .../network/bluetooth/gattccharacteristic.md | 44 -- .../network/bluetooth/gattcconnection.md | 51 -- .../pycom/network/bluetooth/gattccservice.md | 24 - .../network/bluetooth/gattscharacteristic.md | 83 --- .../pycom/network/bluetooth/gattsservice.md | 31 - .../pycom/network/lora.md | 486 ---------------- .../pycom/network/lte.md | 188 ------ .../pycom/network/server.md | 50 -- .../pycom/network/sigfox.md | 279 --------- .../pycom/network/wlan.md | 172 ------ firmware-and-api-reference/pycom/pycom.md | 153 ----- getting-started/connection/README.md | 14 - getting-started/connection/fipy.md | 108 ---- getting-started/connection/gpy.md | 85 --- getting-started/connection/lopy.md | 94 --- getting-started/connection/lopy4.md | 92 --- getting-started/connection/sipy.md | 90 --- getting-started/connection/wipy.md | 84 --- getting-started/installation/README.md | 8 - getting-started/installation/drivers.md | 56 -- getting-started/installation/firmwaretool.md | 56 -- getting-started/installation/pymakr.md | 12 - getting-started/introduction.md | 26 - getting-started/programming/README.md | 16 - getting-started/programming/examples.md | 108 ---- getting-started/programming/first-project.md | 113 ---- getting-started/programming/ftp.md | 41 -- getting-started/programming/micropython.md | 26 - getting-started/programming/repl/README.md | 24 - getting-started/programming/repl/serial.md | 54 -- getting-started/programming/repl/telnet.md | 41 -- getting-started/programming/safeboot.md | 53 -- getting-started/registration/README.md | 16 - getting-started/registration/cellular.md | 12 - getting-started/registration/lora/README.md | 42 -- getting-started/registration/lora/senet.md | 76 --- getting-started/registration/lora/ttn.md | 78 --- getting-started/registration/sigfox.md | 70 --- getting-started/troubleshooting-guide.md | 98 ---- product-info-datasheets/boards/README.md | 16 - .../boards/deepsleep/README.md | 20 - .../boards/deepsleep/api.md | 95 --- product-info-datasheets/boards/expansion2.md | 28 - product-info-datasheets/boards/expansion3.md | 48 -- product-info-datasheets/boards/pyscan.md | 47 -- product-info-datasheets/boards/pysense.md | 24 - product-info-datasheets/boards/pytrack.md | 24 - product-info-datasheets/development/README.md | 18 - product-info-datasheets/development/fipy.md | 60 -- product-info-datasheets/development/gpy.md | 57 -- product-info-datasheets/development/lopy.md | 49 -- product-info-datasheets/development/lopy4.md | 48 -- product-info-datasheets/development/sipy.md | 48 -- product-info-datasheets/development/wipy2.md | 47 -- product-info-datasheets/development/wipy3.md | 52 -- product-info-datasheets/introduction.md | 46 -- product-info-datasheets/notes.md | 26 - product-info-datasheets/oem/README.md | 14 - product-info-datasheets/oem/g01.md | 43 -- product-info-datasheets/oem/l01.md | 37 -- product-info-datasheets/oem/l01_reference.md | 45 -- product-info-datasheets/oem/l04.md | 38 -- .../oem/universal_reference.md | 45 -- product-info-datasheets/oem/w01.md | 35 -- products.md | 78 --- pybytes/connect/flash.md | 69 --- pybytes/connect/sigfox/README.md | 40 -- pybytes/dashboard.md | 131 ----- pymakr-plugin/installation/README.md | 12 - pymakr-plugin/installation/atom.md | 79 --- pymakr-plugin/installation/vscode.md | 91 --- pymakr-plugin/settings.md | 38 -- pymakr-plugin/toolsfeatures.md | 80 --- pytrack-pysense-pyscan/apireference/README.md | 4 - pytrack-pysense-pyscan/apireference/pyscan.md | 145 ----- .../apireference/pysense.md | 106 ---- .../apireference/pytrack.md | 48 -- pytrack-pysense-pyscan/apireference/sleep.md | 103 ---- pytrack-pysense-pyscan/installation/README.md | 4 - .../installation/drivers.md | 46 -- .../installation/firmware.md | 150 ----- .../installation/libraries.md | 40 -- pytrack-pysense-pyscan/introduction.md | 74 --- tutorials-and-examples/all/README.md | 4 - tutorials-and-examples/all/adc.md | 35 -- tutorials-and-examples/all/aws.md | 198 ------- tutorials-and-examples/all/ble.md | 111 ---- tutorials-and-examples/all/https.md | 28 - tutorials-and-examples/all/i2c.md | 94 --- tutorials-and-examples/all/modbus.md | 133 ----- tutorials-and-examples/all/mqtt.md | 43 -- tutorials-and-examples/all/ota-lorawan.md | 5 - tutorials-and-examples/all/ota.md | 207 ------- tutorials-and-examples/all/owd.md | 246 -------- tutorials-and-examples/all/pir.md | 125 ---- tutorials-and-examples/all/repl.md | 45 -- tutorials-and-examples/all/rgbled.md | 33 -- tutorials-and-examples/all/rmt.md | 141 ----- tutorials-and-examples/all/threading.md | 28 - tutorials-and-examples/all/timers.md | 53 -- tutorials-and-examples/all/wlan.md | 144 ----- tutorials-and-examples/introduction.md | 14 - tutorials-and-examples/lora/README.md | 8 - .../lora/lora-mac-nano-gateway.md | 106 ---- tutorials-and-examples/lora/lora-mac.md | 38 -- tutorials-and-examples/lora/lorawan-abp.md | 50 -- .../lora/lorawan-nano-gateway.md | 549 ------------------ tutorials-and-examples/lora/lorawan-otaa.md | 54 -- tutorials-and-examples/lora/module-module.md | 46 -- tutorials-and-examples/lora/rn2483-to-lopy.md | 39 -- tutorials-and-examples/lte/README.md | 6 - tutorials-and-examples/lte/cat-m1.md | 43 -- tutorials-and-examples/lte/firmware.md | 218 ------- tutorials-and-examples/lte/imei.md | 20 - tutorials-and-examples/lte/nb-iot.md | 37 -- tutorials-and-examples/pyscan.md | 58 -- tutorials-and-examples/pysense.md | 23 - tutorials-and-examples/pytrack.md | 50 -- tutorials-and-examples/sigfox.md | 50 -- 171 files changed, 12644 deletions(-) delete mode 100644 SUMMARY.md delete mode 100644 advanced-topics/cli.md delete mode 100644 advanced-topics/downgrade.md delete mode 100644 advanced-topics/encryption.md delete mode 100644 documentation-notes/introduction.md delete mode 100644 documentation-notes/mesh-networks.md delete mode 100644 documentation-notes/replscript.md delete mode 100644 documentation-notes/syntax.md delete mode 100644 documents/certificates.md delete mode 100644 documents/license.md delete mode 100644 firmware-and-api-reference/introduction.md delete mode 100644 firmware-and-api-reference/micropython/README.md delete mode 100644 firmware-and-api-reference/micropython/_thread.md delete mode 100644 firmware-and-api-reference/micropython/array.md delete mode 100644 firmware-and-api-reference/micropython/builtin.md delete mode 100644 firmware-and-api-reference/micropython/cmath.md delete mode 100644 firmware-and-api-reference/micropython/gc.md delete mode 100644 firmware-and-api-reference/micropython/math.md delete mode 100644 firmware-and-api-reference/micropython/micropython.md delete mode 100644 firmware-and-api-reference/micropython/select.md delete mode 100644 firmware-and-api-reference/micropython/sys.md delete mode 100644 firmware-and-api-reference/micropython/ubinascii.md delete mode 100644 firmware-and-api-reference/micropython/ucrypto.md delete mode 100644 firmware-and-api-reference/micropython/uctypes.md delete mode 100644 firmware-and-api-reference/micropython/uhashlib.md delete mode 100644 firmware-and-api-reference/micropython/ujson.md delete mode 100644 firmware-and-api-reference/micropython/uos.md delete mode 100644 firmware-and-api-reference/micropython/ure.md delete mode 100644 firmware-and-api-reference/micropython/usocket.md delete mode 100644 firmware-and-api-reference/micropython/ussl.md delete mode 100644 firmware-and-api-reference/micropython/ustruct.md delete mode 100644 firmware-and-api-reference/micropython/utime.md delete mode 100644 firmware-and-api-reference/notes.md delete mode 100644 firmware-and-api-reference/pycom/README.md delete mode 100644 firmware-and-api-reference/pycom/aes.md delete mode 100644 firmware-and-api-reference/pycom/machine/README.md delete mode 100644 firmware-and-api-reference/pycom/machine/adc.md delete mode 100644 firmware-and-api-reference/pycom/machine/can.md delete mode 100644 firmware-and-api-reference/pycom/machine/dac.md delete mode 100644 firmware-and-api-reference/pycom/machine/i2c.md delete mode 100644 firmware-and-api-reference/pycom/machine/pin.md delete mode 100644 firmware-and-api-reference/pycom/machine/pwm.md delete mode 100644 firmware-and-api-reference/pycom/machine/rmt.md delete mode 100644 firmware-and-api-reference/pycom/machine/rtc.md delete mode 100644 firmware-and-api-reference/pycom/machine/sd.md delete mode 100644 firmware-and-api-reference/pycom/machine/spi.md delete mode 100644 firmware-and-api-reference/pycom/machine/timer.md delete mode 100644 firmware-and-api-reference/pycom/machine/uart.md delete mode 100644 firmware-and-api-reference/pycom/machine/wdt.md delete mode 100644 firmware-and-api-reference/pycom/network/README.md delete mode 100644 firmware-and-api-reference/pycom/network/bluetooth/README.md delete mode 100644 firmware-and-api-reference/pycom/network/bluetooth/gatt.md delete mode 100644 firmware-and-api-reference/pycom/network/bluetooth/gattccharacteristic.md delete mode 100644 firmware-and-api-reference/pycom/network/bluetooth/gattcconnection.md delete mode 100644 firmware-and-api-reference/pycom/network/bluetooth/gattccservice.md delete mode 100644 firmware-and-api-reference/pycom/network/bluetooth/gattscharacteristic.md delete mode 100644 firmware-and-api-reference/pycom/network/bluetooth/gattsservice.md delete mode 100644 firmware-and-api-reference/pycom/network/lora.md delete mode 100644 firmware-and-api-reference/pycom/network/lte.md delete mode 100644 firmware-and-api-reference/pycom/network/server.md delete mode 100644 firmware-and-api-reference/pycom/network/sigfox.md delete mode 100644 firmware-and-api-reference/pycom/network/wlan.md delete mode 100644 firmware-and-api-reference/pycom/pycom.md delete mode 100644 getting-started/connection/README.md delete mode 100644 getting-started/connection/fipy.md delete mode 100644 getting-started/connection/gpy.md delete mode 100644 getting-started/connection/lopy.md delete mode 100644 getting-started/connection/lopy4.md delete mode 100644 getting-started/connection/sipy.md delete mode 100644 getting-started/connection/wipy.md delete mode 100644 getting-started/installation/README.md delete mode 100644 getting-started/installation/drivers.md delete mode 100644 getting-started/installation/firmwaretool.md delete mode 100644 getting-started/installation/pymakr.md delete mode 100644 getting-started/introduction.md delete mode 100644 getting-started/programming/README.md delete mode 100644 getting-started/programming/examples.md delete mode 100644 getting-started/programming/first-project.md delete mode 100644 getting-started/programming/ftp.md delete mode 100644 getting-started/programming/micropython.md delete mode 100644 getting-started/programming/repl/README.md delete mode 100644 getting-started/programming/repl/serial.md delete mode 100644 getting-started/programming/repl/telnet.md delete mode 100644 getting-started/programming/safeboot.md delete mode 100644 getting-started/registration/README.md delete mode 100644 getting-started/registration/cellular.md delete mode 100644 getting-started/registration/lora/README.md delete mode 100644 getting-started/registration/lora/senet.md delete mode 100644 getting-started/registration/lora/ttn.md delete mode 100644 getting-started/registration/sigfox.md delete mode 100644 getting-started/troubleshooting-guide.md delete mode 100644 product-info-datasheets/boards/README.md delete mode 100644 product-info-datasheets/boards/deepsleep/README.md delete mode 100644 product-info-datasheets/boards/deepsleep/api.md delete mode 100644 product-info-datasheets/boards/expansion2.md delete mode 100644 product-info-datasheets/boards/expansion3.md delete mode 100644 product-info-datasheets/boards/pyscan.md delete mode 100644 product-info-datasheets/boards/pysense.md delete mode 100644 product-info-datasheets/boards/pytrack.md delete mode 100644 product-info-datasheets/development/README.md delete mode 100644 product-info-datasheets/development/fipy.md delete mode 100644 product-info-datasheets/development/gpy.md delete mode 100644 product-info-datasheets/development/lopy.md delete mode 100644 product-info-datasheets/development/lopy4.md delete mode 100644 product-info-datasheets/development/sipy.md delete mode 100644 product-info-datasheets/development/wipy2.md delete mode 100644 product-info-datasheets/development/wipy3.md delete mode 100644 product-info-datasheets/introduction.md delete mode 100644 product-info-datasheets/notes.md delete mode 100644 product-info-datasheets/oem/README.md delete mode 100644 product-info-datasheets/oem/g01.md delete mode 100644 product-info-datasheets/oem/l01.md delete mode 100644 product-info-datasheets/oem/l01_reference.md delete mode 100644 product-info-datasheets/oem/l04.md delete mode 100644 product-info-datasheets/oem/universal_reference.md delete mode 100644 product-info-datasheets/oem/w01.md delete mode 100644 products.md delete mode 100644 pybytes/connect/flash.md delete mode 100644 pybytes/connect/sigfox/README.md delete mode 100644 pybytes/dashboard.md delete mode 100644 pymakr-plugin/installation/README.md delete mode 100644 pymakr-plugin/installation/atom.md delete mode 100644 pymakr-plugin/installation/vscode.md delete mode 100644 pymakr-plugin/settings.md delete mode 100644 pymakr-plugin/toolsfeatures.md delete mode 100644 pytrack-pysense-pyscan/apireference/README.md delete mode 100644 pytrack-pysense-pyscan/apireference/pyscan.md delete mode 100644 pytrack-pysense-pyscan/apireference/pysense.md delete mode 100644 pytrack-pysense-pyscan/apireference/pytrack.md delete mode 100644 pytrack-pysense-pyscan/apireference/sleep.md delete mode 100644 pytrack-pysense-pyscan/installation/README.md delete mode 100644 pytrack-pysense-pyscan/installation/drivers.md delete mode 100644 pytrack-pysense-pyscan/installation/firmware.md delete mode 100644 pytrack-pysense-pyscan/installation/libraries.md delete mode 100644 pytrack-pysense-pyscan/introduction.md delete mode 100644 tutorials-and-examples/all/README.md delete mode 100644 tutorials-and-examples/all/adc.md delete mode 100644 tutorials-and-examples/all/aws.md delete mode 100644 tutorials-and-examples/all/ble.md delete mode 100644 tutorials-and-examples/all/https.md delete mode 100644 tutorials-and-examples/all/i2c.md delete mode 100644 tutorials-and-examples/all/modbus.md delete mode 100644 tutorials-and-examples/all/mqtt.md delete mode 100644 tutorials-and-examples/all/ota-lorawan.md delete mode 100644 tutorials-and-examples/all/ota.md delete mode 100644 tutorials-and-examples/all/owd.md delete mode 100644 tutorials-and-examples/all/pir.md delete mode 100644 tutorials-and-examples/all/repl.md delete mode 100644 tutorials-and-examples/all/rgbled.md delete mode 100644 tutorials-and-examples/all/rmt.md delete mode 100644 tutorials-and-examples/all/threading.md delete mode 100644 tutorials-and-examples/all/timers.md delete mode 100644 tutorials-and-examples/all/wlan.md delete mode 100644 tutorials-and-examples/introduction.md delete mode 100644 tutorials-and-examples/lora/README.md delete mode 100644 tutorials-and-examples/lora/lora-mac-nano-gateway.md delete mode 100644 tutorials-and-examples/lora/lora-mac.md delete mode 100644 tutorials-and-examples/lora/lorawan-abp.md delete mode 100644 tutorials-and-examples/lora/lorawan-nano-gateway.md delete mode 100644 tutorials-and-examples/lora/lorawan-otaa.md delete mode 100644 tutorials-and-examples/lora/module-module.md delete mode 100644 tutorials-and-examples/lora/rn2483-to-lopy.md delete mode 100644 tutorials-and-examples/lte/README.md delete mode 100644 tutorials-and-examples/lte/cat-m1.md delete mode 100644 tutorials-and-examples/lte/firmware.md delete mode 100644 tutorials-and-examples/lte/imei.md delete mode 100644 tutorials-and-examples/lte/nb-iot.md delete mode 100644 tutorials-and-examples/pyscan.md delete mode 100644 tutorials-and-examples/pysense.md delete mode 100644 tutorials-and-examples/pytrack.md delete mode 100644 tutorials-and-examples/sigfox.md diff --git a/SUMMARY.md b/SUMMARY.md deleted file mode 100644 index af7909a..0000000 --- a/SUMMARY.md +++ /dev/null @@ -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) - diff --git a/advanced-topics/cli.md b/advanced-topics/cli.md deleted file mode 100644 index e367c85..0000000 --- a/advanced-topics/cli.md +++ /dev/null @@ -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: -.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, `.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, `.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, `.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 -``` - diff --git a/advanced-topics/downgrade.md b/advanced-topics/downgrade.md deleted file mode 100644 index f91ffe1..0000000 --- a/advanced-topics/downgrade.md +++ /dev/null @@ -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 -``` - diff --git a/advanced-topics/encryption.md b/advanced-topics/encryption.md deleted file mode 100644 index da3800a..0000000 --- a/advanced-topics/encryption.md +++ /dev/null @@ -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 %} - diff --git a/documentation-notes/introduction.md b/documentation-notes/introduction.md deleted file mode 100644 index 69449b9..0000000 --- a/documentation-notes/introduction.md +++ /dev/null @@ -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. - diff --git a/documentation-notes/mesh-networks.md b/documentation-notes/mesh-networks.md deleted file mode 100644 index 017f4e7..0000000 --- a/documentation-notes/mesh-networks.md +++ /dev/null @@ -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. - diff --git a/documentation-notes/replscript.md b/documentation-notes/replscript.md deleted file mode 100644 index 2a7591d..0000000 --- a/documentation-notes/replscript.md +++ /dev/null @@ -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) -``` - diff --git a/documentation-notes/syntax.md b/documentation-notes/syntax.md deleted file mode 100644 index 38454ce..0000000 --- a/documentation-notes/syntax.md +++ /dev/null @@ -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 %} - diff --git a/documents/certificates.md b/documents/certificates.md deleted file mode 100644 index 04c0ec7..0000000 --- a/documents/certificates.md +++ /dev/null @@ -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" %} - diff --git a/documents/license.md b/documents/license.md deleted file mode 100644 index 2d64517..0000000 --- a/documents/license.md +++ /dev/null @@ -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) - diff --git a/firmware-and-api-reference/introduction.md b/firmware-and-api-reference/introduction.md deleted file mode 100644 index f065fcc..0000000 --- a/firmware-and-api-reference/introduction.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/micropython/README.md b/firmware-and-api-reference/micropython/README.md deleted file mode 100644 index c84c996..0000000 --- a/firmware-and-api-reference/micropython/README.md +++ /dev/null @@ -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 %} - diff --git a/firmware-and-api-reference/micropython/_thread.md b/firmware-and-api-reference/micropython/_thread.md deleted file mode 100644 index 56edbef..0000000 --- a/firmware-and-api-reference/micropython/_thread.md +++ /dev/null @@ -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") -``` - diff --git a/firmware-and-api-reference/micropython/array.md b/firmware-and-api-reference/micropython/array.md deleted file mode 100644 index 5965fdc..0000000 --- a/firmware-and-api-reference/micropython/array.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/micropython/builtin.md b/firmware-and-api-reference/micropython/builtin.md deleted file mode 100644 index 9314075..0000000 --- a/firmware-and-api-reference/micropython/builtin.md +++ /dev/null @@ -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\(\) - diff --git a/firmware-and-api-reference/micropython/cmath.md b/firmware-and-api-reference/micropython/cmath.md deleted file mode 100644 index 8aa91e3..0000000 --- a/firmware-and-api-reference/micropython/cmath.md +++ /dev/null @@ -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 - diff --git a/firmware-and-api-reference/micropython/gc.md b/firmware-and-api-reference/micropython/gc.md deleted file mode 100644 index 008a2ba..0000000 --- a/firmware-and-api-reference/micropython/gc.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/micropython/math.md b/firmware-and-api-reference/micropython/math.md deleted file mode 100644 index 696594f..0000000 --- a/firmware-and-api-reference/micropython/math.md +++ /dev/null @@ -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 - diff --git a/firmware-and-api-reference/micropython/micropython.md b/firmware-and-api-reference/micropython/micropython.md deleted file mode 100644 index 9aae1ff..0000000 --- a/firmware-and-api-reference/micropython/micropython.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/micropython/select.md b/firmware-and-api-reference/micropython/select.md deleted file mode 100644 index eb2ba32..0000000 --- a/firmware-and-api-reference/micropython/select.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/micropython/sys.md b/firmware-and-api-reference/micropython/sys.md deleted file mode 100644 index 61dae02..0000000 --- a/firmware-and-api-reference/micropython/sys.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/micropython/ubinascii.md b/firmware-and-api-reference/micropython/ubinascii.md deleted file mode 100644 index b492379..0000000 --- a/firmware-and-api-reference/micropython/ubinascii.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/micropython/ucrypto.md b/firmware-and-api-reference/micropython/ucrypto.md deleted file mode 100644 index 79a1f06..0000000 --- a/firmware-and-api-reference/micropython/ucrypto.md +++ /dev/null @@ -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 %} - diff --git a/firmware-and-api-reference/micropython/uctypes.md b/firmware-and-api-reference/micropython/uctypes.md deleted file mode 100644 index 4fe016c..0000000 --- a/firmware-and-api-reference/micropython/uctypes.md +++ /dev/null @@ -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\). - diff --git a/firmware-and-api-reference/micropython/uhashlib.md b/firmware-and-api-reference/micropython/uhashlib.md deleted file mode 100644 index 2aa8904..0000000 --- a/firmware-and-api-reference/micropython/uhashlib.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/micropython/ujson.md b/firmware-and-api-reference/micropython/ujson.md deleted file mode 100644 index baed2e5..0000000 --- a/firmware-and-api-reference/micropython/ujson.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/micropython/uos.md b/firmware-and-api-reference/micropython/uos.md deleted file mode 100644 index 9326867..0000000 --- a/firmware-and-api-reference/micropython/uos.md +++ /dev/null @@ -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 - diff --git a/firmware-and-api-reference/micropython/ure.md b/firmware-and-api-reference/micropython/ure.md deleted file mode 100644 index 6885891..0000000 --- a/firmware-and-api-reference/micropython/ure.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/micropython/usocket.md b/firmware-and-api-reference/micropython/usocket.md deleted file mode 100644 index 1ae5abd..0000000 --- a/firmware-and-api-reference/micropython/usocket.md +++ /dev/null @@ -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') -``` diff --git a/firmware-and-api-reference/micropython/ussl.md b/firmware-and-api-reference/micropython/ussl.md deleted file mode 100644 index 715bbda..0000000 --- a/firmware-and-api-reference/micropython/ussl.md +++ /dev/null @@ -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` - diff --git a/firmware-and-api-reference/micropython/ustruct.md b/firmware-and-api-reference/micropython/ustruct.md deleted file mode 100644 index 4f73e4f..0000000 --- a/firmware-and-api-reference/micropython/ustruct.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/micropython/utime.md b/firmware-and-api-reference/micropython/utime.md deleted file mode 100644 index 6bec364..0000000 --- a/firmware-and-api-reference/micropython/utime.md +++ /dev/null @@ -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 %} - diff --git a/firmware-and-api-reference/notes.md b/firmware-and-api-reference/notes.md deleted file mode 100644 index 23470ae..0000000 --- a/firmware-and-api-reference/notes.md +++ /dev/null @@ -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 %} - diff --git a/firmware-and-api-reference/pycom/README.md b/firmware-and-api-reference/pycom/README.md deleted file mode 100644 index 25d7137..0000000 --- a/firmware-and-api-reference/pycom/README.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/pycom/aes.md b/firmware-and-api-reference/pycom/aes.md deleted file mode 100644 index 633b023..0000000 --- a/firmware-and-api-reference/pycom/aes.md +++ /dev/null @@ -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 %} - diff --git a/firmware-and-api-reference/pycom/machine/README.md b/firmware-and-api-reference/pycom/machine/README.md deleted file mode 100644 index 80a5876..0000000 --- a/firmware-and-api-reference/pycom/machine/README.md +++ /dev/null @@ -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` - diff --git a/firmware-and-api-reference/pycom/machine/adc.md b/firmware-and-api-reference/pycom/machine/adc.md deleted file mode 100644 index d2a116d..0000000 --- a/firmware-and-api-reference/pycom/machine/adc.md +++ /dev/null @@ -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 %} - diff --git a/firmware-and-api-reference/pycom/machine/can.md b/firmware-and-api-reference/pycom/machine/can.md deleted file mode 100644 index 80f4882..0000000 --- a/firmware-and-api-reference/pycom/machine/can.md +++ /dev/null @@ -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 \(>= 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` - diff --git a/firmware-and-api-reference/pycom/machine/dac.md b/firmware-and-api-reference/pycom/machine/dac.md deleted file mode 100644 index 983869b..0000000 --- a/firmware-and-api-reference/pycom/machine/dac.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/pycom/machine/i2c.md b/firmware-and-api-reference/pycom/machine/i2c.md deleted file mode 100644 index e180b55..0000000 --- a/firmware-and-api-reference/pycom/machine/i2c.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/pycom/machine/pin.md b/firmware-and-api-reference/pycom/machine/pin.md deleted file mode 100644 index b1dd63e..0000000 --- a/firmware-and-api-reference/pycom/machine/pin.md +++ /dev/null @@ -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` - diff --git a/firmware-and-api-reference/pycom/machine/pwm.md b/firmware-and-api-reference/pycom/machine/pwm.md deleted file mode 100644 index 24a8d30..0000000 --- a/firmware-and-api-reference/pycom/machine/pwm.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/pycom/machine/rmt.md b/firmware-and-api-reference/pycom/machine/rmt.md deleted file mode 100644 index cd710e2..0000000 --- a/firmware-and-api-reference/pycom/machine/rmt.md +++ /dev/null @@ -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` - diff --git a/firmware-and-api-reference/pycom/machine/rtc.md b/firmware-and-api-reference/pycom/machine/rtc.md deleted file mode 100644 index 9b32c5b..0000000 --- a/firmware-and-api-reference/pycom/machine/rtc.md +++ /dev/null @@ -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` - diff --git a/firmware-and-api-reference/pycom/machine/sd.md b/firmware-and-api-reference/pycom/machine/sd.md deleted file mode 100644 index a5ee55f..0000000 --- a/firmware-and-api-reference/pycom/machine/sd.md +++ /dev/null @@ -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 %} - diff --git a/firmware-and-api-reference/pycom/machine/spi.md b/firmware-and-api-reference/pycom/machine/spi.md deleted file mode 100644 index d4f1382..0000000 --- a/firmware-and-api-reference/pycom/machine/spi.md +++ /dev/null @@ -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` - diff --git a/firmware-and-api-reference/pycom/machine/timer.md b/firmware-and-api-reference/pycom/machine/timer.md deleted file mode 100644 index cb3a1d8..0000000 --- a/firmware-and-api-reference/pycom/machine/timer.md +++ /dev/null @@ -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 %} - diff --git a/firmware-and-api-reference/pycom/machine/uart.md b/firmware-and-api-reference/pycom/machine/uart.md deleted file mode 100644 index 655dbbd..0000000 --- a/firmware-and-api-reference/pycom/machine/uart.md +++ /dev/null @@ -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` - diff --git a/firmware-and-api-reference/pycom/machine/wdt.md b/firmware-and-api-reference/pycom/machine/wdt.md deleted file mode 100644 index aecf6b7..0000000 --- a/firmware-and-api-reference/pycom/machine/wdt.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/pycom/network/README.md b/firmware-and-api-reference/pycom/network/README.md deleted file mode 100644 index 57b7462..0000000 --- a/firmware-and-api-reference/pycom/network/README.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/pycom/network/bluetooth/README.md b/firmware-and-api-reference/pycom/network/bluetooth/README.md deleted file mode 100644 index 7fe1da3..0000000 --- a/firmware-and-api-reference/pycom/network/bluetooth/README.md +++ /dev/null @@ -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 > 0, then the BLE radio will listen for advertisements until the specified value in seconds elapses. If timeout < 0, then there’s no timeout at all, and stop\_scan\(\) needs to be called to cancel the scanning process. - -Examples: - -```python -bluetooth.start_scan(10) # starts scanning and stop after 10 seconds -bluetooth.start_scan(-1) # starts scanning indefinitely until bluetooth.stop_scan() is called -``` - -### bluetooth.stop\_scan\(\) - -Stops an ongoing scanning process. Returns `None`. - -### bluetooth.isscanning\(\) - -Returns `True` if a Bluetooth scan is in progress. `False` otherwise. - -### bluetooth.get\_adv\(\) - -Gets an named tuple with the advertisement data received during the scanning. The tuple has the following structure: `(mac, addr_type, adv_type, rssi, data)` - -* `mac` is the 6-byte ling mac address of the device that sent the advertisement. -* `addr_type` is the address type. See the constants section below for more details. -* `adv_type` is the advertisement type received. See the constants section below fro more details. -* `rssi` is signed integer with the signal strength of the advertisement. -* `data` contains the complete 31 bytes of the advertisement message. In order to parse the data and get the specific types, the method `resolve_adv_data()` can be used. - -Example for getting `mac` address of an advertiser: - -```python -import ubinascii - -bluetooth = Bluetooth() -bluetooth.start_scan(20) # scan for 20 seconds - -adv = bluetooth.get_adv() # -ubinascii.hexlify(adv.mac) # convert hexadecimal to ascii -``` - -### bluetooth.get\_advertisements\(\) - -Same as the `get_adv()` method, but this one returns a list with all the advertisements received. - -### bluetooth.resolve\_adv\_data\(data, data\_type\) - -Parses the advertisement data and returns the requested `data_type` if present. If the data type is not present, the function returns `None`. - -Arguments: - -* `data` is the bytes object with the complete advertisement data. -* `data_type` is the data type to resolve from from the advertisement data. See constants section below for details. - -Example: - -```python -import ubinascii -from network import Bluetooth -bluetooth = Bluetooth() - -bluetooth.start_scan(20) -while bluetooth.isscanning(): - adv = bluetooth.get_adv() - if adv: - # try to get the complete name - print(bluetooth.resolve_adv_data(adv.data, Bluetooth.ADV_NAME_CMPL)) - - mfg_data = bluetooth.resolve_adv_data(adv.data, Bluetooth.ADV_MANUFACTURER_DATA) - - if mfg_data: - # try to get the manufacturer data (Apple's iBeacon data is sent here) - print(ubinascii.hexlify(mfg_data)) -``` - -### bluetooth.connect\(mac\_addr\) - -Opens a BLE connection with the device specified by the `mac_addr` argument. This function blocks until the connection succeeds or fails. If the connections succeeds it returns a object of type `GATTCConnection`. - -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` - diff --git a/firmware-and-api-reference/pycom/network/bluetooth/gatt.md b/firmware-and-api-reference/pycom/network/bluetooth/gatt.md deleted file mode 100644 index c93fee7..0000000 --- a/firmware-and-api-reference/pycom/network/bluetooth/gatt.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/pycom/network/bluetooth/gattccharacteristic.md b/firmware-and-api-reference/pycom/network/bluetooth/gattccharacteristic.md deleted file mode 100644 index 2640e3b..0000000 --- a/firmware-and-api-reference/pycom/network/bluetooth/gattccharacteristic.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/pycom/network/bluetooth/gattcconnection.md b/firmware-and-api-reference/pycom/network/bluetooth/gattcconnection.md deleted file mode 100644 index c4523e0..0000000 --- a/firmware-and-api-reference/pycom/network/bluetooth/gattcconnection.md +++ /dev/null @@ -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()) -``` - diff --git a/firmware-and-api-reference/pycom/network/bluetooth/gattccservice.md b/firmware-and-api-reference/pycom/network/bluetooth/gattccservice.md deleted file mode 100644 index dd5b0b5..0000000 --- a/firmware-and-api-reference/pycom/network/bluetooth/gattccservice.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/pycom/network/bluetooth/gattscharacteristic.md b/firmware-and-api-reference/pycom/network/bluetooth/gattscharacteristic.md deleted file mode 100644 index a8f2b7e..0000000 --- a/firmware-and-api-reference/pycom/network/bluetooth/gattscharacteristic.md +++ /dev/null @@ -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) -``` - diff --git a/firmware-and-api-reference/pycom/network/bluetooth/gattsservice.md b/firmware-and-api-reference/pycom/network/bluetooth/gattsservice.md deleted file mode 100644 index 31ec57c..0000000 --- a/firmware-and-api-reference/pycom/network/bluetooth/gattsservice.md +++ /dev/null @@ -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) -``` - diff --git a/firmware-and-api-reference/pycom/network/lora.md b/firmware-and-api-reference/pycom/network/lora.md deleted file mode 100644 index c9396f3..0000000 --- a/firmware-and-api-reference/pycom/network/lora.md +++ /dev/null @@ -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) -``` - diff --git a/firmware-and-api-reference/pycom/network/lte.md b/firmware-and-api-reference/pycom/network/lte.md deleted file mode 100644 index 668f165..0000000 --- a/firmware-and-api-reference/pycom/network/lte.md +++ /dev/null @@ -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 \ No newline at end of file diff --git a/firmware-and-api-reference/pycom/network/server.md b/firmware-and-api-reference/pycom/network/server.md deleted file mode 100644 index a6c5e19..0000000 --- a/firmware-and-api-reference/pycom/network/server.md +++ /dev/null @@ -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. - diff --git a/firmware-and-api-reference/pycom/network/sigfox.md b/firmware-and-api-reference/pycom/network/sigfox.md deleted file mode 100644 index 9244cfd..0000000 --- a/firmware-and-api-reference/pycom/network/sigfox.md +++ /dev/null @@ -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 %} - diff --git a/firmware-and-api-reference/pycom/network/wlan.md b/firmware-and-api-reference/pycom/network/wlan.md deleted file mode 100644 index daf04cd..0000000 --- a/firmware-and-api-reference/pycom/network/wlan.md +++ /dev/null @@ -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` - diff --git a/firmware-and-api-reference/pycom/pycom.md b/firmware-and-api-reference/pycom/pycom.md deleted file mode 100644 index ce662d7..0000000 --- a/firmware-and-api-reference/pycom/pycom.md +++ /dev/null @@ -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. - diff --git a/getting-started/connection/README.md b/getting-started/connection/README.md deleted file mode 100644 index 3cbe712..0000000 --- a/getting-started/connection/README.md +++ /dev/null @@ -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" %} - diff --git a/getting-started/connection/fipy.md b/getting-started/connection/fipy.md deleted file mode 100644 index 6a584bf..0000000 --- a/getting-started/connection/fipy.md +++ /dev/null @@ -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 - -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) - diff --git a/getting-started/connection/gpy.md b/getting-started/connection/gpy.md deleted file mode 100644 index 83f389b..0000000 --- a/getting-started/connection/gpy.md +++ /dev/null @@ -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 - -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) - diff --git a/getting-started/connection/lopy.md b/getting-started/connection/lopy.md deleted file mode 100644 index 7d07644..0000000 --- a/getting-started/connection/lopy.md +++ /dev/null @@ -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) - diff --git a/getting-started/connection/lopy4.md b/getting-started/connection/lopy4.md deleted file mode 100644 index 90d3e35..0000000 --- a/getting-started/connection/lopy4.md +++ /dev/null @@ -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) - diff --git a/getting-started/connection/sipy.md b/getting-started/connection/sipy.md deleted file mode 100644 index a122cd3..0000000 --- a/getting-started/connection/sipy.md +++ /dev/null @@ -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) - diff --git a/getting-started/connection/wipy.md b/getting-started/connection/wipy.md deleted file mode 100644 index b094b37..0000000 --- a/getting-started/connection/wipy.md +++ /dev/null @@ -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\) - diff --git a/getting-started/installation/README.md b/getting-started/installation/README.md deleted file mode 100644 index 918a459..0000000 --- a/getting-started/installation/README.md +++ /dev/null @@ -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. - diff --git a/getting-started/installation/drivers.md b/getting-started/installation/drivers.md deleted file mode 100644 index 8ae7dee..0000000 --- a/getting-started/installation/drivers.md +++ /dev/null @@ -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) - diff --git a/getting-started/installation/firmwaretool.md b/getting-started/installation/firmwaretool.md deleted file mode 100644 index eaea79a..0000000 --- a/getting-started/installation/firmwaretool.md +++ /dev/null @@ -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. - diff --git a/getting-started/installation/pymakr.md b/getting-started/installation/pymakr.md deleted file mode 100644 index 6fe670c..0000000 --- a/getting-started/installation/pymakr.md +++ /dev/null @@ -1,12 +0,0 @@ -# Pymakr - -![](../../.gitbook/assets/pymakr-logo-1%20%281%29.png) - -## Pymakr Plugins - -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" %} - diff --git a/getting-started/introduction.md b/getting-started/introduction.md deleted file mode 100644 index 066678c..0000000 --- a/getting-started/introduction.md +++ /dev/null @@ -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 %} - diff --git a/getting-started/programming/README.md b/getting-started/programming/README.md deleted file mode 100644 index 2ca30f5..0000000 --- a/getting-started/programming/README.md +++ /dev/null @@ -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. - diff --git a/getting-started/programming/examples.md b/getting-started/programming/examples.md deleted file mode 100644 index 36b38f1..0000000 --- a/getting-started/programming/examples.md +++ /dev/null @@ -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 %} - diff --git a/getting-started/programming/first-project.md b/getting-started/programming/first-project.md deleted file mode 100644 index a606085..0000000 --- a/getting-started/programming/first-project.md +++ /dev/null @@ -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` > `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') -``` - diff --git a/getting-started/programming/ftp.md b/getting-started/programming/ftp.md deleted file mode 100644 index 3b01383..0000000 --- a/getting-started/programming/ftp.md +++ /dev/null @@ -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) - diff --git a/getting-started/programming/micropython.md b/getting-started/programming/micropython.md deleted file mode 100644 index d6a9970..0000000 --- a/getting-started/programming/micropython.md +++ /dev/null @@ -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 %} - diff --git a/getting-started/programming/repl/README.md b/getting-started/programming/repl/README.md deleted file mode 100644 index fcad659..0000000 --- a/getting-started/programming/repl/README.md +++ /dev/null @@ -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 %} - diff --git a/getting-started/programming/repl/serial.md b/getting-started/programming/repl/serial.md deleted file mode 100644 index d8fd494..0000000 --- a/getting-started/programming/repl/serial.md +++ /dev/null @@ -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) - diff --git a/getting-started/programming/repl/telnet.md b/getting-started/programming/repl/telnet.md deleted file mode 100644 index 2f4d986..0000000 --- a/getting-started/programming/repl/telnet.md +++ /dev/null @@ -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 %} - diff --git a/getting-started/programming/safeboot.md b/getting-started/programming/safeboot.md deleted file mode 100644 index 1e235c6..0000000 --- a/getting-started/programming/safeboot.md +++ /dev/null @@ -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() -``` - diff --git a/getting-started/registration/README.md b/getting-started/registration/README.md deleted file mode 100644 index ceadcbd..0000000 --- a/getting-started/registration/README.md +++ /dev/null @@ -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 %} - diff --git a/getting-started/registration/cellular.md b/getting-started/registration/cellular.md deleted file mode 100644 index ee14ca3..0000000 --- a/getting-started/registration/cellular.md +++ /dev/null @@ -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). - diff --git a/getting-started/registration/lora/README.md b/getting-started/registration/lora/README.md deleted file mode 100644 index 021a492..0000000 --- a/getting-started/registration/lora/README.md +++ /dev/null @@ -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 %} - diff --git a/getting-started/registration/lora/senet.md b/getting-started/registration/lora/senet.md deleted file mode 100644 index 7bfff66..0000000 --- a/getting-started/registration/lora/senet.md +++ /dev/null @@ -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. - diff --git a/getting-started/registration/lora/ttn.md b/getting-started/registration/lora/ttn.md deleted file mode 100644 index 18e1271..0000000 --- a/getting-started/registration/lora/ttn.md +++ /dev/null @@ -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. - diff --git a/getting-started/registration/sigfox.md b/getting-started/registration/sigfox.md deleted file mode 100644 index 9fd1c78..0000000 --- a/getting-started/registration/sigfox.md +++ /dev/null @@ -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. - diff --git a/getting-started/troubleshooting-guide.md b/getting-started/troubleshooting-guide.md deleted file mode 100644 index 80b744f..0000000 --- a/getting-started/troubleshooting-guide.md +++ /dev/null @@ -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`\). - diff --git a/product-info-datasheets/boards/README.md b/product-info-datasheets/boards/README.md deleted file mode 100644 index 997138b..0000000 --- a/product-info-datasheets/boards/README.md +++ /dev/null @@ -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/" %} - diff --git a/product-info-datasheets/boards/deepsleep/README.md b/product-info-datasheets/boards/deepsleep/README.md deleted file mode 100644 index 5e075ce..0000000 --- a/product-info-datasheets/boards/deepsleep/README.md +++ /dev/null @@ -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) - diff --git a/product-info-datasheets/boards/deepsleep/api.md b/product-info-datasheets/boards/deepsleep/api.md deleted file mode 100644 index 9106580..0000000 --- a/product-info-datasheets/boards/deepsleep/api.md +++ /dev/null @@ -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 %} - diff --git a/product-info-datasheets/boards/expansion2.md b/product-info-datasheets/boards/expansion2.md deleted file mode 100644 index e794a17..0000000 --- a/product-info-datasheets/boards/expansion2.md +++ /dev/null @@ -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`. - - - diff --git a/product-info-datasheets/boards/expansion3.md b/product-info-datasheets/boards/expansion3.md deleted file mode 100644 index fb2e557..0000000 --- a/product-info-datasheets/boards/expansion3.md +++ /dev/null @@ -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 - diff --git a/product-info-datasheets/boards/pyscan.md b/product-info-datasheets/boards/pyscan.md deleted file mode 100644 index f1d1e74..0000000 --- a/product-info-datasheets/boards/pyscan.md +++ /dev/null @@ -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\). - - - diff --git a/product-info-datasheets/boards/pysense.md b/product-info-datasheets/boards/pysense.md deleted file mode 100644 index 414fd2e..0000000 --- a/product-info-datasheets/boards/pysense.md +++ /dev/null @@ -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\). - - - diff --git a/product-info-datasheets/boards/pytrack.md b/product-info-datasheets/boards/pytrack.md deleted file mode 100644 index 6fcee55..0000000 --- a/product-info-datasheets/boards/pytrack.md +++ /dev/null @@ -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\). - - - diff --git a/product-info-datasheets/development/README.md b/product-info-datasheets/development/README.md deleted file mode 100644 index fb11de1..0000000 --- a/product-info-datasheets/development/README.md +++ /dev/null @@ -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" %} - diff --git a/product-info-datasheets/development/fipy.md b/product-info-datasheets/development/fipy.md deleted file mode 100644 index bbeecab..0000000 --- a/product-info-datasheets/development/fipy.md +++ /dev/null @@ -1,60 +0,0 @@ -# FiPy - -\*\*\*\*![](../../.gitbook/assets/assets-lil0igdl11z7jos_jpx-lkn7scqkkkb6tqb3uyo-lkn82srvkf3rhetvjpi-fipy-1.png) **** - -**Store**: [Buy Here](https://pycom.io/product/fipy/) - -**Getting Started:** [Click Here](../../getting-started/connection/fipy.md) - -## Datasheet - -The datasheet of the FiPy is available as a PDF File. - -{% file src="../../.gitbook/assets/fipy-specsheet-1.pdf" caption="FiPy Datasheet" %} - -The drawing of the LTE-M antenna is available as a PDF File. - -{% file src="../../.gitbook/assets/lte-m-antenna-drawing.pdf" caption="LTE-M Antenna Drawing" %} - -## Pinout - -The pinout of the FiPy is available as a PDF File - -{% file src="../../.gitbook/assets/fipy-pinout.pdf" caption="FiPy Pinout" %} - -![](../../.gitbook/assets/fipy-pinout.png) - -{% hint style="info" %} -Please note that the PIN assignments for UART1 \(TX1/RX1\), SPI \(CLK, MOSI, MISO\) and I2C \(SDA, SCL\) are defaults and can be changed in Software. -{% endhint %} - -## Notes - -### WiFi - -By default, upon boot the FiPy will create a WiFi access point with the SSID `fipy-wlan-XXXX`, where `XXXX` is a random 4-digit number, and the password `www.pycom.io`. - -The RF switch that selects between the on-board and external antenna is connected to `P12`, for this reason using `P12` should be avoided unless WiFi is disabled in your application. - -### Power - -The `Vin` pin on the FiPy can be supplied with a voltage ranging from `3.5v` to `5.5v`. The `3.3v` pin on the other hand is output **only**, and must not be used to feed power into the FiPy, otherwise the on-board regulator will be damaged. - -### AT Commands - -The AT commands for the Sequans Monarch modem on the FiPy are available in a PDF file. - -{% file src="../../.gitbook/assets/monarch\_4g-ez\_lr5110\_atcommands\_referencemanual\_rev3\_noconfidential-2.pdf" caption="AT Commands for Sequans" %} - -## Tutorials - -Tutorials on how to the FiPy module can be found in the [examples](../../tutorials-and-examples/introduction.md) section of this documentation. The following tutorials might be of specific interest for the FiPy: - -* [WiFi connection](../../tutorials-and-examples/all/wlan.md) -* [LoRaWAN node](../../tutorials-and-examples/lora/lorawan-abp.md) -* [LoRaWAN nano gateway](../../tutorials-and-examples/lora/lorawan-nano-gateway.md) -* [Sigfox](../../tutorials-and-examples/sigfox.md) -* [LTE CAT-M1](../../tutorials-and-examples/lte/cat-m1.md) -* [NB-IoT](../../tutorials-and-examples/lte/nb-iot.md) -* [BLE](../../tutorials-and-examples/all/ble.md) - diff --git a/product-info-datasheets/development/gpy.md b/product-info-datasheets/development/gpy.md deleted file mode 100644 index b12525d..0000000 --- a/product-info-datasheets/development/gpy.md +++ /dev/null @@ -1,57 +0,0 @@ -# GPy - -\*\*\*\*![](../../.gitbook/assets/assets-lil0igdl11z7jos_jpx-lkn7scqkkkb6tqb3uyo-lkn87yf-xz772800vwc-gpy-1.png) **** - -**Store**: [Buy Here](https://pycom.io/product/gpy) - -**Getting Started:** [Click Here](../../getting-started/connection/gpy.md) - -## Datasheet - -The datasheet of the GPy is available as a PDF File. - -{% file src="../../.gitbook/assets/gpy-specsheet.pdf" caption="GPy Datasheet" %} - -The drawing of the LTE-M antenna is available as a PDF File. - -{% file src="../../.gitbook/assets/lte-m-antenna-drawing.pdf" caption="LTE-M Antenna Drawing" %} - -## Pinout - -The pinout of the GPy is available as a PDF File - -{% file src="../../.gitbook/assets/gpy-pinout.pdf" caption="GPy Pinout" %} - -![](../../.gitbook/assets/gpy-pinout.png) - -{% hint style="info" %} -Please note that the PIN assignments for UART1 \(TX1/RX1\), SPI \(CLK, MOSI, MISO\) and I2C \(SDA, SCL\) are defaults and can be changed in Software. -{% endhint %} - -## Notes - -### WiFi - -By default, upon boot the GPy will create a WiFi access point with the SSID `gpy-wlan-XXXX`, where `XXXX` is a random 4-digit number, and the password `www.pycom.io`. - -The RF switch that selects between the on-board and external antenna is connected to `P12`, for this reason using `P12` should be avoided unless WiFi is disabled in your application. - -### Power - -The `Vin` pin on the GPy can be supplied with a voltage ranging from `3.5v` to `5.5v`. The `3.3v` pin on the other hand is output **only**, and must not be used to feed power into the GPy, otherwise the on-board regulator will be damaged. - -### AT Commands - -The AT commands for the Sequans Monarch modem on the GPy are available in a PDF file. - -{% file src="../../.gitbook/assets/monarch\_4g-ez\_lr5110\_atcommands\_referencemanual\_rev3\_noconfidential-1.pdf" caption="AT Commands for Sequans" %} - -## Tutorials - -Tutorials on how to the GPy module can be found in the [examples](../../tutorials-and-examples/introduction.md) section of this documentation. The following tutorials might be of specific interest for the GPy: - -* [WiFi connection](../../tutorials-and-examples/all/wlan.md) -* [LTE CAT-M1](../../tutorials-and-examples/lte/cat-m1.md) -* [NB-IoT](../../tutorials-and-examples/lte/nb-iot.md) -* [BLE](../../tutorials-and-examples/all/ble.md) - diff --git a/product-info-datasheets/development/lopy.md b/product-info-datasheets/development/lopy.md deleted file mode 100644 index f637ae1..0000000 --- a/product-info-datasheets/development/lopy.md +++ /dev/null @@ -1,49 +0,0 @@ -# LoPy - -\*\*\*\*![](../../.gitbook/assets/assets-lil0igdl11z7jos_jpx-lkn7scqkkkb6tqb3uyo-lkn80ythqnrgah01r2m-lopy-1.png) **** - -**Store**: [Buy Here](https://pycom.io/product/lopy) - -**Getting Started:** [Click Here](../../getting-started/connection/lopy.md) - -## Datasheet - -The datasheet of the LoPy is available as a PDF File. - -{% file src="../../.gitbook/assets/lopy-specsheet.pdf" caption="LoPy Datasheet" %} - -## Pinout - -The pinout of the LoPy is available as a PDF File - -{% file src="../../.gitbook/assets/lopy-pinout.pdf" caption="LoPy Pinout" %} - -![](../../.gitbook/assets/lopy-pinout.png) - -{% hint style="info" %} -Please note that the PIN assignments for UART1 \(TX1/RX1\), SPI \(CLK, MOSI, MISO\) and I2C \(SDA, SCL\) are defaults and can be changed in Software. -{% endhint %} - -## Notes - -### WiFi - -By default, upon boot the LoPy will create a WiFi access point with the SSID `lopy-wlan-XXXX`, where `XXXX` is a random 4-digit number, and the password `www.pycom.io`. - -### Power - -The `Vin` pin on the LoPy can be supplied with a voltage ranging from `3.5v` to `5.5v`. The `3.3v` pin on the other hand is output **only**, and must not be used to feed power into the LoPy, otherwise the on-board regulator will be damaged. - -### Deep Sleep - -Due to a couple issues with the LoPy design the module draws more current than it should while in deep sleep. The DC-DC switching regulator always stays in high performance mode which is used to provide the lowest possible output ripple when the modules is in use. In this mode, it draws a quiescent current of 10mA. When the regulator is put into ECO mode, the quiescent current goes down to 10uA. Unfortunately, the pin used to control this mode is out of the RTC domain, and therefore not usable during deep sleep. This causes the regulator to always stay in PWM mode, keeping its quiescent current at 10mA. Alongside this the flash chip doesn't enter power down mode because the CS pin is floating during deep sleep. This causes the flash chip to consume around 2mA of current. To work around this issue a ["deep sleep shield"](../boards/deepsleep/) is available that attaches to the module and allows power to be cut off from the device. The device can then be re-enabled either on a timer or via pin interrupt. With the deep sleep shield the current consumption during deep sleep is between 7uA and 10uA depending on the wake sources configured. - -## Tutorials - -Tutorials on how to the LoPy module can be found in the [examples](../../tutorials-and-examples/introduction.md) section of this documentation. The following tutorials might be of specific interest for the LoPy: - -* [WiFi connection](../../tutorials-and-examples/all/wlan.md) -* [LoRaWAN node](../../tutorials-and-examples/lora/lorawan-abp.md) -* [LoRaWAN nano gateway](../../tutorials-and-examples/lora/lorawan-nano-gateway.md) -* [BLE](../../tutorials-and-examples/all/ble.md) - diff --git a/product-info-datasheets/development/lopy4.md b/product-info-datasheets/development/lopy4.md deleted file mode 100644 index 1b36a84..0000000 --- a/product-info-datasheets/development/lopy4.md +++ /dev/null @@ -1,48 +0,0 @@ -# LoPy 4 - -\*\*\*\*![](../../.gitbook/assets/assets-lil0igdl11z7jos_jpx-lkn7scqkkkb6tqb3uyo-lkn85npgnazxzxyv-nu-lopy4-1.png) **** - -**Store**: [Buy Here](https://pycom.io/product/lopy4/) - -**Getting Started:** [Click Here](../../getting-started/connection/lopy4.md) - -## Datasheet - -The datasheet of the LoPy4 is available as a PDF File. - -{% file src="../../.gitbook/assets/lopy4-specsheet-1.pdf" caption="LoPy4 Datasheet" %} - -## Pinout - -The pinout of the LoPy4 is available as a PDF File - -{% file src="../../.gitbook/assets/lopy4-pinout.pdf" caption="LoPy4 Pinout" %} - -![](../../.gitbook/assets/lopy4-pinout.png) - -{% hint style="info" %} -Please note that the PIN assignments for UART1 \(TX1/RX1\), SPI \(CLK, MOSI, MISO\) and I2C \(SDA, SCL\) are defaults and can be changed in Software. -{% endhint %} - -## Notes - -### WiFi - -By default, upon boot the LoPy4 will create a WiFi access point with the SSID `lopy4-wlan-XXXX`, where `XXXX` is a random 4-digit number, and the password `www.pycom.io`. - -The RF switch that selects between the on-board and external antenna is connected to `P12`, for this reason using `P12` should be avoided unless WiFi is disabled in your application. - -### Power - -The `Vin` pin on the LoPy4 can be supplied with a voltage ranging from `3.5v` to `5.5v`. The `3.3v` pin on the other hand is output **only**, and must not be used to feed power into the LoPy4, otherwise the on-board regulator will be damaged. - -## Tutorials - -Tutorials on how to the LoPy4 module can be found in the [examples](../../tutorials-and-examples/introduction.md) section of this documentation. The following tutorials might be of specific interest for the LoPy4: - -* [WiFi connection](../../tutorials-and-examples/all/wlan.md) -* [LoRaWAN node](../../tutorials-and-examples/lora/lorawan-abp.md) -* [LoRaWAN nano gateway](../../tutorials-and-examples/lora/lorawan-nano-gateway.md) -* [Sigfox](../../tutorials-and-examples/sigfox.md) -* [BLE](../../tutorials-and-examples/all/ble.md) - diff --git a/product-info-datasheets/development/sipy.md b/product-info-datasheets/development/sipy.md deleted file mode 100644 index 2466c7a..0000000 --- a/product-info-datasheets/development/sipy.md +++ /dev/null @@ -1,48 +0,0 @@ -# SiPy - -\*\*\*\*![](../../.gitbook/assets/assets-lil0igdl11z7jos_jpx-lkn7scqkkkb6tqb3uyo-lkn86n8h-hb1oh1idwb-sipy-2.png) **** - -**Store**: [Buy Here](https://pycom.io/product/sipy) - -**Getting Started:** [Click Here](../../getting-started/connection/sipy.md) - -## Datasheet - -The datasheet of the SiPy is available as a PDF File. - -{% file src="../../.gitbook/assets/sipy-specsheet.pdf" caption="SiPy Datasheet" %} - -## Pinout - -The pinout of the SiPy is available as a PDF File - -{% file src="../../.gitbook/assets/sipy-pinout.pdf" caption="SiPy Pinout" %} - -![](../../.gitbook/assets/sipy-pinout.png) - -{% hint style="info" %} -Please note that the PIN assignments for UART1 \(TX1/RX1\), SPI \(CLK, MOSI, MISO\) and I2C \(SDA, SCL\) are defaults and can be changed in Software. -{% endhint %} - -## Notes - -### WiFi - -By default, upon boot the SiPy will create a WiFi access point with the SSID `sipy-wlan-XXXX`, where `XXXX` is a random 4-digit number, and the password `www.pycom.io`. - -### Power - -The `Vin` pin on the SiPy can be supplied with a voltage ranging from `3.5v` to `5.5v`. The `3.3v` pin on the other hand is output **only**, and must not be used to feed power into the SiPy, otherwise the on-board regulator will be damaged. - -### Deep Sleep - -Due to a couple issues with the SiPy design the module draws more current than it should while in deep sleep. The DC-DC switching regulator always stays in high performance mode which is used to provide the lowest possible output ripple when the modules is in use. In this mode, it draws a quiescent current of 10mA. When the regulator is put into ECO mode, the quiescent current goes down to 10uA. Unfortunately, the pin used to control this mode is out of the RTC domain, and therefore not usable during deep sleep. This causes the regulator to always stay in PWM mode, keeping its quiescent current at 10mA. Alongside this the flash chip doesn't enter power down mode because the CS pin is floating during deep sleep. This causes the flash chip to consume around 2mA of current. To work around this issue a ["deep sleep shield"](../boards/deepsleep/) is available that attaches to the module and allows power to be cut off from the device. The device can then be re-enabled either on a timer or via pin interrupt. With the deep sleep shield the current consumption during deep sleep is between 7uA and 10uA depending on the wake sources configured. - -## Tutorials - -Tutorials on how to the SiPy module can be found in the [examples](../../tutorials-and-examples/introduction.md) section of this documentation. The following tutorials might be of specific interest for the SiPy: - -* [WiFi connection](../../tutorials-and-examples/all/wlan.md) -* [Sigfox](../../tutorials-and-examples/sigfox.md) -* [BLE](../../tutorials-and-examples/all/ble.md) - diff --git a/product-info-datasheets/development/wipy2.md b/product-info-datasheets/development/wipy2.md deleted file mode 100644 index 214bedd..0000000 --- a/product-info-datasheets/development/wipy2.md +++ /dev/null @@ -1,47 +0,0 @@ -# WiPy 2.0 - -\*\*\*\*![](../../.gitbook/assets/assets-lil0igdl11z7jos_jpx-lkn7scqkkkb6tqb3uyo-lkn83ftusu7mke5ppmd-wipy2-1.png) **** - -**Store**: Discontinued, See [WiPy3](wipy3.md) - -**Getting Started:** [Click Here](../../getting-started/connection/wipy.md) - -## Datasheet - -The datasheet of the WiPy2 is available as a PDF File. - -{% file src="../../.gitbook/assets/wipy2-specsheet.pdf" caption="WiPy 2 Datasheet" %} - -## Pinout - -The pinout of the WiPy2 is available as a PDF File. - -{% file src="../../.gitbook/assets/wipy2-pinout.pdf" caption="WiPy 2 Pinout" %} - -![](../../.gitbook/assets/wipy2-pinout.png) - -{% hint style="info" %} -Please note that the PIN assignments for UART1 \(TX1/RX1\), SPI \(CLK, MOSI, MISO\) and I2C \(SDA, SCL\) are defaults and can be changed in Software. -{% endhint %} - -## Notes - -### WiFi - -By default, upon boot the WiPy2 will create a WiFi access point with the SSID `wipy-wlan-XXXX`, where `XXXX` is a random 4-digit number, and the password `www.pycom.io`. - -### Power - -The `Vin` pin on the WiPy2 can be supplied with a voltage ranging from `3.5v` to `5.5v`. The `3.3v` pin on the other hand is output **only**, and must not be used to feed power into the WiPy2, otherwise the on-board regulator will be damaged. - -### Deep Sleep - -Due to a couple issues with the WiPy2 design the module draws more current than it should while in deep sleep. The DC-DC switching regulator always stays in high performance mode which is used to provide the lowest possible output ripple when the modules is in use. In this mode, it draws a quiescent current of 10mA. When the regulator is put into ECO mode, the quiescent current goes down to 10uA. Unfortunately, the pin used to control this mode is out of the RTC domain, and therefore not usable during deep sleep. This causes the regulator to always stay in PWM mode, keeping its quiescent current at 10mA. Alongside this the flash chip doesn't enter power down mode because the CS pin is floating during deep sleep. This causes the flash chip to consume around 2mA of current. To work around this issue a ["deep sleep shield"](../boards/deepsleep/) is available that attaches to the module and allows power to be cut off from the device. The device can then be re-enabled either on a timer or via pin interrupt. With the deep sleep shield the current consumption during deep sleep is between 7uA and 10uA depending on the wake sources configured. - -## Tutorials - -Tutorials on how to the WiPy2 module can be found in the [examples](../../tutorials-and-examples/introduction.md) section of this documentation. The following tutorials might be of specific interest for the WiPy2: - -* [WiFi connection](../../tutorials-and-examples/all/wlan.md) -* [BLE](../../tutorials-and-examples/all/ble.md) - diff --git a/product-info-datasheets/development/wipy3.md b/product-info-datasheets/development/wipy3.md deleted file mode 100644 index 328d578..0000000 --- a/product-info-datasheets/development/wipy3.md +++ /dev/null @@ -1,52 +0,0 @@ -# WiPy 3.0 - -\*\*\*\*![](../../.gitbook/assets/assets-lil0igdl11z7jos_jpx-lkn7scqkkkb6tqb3uyo-lkn86pdzbdvrponxeg6-wipy3.png) **** - -**Store**: [Buy Here](https://pycom.io/product/wipy-3-0/) - -**Getting Started:** [Click Here](../../getting-started/connection/wipy.md) - -## Datasheet - -The datasheet of the WiPy3 is available as a PDF File. - -{% file src="../../.gitbook/assets/wipy3-specsheet.pdf" caption="WiPy3 Datasheet" %} - -## Pinout - -The pinout of the WiPy3 is available as a PDF File. - -{% file src="../../.gitbook/assets/wipy3-pinout.pdf" caption="WiPy3 Pinout" %} - -![](../../.gitbook/assets/wipy3-pinout.png) - -{% hint style="info" %} -Please note that the PIN assignments for UART1 \(TX1/RX1\), SPI \(CLK, MOSI, MISO\) and I2C \(SDA, SCL\) are defaults and can be changed in Software. -{% endhint %} - -## Differences from WiPy 2.0 - -* Deep sleep current draw fixed, now only 19.7µA -* Upgraded RAM from 512KB to 4MB -* Upgraded External FLASH from 4MB to 8MB -* Antenna select pin moved from GPIO16 to GPIO21 \(P12\) - -## Notes - -### WiFi - -By default, upon boot the WiPy3 will create a WiFi access point with the SSID `wipy-wlan-XXXX`, where `XXXX` is a random 4-digit number, and the password `www.pycom.io`. - -The RF switch that selects between the on-board and external antenna is connected to `P12`, for this reason using `P12` should be avoided unless WiFi is disabled in your application. - -### Power - -The `Vin` pin on the WiPy3 can be supplied with a voltage ranging from `3.5v` to `5.5v`. The `3.3v` pin on the other hand is output **only**, and must not be used to feed power into the WiPy3, otherwise the on-board regulator will be damaged. - -## Tutorials - -Tutorials on how to the WiPy3 module can be found in the [examples](../../tutorials-and-examples/introduction.md) section of this documentation. The following tutorials might be of specific interest for the WiPy3: - -* [WiFi connection](../../tutorials-and-examples/all/wlan.md) -* [BLE](../../tutorials-and-examples/all/ble.md) - diff --git a/product-info-datasheets/introduction.md b/product-info-datasheets/introduction.md deleted file mode 100644 index d274565..0000000 --- a/product-info-datasheets/introduction.md +++ /dev/null @@ -1,46 +0,0 @@ -# Introduction - -The follow pages contain all information relating to each product, for examples: pinouts, spec sheets, relevant examples and notes. - -## Development Modules - -{% page-ref page="development/wipy2.md" %} - -{% page-ref page="development/wipy3.md" %} - -{% page-ref page="development/lopy.md" %} - -{% page-ref page="development/lopy4.md" %} - -{% page-ref page="development/sipy.md" %} - -{% page-ref page="development/gpy.md" %} - -{% page-ref page="development/fipy.md" %} - -## OEM modules - -{% page-ref page="oem/w01.md" %} - -{% page-ref page="oem/l01.md" %} - -{% page-ref page="oem/g01.md" %} - -{% page-ref page="oem/l01\_reference.md" %} - -{% page-ref page="oem/universal\_reference.md" %} - -## Expansion Boards and Shields - -{% page-ref page="boards/expansion3.md" %} - -{% page-ref page="boards/pytrack.md" %} - -{% page-ref page="boards/pysense.md" %} - -{% page-ref page="boards/pyscan.md" %} - -{% page-ref page="boards/expansion2.md" %} - -{% page-ref page="boards/deepsleep/" %} - diff --git a/product-info-datasheets/notes.md b/product-info-datasheets/notes.md deleted file mode 100644 index 7f5f037..0000000 --- a/product-info-datasheets/notes.md +++ /dev/null @@ -1,26 +0,0 @@ -# Notes - -## Powering with an external power source - -The devices can be powered by a battery or other external power source. - -Be sure to connect the positive lead of the power supply to `VIN`, and ground to `GND`. - -When powering via `VIN`: - -* The input voltage must be between `3.4V` and `5.5V`. - -{% hint style="danger" %} -Please **DO NOT** power the board via the `3.3V` pin as this may damage the device. ONLY use the `VIN` pin for powering Pycom devices. -{% endhint %} - -The battery connector for the Expansion Board is a **JST PHR-2** variant. The Expansion Board exposes the male connector and an external battery should use a female adapter in order to connect and power the expansion board. The polarity of the battery should be checked before being plugged into the expansion board, the cables may require swapping. - -{% hint style="danger" %} -The `GPIO` pins of the modules are **NOT** `5V` tolerant, connecting them to voltages higher than `3.3V` might cause irreparable damage to the device. -{% endhint %} - -{% hint style="danger" %} -Static electricity can damage components on the device and may destroy them. If there is a lot of static electricity in the area \(e.g. dry and cold climates\), take extra care not to shock the device. If the device came in a ESD bag \(Silver packaging\), the best way to store and carry the device is inside this bag as it will be protected against static discharges. -{% endhint %} - diff --git a/product-info-datasheets/oem/README.md b/product-info-datasheets/oem/README.md deleted file mode 100644 index 5d50d8e..0000000 --- a/product-info-datasheets/oem/README.md +++ /dev/null @@ -1,14 +0,0 @@ -# OEM Modules - -This section contains all of the datasheets for the Pycom OEM Devices. This includes the W01, L01, L04, and G01. - -{% page-ref page="w01.md" %} - -{% page-ref page="l01.md" %} - -{% page-ref page="g01.md" %} - -{% page-ref page="l01\_reference.md" %} - -{% page-ref page="universal\_reference.md" %} - diff --git a/product-info-datasheets/oem/g01.md b/product-info-datasheets/oem/g01.md deleted file mode 100644 index 52f7ee8..0000000 --- a/product-info-datasheets/oem/g01.md +++ /dev/null @@ -1,43 +0,0 @@ -# G01 - -## ![](../../.gitbook/assets/assets-lil0igdl11z7jos_jpx-lkn7scqkkkb6tqb3uyo-lkn83xkh3nwgrgs_fwq-g01-1%20%282%29.png) - -## Datasheet - -The datasheet of the G01 is available as a PDF File. - -{% file src="../../.gitbook/assets/g01-specsheet.pdf" caption="G01 Datasheet" %} - -## Pinout - -The pinout of the G01 is available as a PDF File - -{% file src="../../.gitbook/assets/g01-pinout.pdf" caption="G01 Pinout" %} - -![](../../.gitbook/assets/g01-pinout.png) - -## Drawings - -The drawings for the G01 is available as a PDF File. - -{% file src="../../.gitbook/assets/g01-drawing.pdf" caption="G01 Drawings" %} - -{% hint style="info" %} -Please note that the PIN assignments for UART1 \(TX1/RX1\), SPI \(CLK, MOSI, MISO\) and I2C \(SDA, SCL\) are defaults and can be changed in Software. -{% endhint %} - -## AT Commands - -The AT commands for the Sequans Monarch modem on the G01 are available in a PDF file. - -{% file src="../../.gitbook/assets/monarch\_4g-ez\_lr5110\_atcommands\_referencemanual\_rev3\_noconfidential-3.pdf" caption="AT Commands for Sequans" %} - -## Tutorials - -Tutorials on how to the G01 module can be found in the [examples](../../tutorials-and-examples/introduction.md) section of this documentation. The following tutorials might be of specific interest for the G01: - -* [WiFi connection](../../tutorials-and-examples/all/wlan.md) -* [LTE CAT-M1](../../tutorials-and-examples/lte/cat-m1.md) -* [NB-IoT](../../tutorials-and-examples/lte/nb-iot.md) -* [BLE](../../tutorials-and-examples/all/ble.md) - diff --git a/product-info-datasheets/oem/l01.md b/product-info-datasheets/oem/l01.md deleted file mode 100644 index e43707d..0000000 --- a/product-info-datasheets/oem/l01.md +++ /dev/null @@ -1,37 +0,0 @@ -# L01 - -![](../../.gitbook/assets/assets-lil0igdl11z7jos_jpx-lkn7scqkkkb6tqb3uyo-lkn7x3eyyjifoqpxmzd-l01-1.png) - -## Datasheet - -The datasheet of the L01 is available as a PDF File. - -{% file src="../../.gitbook/assets/l01-specsheet-1.pdf" caption="L01 Datasheet" %} - -## Pinout - -The pinout of the L01 is available as a PDF File - -{% file src="../../.gitbook/assets/l01-pinout.pdf" caption="L01 Pinout" %} - -![](../../.gitbook/assets/l01-pinout.png) - -## Drawings - -The drawings for the L01 is available as a PDF File. - -{% file src="../../.gitbook/assets/l01-drawing.pdf" caption="L01 Drawing" %} - -{% hint style="info" %} -Please note that the PIN assignments for UART1 \(TX1/RX1\), SPI \(CLK, MOSI, MISO\) and I2C \(SDA, SCL\) are defaults and can be changed in Software. -{% endhint %} - -## Tutorials - -Tutorials on how to the L01 module can be found in the [examples](../../tutorials-and-examples/introduction.md) section of this documentation. The following tutorials might be of specific interest for the L01: - -* [WiFi connection](../../tutorials-and-examples/all/wlan.md) -* [LoRaWAN node](../../tutorials-and-examples/lora/lorawan-abp.md) -* [LoRaWAN nano gateway](../../tutorials-and-examples/lora/lorawan-nano-gateway.md) -* [BLE](../../tutorials-and-examples/all/ble.md) - diff --git a/product-info-datasheets/oem/l01_reference.md b/product-info-datasheets/oem/l01_reference.md deleted file mode 100644 index 37ed651..0000000 --- a/product-info-datasheets/oem/l01_reference.md +++ /dev/null @@ -1,45 +0,0 @@ -# L01 OEM Baseboard Reference - -![](../../.gitbook/assets/l01-reference%20%281%29.png) - -The L01 OEM reference board is a reference design suitable L01 as well as W01 making it possible to have a single PCB design that can accommodate both OEM modules. - -{% hint style="info" %} -If you require a reference board for the L04 or G01, this design is **not** suitable as it does not feature a SIM slot or the double antenna connection. For the G01 or L04 please use the [Universal OEM Baseboard Reference](universal_reference.md) -{% endhint %} - -## Features - -* Suits both L01 or W01 OEM Modules -* U.FL connector for the L01's LoRa output. -* On-board 2.4GHz antenna for WiFi and Bluetooth, with the ability to switch - - to a external antenna via a U.FL connector. - -* WS2812B RGB LED -* 3.5-5.5 Input switch mode DC-DC regulator with low current draw during deep - - sleep - -* Reset button - -## Layout - -The layout of the L01 baseboard reference is available as a PDF File - -{% file src="../../.gitbook/assets/l01-oem-layout.pdf" caption="L01 OEM Layout" %} - -![](../../.gitbook/assets/l01-oem-layout-1.png) - -## Schematic - -The schematic of the L01 baseboard reference is available as a PDF File. - -{% file src="../../.gitbook/assets/l01-oem-schematic.pdf" caption="L01 OEM Schematic" %} - -## Altium Project and Gerber Files - -The Altium Project and Gerber files are also available as a ZIP File. - -{% file src="../../.gitbook/assets/l01-oem-baseboard-ref.zip" caption="L01 OEM Altium Project and Gerber Files" %} - diff --git a/product-info-datasheets/oem/l04.md b/product-info-datasheets/oem/l04.md deleted file mode 100644 index c274ed0..0000000 --- a/product-info-datasheets/oem/l04.md +++ /dev/null @@ -1,38 +0,0 @@ -# L04 - -![](../../.gitbook/assets/assets-lil0igdl11z7jos_jpx-lkn7scqkkkb6tqb3uyo-lkn86hknsrea22r0i-s-l04-1.png) - -## Datasheet - -The datasheet of the L04 is available as a PDF File. - -{% file src="../../.gitbook/assets/l04-specsheet.pdf" caption="L04 Datasheet" %} - -## Pinout - -The pinout of the L04 is available as a PDF File - -{% file src="../../.gitbook/assets/l04-pinout.pdf" caption="L04 Pinout" %} - -![](../../.gitbook/assets/l04-pinout.png) - -## Drawings - -The drawings for the L04 is available as a PDF File. - -{% file src="../../.gitbook/assets/l04-drawing.pdf" caption="L04 Drawings" %} - -{% hint style="info" %} -Please note that the PIN assignments for UART1 \(TX1/RX1\), SPI \(CLK, MOSI, MISO\) and I2C \(SDA, SCL\) are defaults and can be changed in Software. -{% endhint %} - -## Tutorials - -Tutorials on how to the L04 module can be found in the [examples](../../tutorials-and-examples/introduction.md) section of this documentation. The following tutorials might be of specific interest for the L04: - -* [WiFi connection](../../tutorials-and-examples/all/wlan.md) -* [LoRaWAN node](../../tutorials-and-examples/lora/lorawan-abp.md) -* [LoRaWAN nano gateway](../../tutorials-and-examples/lora/lorawan-nano-gateway.md) -* [Sigfox](../../tutorials-and-examples/sigfox.md) -* [BLE](../../tutorials-and-examples/all/ble.md) - diff --git a/product-info-datasheets/oem/universal_reference.md b/product-info-datasheets/oem/universal_reference.md deleted file mode 100644 index 39b256c..0000000 --- a/product-info-datasheets/oem/universal_reference.md +++ /dev/null @@ -1,45 +0,0 @@ -# Universal OEM Baseboard Reference - -![](../../.gitbook/assets/universal_reference%20%281%29.png) - -The universal OEM reference board is a reference design suitable W01, L01, L04 and G01 OEM modules, making it possible to have a single PCB design that can accommodate all our OEM modules. - -{% hint style="info" %} -If you require a reference board for the G01, only this design is suitable. The L01 reference board does not contain the necessary SIM slot. -{% endhint %} - -## Features - -* Suits all OEM modules \(L01, L04, W01, G01\) -* On-board 2.4GHz antenna for WiFi and Bluetooth, with the ability to switch - - to a external antenna via a U.FL connector. - -* 3 U.FL connectors for all the outputs available on the OEM modules -* WS2812B RGB LED -* 3.5-5.5 Input switch mode DC-DC regulator with low current draw during deep - - sleep - -* Reset button - -## Layout - -The layout of the OEM baseboard reference is available as a PDF File - -{% file src="../../.gitbook/assets/oem-universal-layout.pdf" caption="OEM Layout" %} - -![](../../.gitbook/assets/oem-universal-layout-1.png) - -## Schematic - -The schematic of the OEM baseboard reference is available as a PDF File. - -{% file src="../../.gitbook/assets/oem-universal-schematic.pdf" caption="OEM Schematic" %} - -## Altium Project and Gerber Files - -The Altium Project and Gerber files are also available as a ZIP File. - -{% file src="../../.gitbook/assets/oem-universal-baseboard-ref.zip" caption="OEM Altium Project and Gerber Files" %} - diff --git a/product-info-datasheets/oem/w01.md b/product-info-datasheets/oem/w01.md deleted file mode 100644 index d0c40df..0000000 --- a/product-info-datasheets/oem/w01.md +++ /dev/null @@ -1,35 +0,0 @@ -# W01 - -## ![](../../.gitbook/assets/assets-lil0igdl11z7jos_jpx-lkn7scqkkkb6tqb3uyo-lkn85ios3qzh5brsxk2-w01.png) - -## Datasheet - -The datasheet of the W01 is available as a PDF File. - -{% file src="../../.gitbook/assets/w01-specsheet-1.pdf" caption="W01 Datasheet" %} - -## Pinout - -The pinout of the W01 is available as a PDF File - -{% file src="../../.gitbook/assets/w01-pinout.pdf" caption="W01 Pinout" %} - -![](../../.gitbook/assets/w01-pinout.png) - -## Drawings - -The drawings for the W01 is available as a PDF File. - -{% file src="../../.gitbook/assets/w01-drawing.pdf" caption="W01 Drawings" %} - -{% hint style="info" %} -Please note that the PIN assignments for UART1 \(TX1/RX1\), SPI \(CLK, MOSI, MISO\) and I2C \(SDA, SCL\) are defaults and can be changed in Software. -{% endhint %} - -## Tutorials - -Tutorials on how to the W01 module can be found in the [examples](../../tutorials-and-examples/introduction.md) section of this documentation. The following tutorials might be of specific interest for the W01: - -* [WiFi connection](../../tutorials-and-examples/all/wlan.md) -* [BLE](../../tutorials-and-examples/all/ble.md) - diff --git a/products.md b/products.md deleted file mode 100644 index 48cee97..0000000 --- a/products.md +++ /dev/null @@ -1,78 +0,0 @@ -# Pycom Products - -## Pycom Products - -Below you will find tables of all Pycom products. These tables illustrate the functionality of our various products, their compatibility with each other, as well as what accessories are required to utilise certain functionality. - -## Development Boards - -| Module | WiFi | Bluetooth | LoRa | Sigfox | LTE CAT-M1NB-IoT | -| :--- | :--- | :--- | :--- | :--- | :--- | -| [ WiPy 3.0](product-info-datasheets/development/wipy3.md) | ✔ | ✔ | | | | -| [SiPy](product-info-datasheets/development/sipy.md) | ✔ | ✔ | | ✔ | | -| [GPy](product-info-datasheets/development/gpy.md) | ✔ | ✔ | | | ✔ | -| [LoPy](product-info-datasheets/development/lopy.md) | ✔ | ✔ | ✔ | | | -| [LoPy4](product-info-datasheets/development/lopy4.md) | ✔ | ✔ | ✔ | ✔ | | -| [FiPy](product-info-datasheets/development/fipy.md) | ✔ | ✔ | ✔ | ✔ | ✔ | -| Antennas | [External WiFi/BT Antenna Kit](https://pycom.io/product/external-wifi-antenna/) | [External WiFi/BT Antenna Kit](https://pycom.io/product/external-wifi-antenna/) | [LoRa & Sigfox Antenna Kit](https://pycom.io/product/lora-antenna-kit/) | [LoRa & Sigfox Antenna Kit](https://pycom.io/product/lora-antenna-kit/) | [LTE-M Antenna Kit](https://pycom.io/product/lte-m-antenna-kit/) | - -## Accessories - -| Accessory | [Expansion Board](product-info-datasheets/boards/expansion3.md) | [Pysense](product-info-datasheets/boards/pysense.md) | [Pytrack](product-info-datasheets/boards/pytrack.md) | [Pyscan](product-info-datasheets/boards/pyscan.md) | -| :--- | :--- | :--- | :--- | :--- | - - -| [PyCase](https://pycom.io/product/pycase/) | ✔ | | | | -| :--- | :--- | :--- | :--- | :--- | - - -| [IP67 Case for Expansion Board](https://pycom.io/product/ip67-expansion-board-case/) | ✔ | | | | -| :--- | :--- | :--- | :--- | :--- | - - -| [IP67 Case for Pysense/Pytrack/Pyscan](https://pycom.io/product/ip67-case/) | | ✔ | ✔ | ✔ | -| :--- | :--- | :--- | :--- | :--- | - - -| [IP67 Case \(universal\)](https://pycom.io/product/universal-ip67-case/) | ✔ | ✔ | ✔ | ✔ | -| :--- | :--- | :--- | :--- | :--- | - - -| LiPo Battery \(user-supplied\) | ✔ | ✔ | ✔ | ✔ | -| :--- | :--- | :--- | :--- | :--- | - - -| Micro USB Cable Required \(user-supplied\) | ✔ | ✔ | ✔ | ✔ | -| :--- | :--- | :--- | :--- | :--- | - - - - - - - - - - - - - -
-

Pyscan Modules

-

OLED Module -

-

2MP Camera -

-

Barcode Reader -

-

Fingerprint Scanner -

-

IR Image Sensor -

- 		✔
| OEM Module | [L01/W01 Reference Board](product-info-datasheets/oem/l01_reference.md) | [Universal Reference Board](product-info-datasheets/oem/universal_reference.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) | | ✔ | - diff --git a/pybytes/connect/flash.md b/pybytes/connect/flash.md deleted file mode 100644 index 3970beb..0000000 --- a/pybytes/connect/flash.md +++ /dev/null @@ -1,69 +0,0 @@ -# Connect to Pybytes: Flash Pybytes library manually - -## Connecting a device to Pybytes by flashing Pybytes library manually - -In this section, we will explain to you how to connect your device to Pybytes by flashing Pybytes library manually. - -{% hint style="info" %} -From firmware 1.16.x onwards all Pycom devices come with Pybytes library build-in `/frozen` folder. That means that you can add your device quickly without the need of flashing Pybytes library manually. [Click here for more information.](quick.md) -{% endhint %} - -### Step 1: Download your Pybytes Library - -At the last step of the "Add Device" process: - -![](../../.gitbook/assets/pybyteslib-box-1.gif) - -1. Click on download "Pybytes library" - -![](../../.gitbook/assets/pybytes-library-wizard%20%281%29.png) - -You can also download _Pybytes library_ at the device's settings page: - -2. Navigate to your device in Pybytes; - -3. On your device's page click on settings tab; - -4. Click on the button _Download_ at Pybytes library; - -![](../../.gitbook/assets/pybytes-library-download%20%281%29.gif) - -### Step 2. Flash your device with Pymakr - -{% hint style="info" %} -In case you haven't installed Pymakr plugin, follow [these instructions](../../pymakr-plugin/installation/atom.md). -{% endhint %} - -1. Connect your device to your computer with USB cable. -2. Extract download Pybytes library and open extracted folder with Atom. -3. Get your device serial port: in Pymakr plugin click on _More_ > _get serial ports_ -4. Paste your device's serial port to `pymakr.conf` file: - - ```text - { - "address": "PASTE_YOUR_SERIAL_PORT_HERE", - "username": "micro", - "password": "python", - "sync_folder": "flash" - } - ``` - -5. Checkout your `flash/pybytes_config.json` file. It will be pre-filled with your information from Pybytes - - Like deviceToken or WiFi credentials. You can change e.g. your WiFy password here. - -6. Put your device in [safe boot mode](../../getting-started/programming/safeboot.md). -7. Upload code to your device by clicking on _Upload_ button in Pymakr. - - After all Pybytes library files are uploaded to device, device will restart and will connect to Pybytes. - -{% hint style="info" %} -Pybytes library is written to `/flash` folder and will take precedence over build in firmware libraries in `/frozen` folder. -{% endhint %} - -## Next step: Set up your device's dashboard! - -Now it's time to display data from your device into Pybytes dashboard. - -{% page-ref page="../dashboard.md" %} - diff --git a/pybytes/connect/sigfox/README.md b/pybytes/connect/sigfox/README.md deleted file mode 100644 index 1f2078d..0000000 --- a/pybytes/connect/sigfox/README.md +++ /dev/null @@ -1,40 +0,0 @@ -# Add Sigfox device - -{% hint style="danger" %} -Before you start you need to create Sigfox account. You need Pycom device with Sigfox to get your Sigfox account. [**Follow these instructions**](../../../getting-started/registration/sigfox.md). -{% endhint %} - -## Create Sigfox API credentials - -Once you have you account setup and are logged in Sigfox backend, you need to create API credentials for Pybytes. - -Click on GROUP → <your\_company\_name> → API ACCESS → New - -![](../../../.gitbook/assets/apiaccess%20%281%29.png) - -In the form chose arbitrary _name_, select Profiles `DEVICE MANAGER [R]` and `DEVICE MANAGER [W]`. Then click on Ok. - -![](../../../.gitbook/assets/apiaccessscope.png) - -Copy _Login_ and _Password_ to the clipboard. - -![](../../../.gitbook/assets/apiaccesskeys.png) - -In Pybytes go to Settings → Sigfox API or [follow this link](https://pybytes.pycom.io/settings/sigfox-credentials) then paste in the form. - -![](../../../.gitbook/assets/pybytessigfoxcredentials.png) - -## Sigfox contract types - -### Sigfox DevKit contracts - -Read more how to use Sigfox with [devKit contract](devkit.md). - -{% page-ref page="devkit.md" %} - -### Sigfox custom contracts - -Read more how to use Sigfox with [Custom contract](devkit.md). - -{% page-ref page="custom.md" %} - diff --git a/pybytes/dashboard.md b/pybytes/dashboard.md deleted file mode 100644 index da1ed84..0000000 --- a/pybytes/dashboard.md +++ /dev/null @@ -1,131 +0,0 @@ -# Visualise data from your device - -In this section, we will explain to you how to create widgets for data visualisation and set up your device's dashboard on Pybytes. - -{% hint style="info" %} -We assume that you already have your device connected to Pybytes. In case you haven't, check how to [add your device here](connect/). After your done with that, you can proceed to the next example. -{% endhint %} - -## Step 1: Set up your application \(`main.py`\) - -The first step is to have an application running on your device. The application in this example sends data from a vector every 10 seconds to Pybytes. - -1. Open the `main.py` file on Pymakr; -2. Insert the following code on your `main.py`; - -```python -# Import what is necessary to create a thread -import _thread -from time import sleep - -# Increment index used to scan each point from vector sensors_data -def inc(index, vector): - if index < len(vector)-1: - return index+1 - else: - return 0 - -# Define your thread's behaviour, here it's a loop sending sensors data every 10 seconds -def send_env_data(): - idx = 0 - sensors_data = [0, -0.2, -0.5, -0.7, -0.8, -0.9, -0.9, -0.9, -0.8, -0.6, -0.4, -0.2, 0, 0.3, 0.5, 0.7, 0.8, 0.9, 0.9, 0.9, 0.8, 0.6, 0.4, 0.1] - - while (pybytes): - pybytes.send_virtual_pin_value(False, 1, sensors_data[idx]) - idx = inc(idx, sensors_data) - sleep(10) - -# Start your thread -_thread.start_new_thread(send_env_data, ()) -``` - -3. Upload the code into your device. Now your device is sending data to Pybytes. - -{% hint style="info" %} -In this code, we're calling the function `pybytes.send_virtual_pin_value(persistent, pin, value))` to communicate with Pybytes. This function is part of the Pybytes library, and it has three arguments: `persistent`, `pin` and `value`. - -* `persistent` denotes information that is infrequently accessed and not likely to be modified; -* `pin` represents which virtual pin is receiving data; -* `value` is the value being attributed to that particular pin -{% endhint %} - -## Step 2: Add a signal from your device - -Go to Pybytes. - -1. On `Devices` page select a device; - -![](../.gitbook/assets/01%20%281%29.gif) - -2. On your device's page click on `Data` tab. - -![](../.gitbook/assets/02-1.png) - -3. Click on the `Define New Signal` button. - -![](../.gitbook/assets/03-1.png) - -4. Define the new signal by entering a number, a name, a data type and a unit. Finally, click on the button `Define`. - -![](../.gitbook/assets/04-1.gif) - -5. Your signal was added! - -![](../.gitbook/assets/05%20%281%29.png) - -{% hint style="info" %} -The name and unit are labels used to identify your signal inside Pybytes \(In this example we defined `Sinwave` as the name of the signal and `Rad` as the unit\). - -The signal number has to match the pin number that you defined on `pybytes.send_virtual_pin_value` function call, inside your `main.py` code \(In this example we defined `pin = 1`\); - -The datatype also has to match the variable used as argument on `pybytes.send_virtual_pin_value` function call, inside your `main.py` code \(In this example our variable is a floating number; therefore we defined as a `Float32`\). -{% endhint %} - -## Step 3: Add a widget for the signal - -1. Click on the signal card. - -![](../.gitbook/assets/01.png) - -2. Click on the button `Create a new display`. - -![](../.gitbook/assets/02-1%20%281%29.png) - -3. Select the type of visualisation \(e.g. Bar chart or Line chart\). - -![](../.gitbook/assets/03.gif) - -4. You can adjust the parameters of your widget at `Settings`. After, click on the button `Create`. - -![](../.gitbook/assets/04-1.png) - -5. Your widget was created. Now, add your widget to your device's dashboard. Click on the button `Edit` on your widget. - -![](../.gitbook/assets/05-1.png) - -6. Mark the checkbox `Display on Dashboard` at `Settings`. Finally, click on the button `Save`. - -![](../.gitbook/assets/06.gif) - -7. Click on the tab `Dashboard`. Your widget was successfully added there! - -![](../.gitbook/assets/07.png) - -## Step 4: Organise your dashboard - -1. Click on the button `Organise`. Now the dashboard's grid will enter the edit mode and allow you to resize and reposition its widgets. - -![](../.gitbook/assets/edit-mode%20%281%29.gif) - -2. Resize a widget by clicking on the triangle icon at the bottom right corner of the widget and drag the cursor over the grid. After, click on the button `Save` to save this action. - -![](../.gitbook/assets/02-1.gif) - -3. Change the widget's position by drag-and-dropping it over the grid. After, click on the button `Save` to save this action. - -![](../.gitbook/assets/03-1.gif) - -## Done! - -Now you've learned how to set up your device's dashboard to display data. Also, you can add more widgets to other pins of your device. - diff --git a/pymakr-plugin/installation/README.md b/pymakr-plugin/installation/README.md deleted file mode 100644 index 1781c20..0000000 --- a/pymakr-plugin/installation/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# Installation - -![](../../.gitbook/assets/pymakr-logo-1.png) - -## Pymakr Plugins - -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="atom.md" %} - -{% page-ref page="vscode.md" %} - diff --git a/pymakr-plugin/installation/atom.md b/pymakr-plugin/installation/atom.md deleted file mode 100644 index 396eaa0..0000000 --- a/pymakr-plugin/installation/atom.md +++ /dev/null @@ -1,79 +0,0 @@ -# Atom - -For beginners, users getting started with MicroPython & Pycom as well as Atom text editor users, we recommend the **Pymakr Plugin for Atom**. This section will help you get started using the Atom Text Editor & Pymakr Plugin. - -Please follow these steps to install the Pymakr Plugin: - -1. Ensure that you have Atom installed and open. - -![](../../.gitbook/assets/atom_setup_step_1-1.png) - -2. Navigate to the Install page, via `Atom > Preferences > Install` - -![](../../.gitbook/assets/atom_setup_step_2-1.png) - -3. Search for `Pymakr` and select the official Pycom Pymakr Plugin. - -![](../../.gitbook/assets/atom_setup_step_3-1.png) - -4. You should now see and click the Install button. This will download and install the Pymakr Plugin. - -![](../../.gitbook/assets/atom_setup_step_4-1.png) - -5. That’s it! You’ve installed the Pymakr Plugin for Atom. - -![](../../.gitbook/assets/atom_setup_step_5-1.png) - -## Connecting via Serial USB - -After installing the Pymakr Plugin, you need to take a few seconds to configure it for first time use. Please follow these steps: - -1. Connect your Pycom device to your computer via USB. If you are using an Expansion Board 2.0, and have just finished a firmware upgrade, be sure to **remove the wire between GND and G23** and reset your device by pressing the button. - - Note: you don't need the wire for Expansion Board 3.0 - -2. Open Atom and ensure that the Pymakr Plugin has correctly installed. - -![](../../.gitbook/assets/atom_config_step_2-1.png) - -3. Open the Pymakr console by clicking the `^` button, located in the lower right side of the Atom window. - -![](../../.gitbook/assets/atom_config_step_3%20%281%29.png) - -4. Click, `More` followed by `Get Serial Ports`. This will copy the serial address of your expansion board to your clipboard. - -![](../../.gitbook/assets/atom_config_step_4.png) - -5. Navigate to `Settings > Global Settings` - -![](../../.gitbook/assets/atom_config_step_5.png) - -6. Paste the serial address you copied earlier into the text field `Device Address` - -![](../../.gitbook/assets/atom_config_step_6%20%281%29.png) - -7. Press connect and the Pymakr console should show three arrows `>>>`, indicating that you are connected - -![](../../.gitbook/assets/atom_config_step_7%20%281%29.png) - -These settings can also be applied on a per project basis by clicking `Settings` then `Project Settings`. This will open a JSON file which you can edit to enter your desired settings. - -{% hint style="info" %} -This process is easiest with either a Pycom Expansion Board or a Pytrack/Pysense as the addresses are automatically selected. For external products such as FTDI USB Serial Cables, the serial address may need to be copied manually. Additionally, the reset button on the device may also need to be pressed before a connection message appears. -{% endhint %} - -## Connecting via Telnet - -After installing the Pymakr Plugin, a device may be connected via the telnet interface. Please see the following steps: - -1. Ensure that Pycom device is turned on -2. Connect the host computer to the WiFi Access Point named after your board \(the SSID will be as follows e.g. `lopy-wlan-xxxx`, `wipy-wlan-xxxx`, etc.\). The password is `www.pycom.io`. -3. Follow the steps as above in the "Connecting via Serial USB" section but - - enter `192.168.4.1` as the address. - -4. The default username and password are `micro` and `python`, respectively. -5. Click `Connect` in the Pymakr pane, Pymakr will now connect via telnet. - -![](../../.gitbook/assets/pymakr-plugin-settings-1.png) - diff --git a/pymakr-plugin/installation/vscode.md b/pymakr-plugin/installation/vscode.md deleted file mode 100644 index 053e998..0000000 --- a/pymakr-plugin/installation/vscode.md +++ /dev/null @@ -1,91 +0,0 @@ -# Visual Studio Code - -Pycom also supports Microsoft's Visual Studio Code IDE platform with the Pymakr Plugin. To download Visual Studio Code, navigate to [VS Code](https://code.visualstudio.com/). - -You will also need NodeJS installed on your PC. Please download the latest LTS version available [from the NodeJS website.](https://nodejs.org/) - -Please follow these steps to install the Pymakr VSCode Extension: - -1. Ensure that you have VSCode installed and open. - -![](../../.gitbook/assets/vsc_setup_step_1-1.png) - -2. Navigate to the Extensions page, using the 5th button in the left navigation - -![](../../.gitbook/assets/vsc_setup_step_2-1.png) - -3. Search for `Pymakr` and click the install button next to it. - -![](../../.gitbook/assets/vsc_setup_step_3.png) - -4. Within a few minutes, a reload button should appear. Press it to reload VSCode. - -![](../../.gitbook/assets/vsc_setup_step_4.png) - -5. That’s it! You’ve installed the Pymakr Extension for VSCode - -![](../../.gitbook/assets/vsc_setup_step_5%20%281%29.png) - -## Connecting via Serial USB - -After installing the Pymakr Plugin, you need to take a few seconds to configure it for first time use. Please follow these steps: - -1. Connect your Pycom device to your computer via USB. If you are using an - - Expansion Board, and have just finished a firmware upgrade, be sure to **Remove** - - **the wire between GND and G23** and reset your device by pressing the button. - -2. Open Visual Studio Code and ensure that the Pymakr Plugin has correctly installed. - -![](../../.gitbook/assets/vsc_config_step_1-1.png) - -3. Click `All commands` on the bottom of the Visual Studio Code window - -![](../../.gitbook/assets/vsc_config_step_2-1.png) - -4. In the list that appears, click `Pymakr > Extra > List Serial Ports` - -![](../../.gitbook/assets/vsc_config_step_3-1.png) - -5. This will list the available serial ports. If Pymakr is able to auto-detect which to use, this will be copied to your clipboard. If not please manually copy the correct serial port. - -![](../../.gitbook/assets/vsc_config_step_4.png) - -6. Once again click `All commands`, then click `Pymakr > Global Settings`. This will open a JSON file. Paste the serial address you copied earlier into the field `address` and save the file. - -![](../../.gitbook/assets/vsc_config_step_5-1.png) - -7. Finally close the JSON file, click `All commands`, then `Pymakr > Connect` to connect your device. The Pymakr console should show three arrows `>>>`, indicating that you are connected - -![](../../.gitbook/assets/vsc_config_step_6%20%281%29.png) - -These settings can also be applied on a per project basis by clicking `All commands` then `Pymakr > Project Settings`. This will open a JSON file which you can edit to enter your desired settings for the currently open project. - -{% hint style="info" %} -This process is easiest with either a Pycom Expansion Board or a Pytrack/Pysense as the addresses are automatically selected. For external products such as FTDI USB Serial Cables, the serial address may need to be copied manually. Additionally, the reset button on the device may also need to be pressed before a connection message appears. -{% endhint %} - -## Connecting via Telnet - -After installing the Pymakr Plugin, a device may be connected via the telnet interface. Please see the following steps: - -1. Ensure that Pycom device is turned on -2. Connect the host computer to the WiFi Access Point named after your board - - \(the SSID will be as follows e.g. `lopy-wlan-xxxx`, `wipy-wlan-xxxx`, etc.\). - - The password is `www.pycom.io`. - -3. Follow the steps as above in the "Connecting via Serial USB" section but - - enter `192.168.4.1` as the address. - -4. The default username and password are `micro` and `python`, - - respectively. - -5. Finally close the JSON file, click `All commands`, then `Pymakr > Connect`, - - Pymakr will now connect via telnet. - diff --git a/pymakr-plugin/settings.md b/pymakr-plugin/settings.md deleted file mode 100644 index 3e75c85..0000000 --- a/pymakr-plugin/settings.md +++ /dev/null @@ -1,38 +0,0 @@ -# Settings - -Below you will find a description of the various settings available for Pymakr. - -## address - -This is the address of the Pycom module you want Pymakr can connect to. This can be either a serial port \(e.g `COM1` on windows or `/dev/cu.usbserial-DQ0054ES` on Linux/macOS\) or an IP address \(Telnet\) \(e.g. `192.168.4.1` if connected to the AP created by the Pycom module\). - -## username - -If a IP address was provided for the `address` therefore Pymakr is connecting via Telnet, you will also need to provide a username, the default is `micro`. - -## password - -If an IP address was provided for the address, Pymakr is connecting via Telnet. You will also need to provide a password, the default is `python`. - -## sync\_folder - -If left blank, all directories inside the project will be synced to the device when the user clicks `upload`. If directories are specified, only these directories will be synced, all others will be ignored - -## open\_on\_start - -If set to `true`, the Pymakr console will open and try to connect when the editor is started, or a project is opened. - -## safe\_boot\_on\_upload - -If set to `true`, Pymakr will reboot the connected device into safe-mode before uploading. This is useful if your code uses a lot of RAM causing issues with the upload procedure. - -This feature is only available on modules running firmware version `1.17.0.b1` or higher. - -## sync\_file\_types - -Only files ending with the extensions listed in this setting will be synced to the device when performing an upload. All other files are ignored. By default this is set to include: `py, txt, log, json, xml` - -## ctrl\_c\_on\_connect - -If set to `true`, Pymakr will sent the `ctrl-c` signal to the connected module before uploading. This should stop the script currently running on the device and improve the reliability of the upload process. - diff --git a/pymakr-plugin/toolsfeatures.md b/pymakr-plugin/toolsfeatures.md deleted file mode 100644 index 19f3bb3..0000000 --- a/pymakr-plugin/toolsfeatures.md +++ /dev/null @@ -1,80 +0,0 @@ -# Tools/Features - -## Console \(REPL\) - -MicroPython has an interactive code tool known as the REPL \(Read Evaluate Print Line\). The REPL allows you to run code on your device, line by line. To begin coding, go to the Pymakr Plugin Console and start typing your code. Start by making the LED change colour. - -```python -import pycom # we need this module to control the LED - -pycom.heartbeat(False) # disable the blue blinking -pycom.rgbled(0x00ff00) # make the LED light up green in colour -``` - -You can change the colour by adjusting the hex RGB value. - -```python -pycom.rgbled(0xff0000) # now make the LED light up red in colour -``` - -The console can be used to run any python code, also functions or loops. - -Use `print()` to output contents of variables to the console for you to read. Returned values from functions will also be displayed if they are not caught in a variable. This will not happen for code running from the main or boot files. Here you need to use `print()` to output to the console. - -{% hint style="info" %} -Note that after writing or pasting any indented code like a function or a while loop, the user will have to press enter up to three times to tell MicroPython the code is to be closed \(this is standard MicroPython & Python behaviour\). - -Also be aware that code written into the REPL is not saved after the device is powered off/on again. -{% endhint %} - -## Run - -To test code on a device, create a new `.py` file or open an existing one, type the desired code, save the file and then press the `Run` button. This will run the code directly onto the Pycom board and output the results of the script to the REPL. - -{% hint style="info" %} -Changes made to files won’t be automatically uploaded to the board upon restarting or exiting the `Run` feature, as the Pycom board will not store this code. In order to push the code permanently to a device, use the `Upload` feature. -{% endhint %} - -## Projects - -Pymakr Plugin supports user projects, allowing for pre-configured settings such as default serial address/credentials, files to be ignored and folders to sync. - -## pymakr.conf - -Pymakr Plugin supports local project settings using a file called `pymakr.conf`. This can be used to store the default serial address of a device, which files to ignore and other settings. An example `pymakr.conf` is shown below: - -```javascript -{ - "address": "/dev/cu.usbserial-AB001234", - "username": "micro", - "password": "python", - "sync_folder": "scripts" -} -``` - -## Upload - -The Pymakr Plugins have a feature to sync and upload code to a device. This can be used for both uploading code to a device as well as testing out scripts by running them live on the device. The following steps demonstrate how to use this feature. - -To start using the `Upload` feature, ensure that a project folder has been created for the device. For example, if using the `pymakr.conf` from above, this project folder should be named `scripts`. This folder should have the following structure: - -![](../.gitbook/assets/mp-filestructure%20%281%29.png) - -Library files should be placed into the `lib` folder, certificates into the `cert` folder and so on. The `Upload` button will take the highest level folder \(currently open\) and upload this to the connected Pycom device. The files will be pushed to the device in exactly the same structure as within the code editor's file directory. - -## More - -Clicking the `More` button within the Pymakr Plugin allows for some additional features. See the options below for specific functionality. - -### Get Firmware Version - -Retrieves the firmware version of the Pycom device connected to the Pymakr Plugin instance. - -### Get WiFi AP SSID - -Retrieves the default WiFi Access Point SSID of the Pycom device connected to the Pymakr Plugin instance. - -### Get Serial Ports - -Retrieves the various serial ports that are available to the Pymakr Plugin instance. - diff --git a/pytrack-pysense-pyscan/apireference/README.md b/pytrack-pysense-pyscan/apireference/README.md deleted file mode 100644 index 79e556c..0000000 --- a/pytrack-pysense-pyscan/apireference/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# API Reference - -To simplify usability, APIs for the libraries have been created, abstracting away the low level interactions with the sensors. The next following pages refer to the respective libraries for the Pytrack, Pysense, and Pyscan. - diff --git a/pytrack-pysense-pyscan/apireference/pyscan.md b/pytrack-pysense-pyscan/apireference/pyscan.md deleted file mode 100644 index f47bf79..0000000 --- a/pytrack-pysense-pyscan/apireference/pyscan.md +++ /dev/null @@ -1,145 +0,0 @@ -# Pyscan - -This chapter describes the various libraries which are designed for the Pyscan board. This includes details about the various methods and classes available for each of the Pyscan’s sensors. - -## 3-Axis Accelerometer \(LIS2HH12\) - -Pysense has a 3-Axis Accelerometer that provides outputs for acceleration as well as roll, pitch and yaw. - -### Constructors - -#### class LIS2HH12\(pysense = None, sda = 'P22', scl = 'P21'\) - -Creates a `LIS2HH12` object, that will return values for acceleration, roll, pitch and yaw. Constructor must be passed a Pysense or I2C object to successfully construct. - -### Methods - -#### LIS2HH12.acceleration\(\) - -Read the acceleration from the `LIS2HH12`. Returns a **tuple** with the 3 values of acceleration \(G\). - -#### LIS2HH12.roll\(\) - -Read the current roll from the `LIS2HH12`. Returns a **float** in degrees in the range -180 to 180. - -#### LIS2HH12.pitch\(\) - -Read the current pitch from the `LIS2HH12`. Returns a **float** in degrees in the range -90 to 90. Once the board tilts beyond this range the values will repeat. This is due to a lack of yaw measurement, making it not possible to know the exact orientation of the board. - -## Digital Ambient Light Sensor \(LTR-329ALS-01\) - -Pysense has a dual light sensor that provides outputs for external light levels in lux. See the datasheet for more information about the wavelengths of the two sensors. - -### Constructors - -#### class LTR329ALS01\(pysense = None, sda = 'P22', scl = 'P21', gain = ALS\_GAIN\_1X, integration = ALS\_INT\_100, rate = ALS\_RATE\_500\) - -Creates a `LTR329ALS01` object, that will return values for light in lux. Constructor must be passed a Pysense or I2C object to successfully construct. - -### Methods - -#### LTR329ALS01.light\(\) - -Read the light levels of both `LTR329ALS01` sensors. Returns a **tuple** with two values for light levels in lux. - -### Arguments - -The following arguments may be passed into the constructor. - -* gain: `ALS_GAIN_1X`,`ALS_GAIN_2X`, `ALS_GAIN_4X`, `ALS_GAIN_8X`, `ALS_GAIN_48X`, `ALS_GAIN_96X` -* integration: `ALS_INT_50`, `ALS_INT_100`, `ALS_INT_150`, `ALS_INT_200`, `ALS_INT_250`, `ALS_INT_300`, `ALS_INT_350`, `ALS_INT_400` -* rate: `ALS_RATE_50`, `ALS_RATE_100`, `ALS_RATE_200`, `ALS_RATE_500`, `ALS_RATE_1000`, `ALS_RATE_2000` - -## Pyscan NFC library \(MFRC6300\) - -### Constructors - -#### class MFRC630\(pyscan=None, sda='P22', scl='P21', timeout=None, debug=False\) - -Creates a `MFRC630` object. Constructor must be passed a Pyscan or I2C object to successfully construct. - -### Methods - -#### MFRC630.mfrc630\_cmd\_init\(\) - -Initialise the `MFRC630` with some settings - -#### MFRC630.mfrc630\_cmd\_reset\(\) - -Reset the device. Stops the currently active command and resets device. - -#### MFRC630.mfrc630\_cmd\_idle\(\) - -Set the device into idle mode. Stops the currently active command and return to idle mode. - -#### MFRC630.mfrc630\_cmd\_load\_key\(key\) - -Loads the provided key into the key buffer. - -* `key` Array which holds the MIFARE key, **it is always 6 bytes long** - -#### MFRC630.mfrc630\_MF\_read\_block\(block\_address, dest\) - -Reads a block of memory from an authenticated card. Try to read a block of memory from the card with the appropriate timeouts and error checking. - -* `block_address` The block to read -* `dest` The array in which to write the 16 bytes read from the card - -Returns `0` for failure, otherwise the number of bytes received. - -#### MFRC630.mfrc630\_MF\_auth\(uid, key\_type, block\) - -Perform a MIFARE authentication procedure. This function is a higher-level wrapper around the MF authenticate command. The result of the authentication is checked to identify whether it appears to have succeeded. The key must be loaded into the key buffer with `MFRC630.mfrc630_cmd_load_key(key)`. - -Once authenticated, the authentication MUST be stopped manually by calling the `mfrc630_MF_deauth()` function or otherwise disabling the `Crypto1 ON` bit in the status register. - -* `key_type` The MIFARE key A or B \(`MFRC630_MF_AUTH_KEY_A` or `MFRC630_MF_AUTH_KEY_B`\) to use -* `block` The block to authenticate -* `uid` The authentication procedure required the first four bytes of the card's UID to authenticate - -Returns `0` in case of failure, nonzero in case of success. - -#### MFRC630.mfrc630\_MF\_deauth\(\) - -Disables MIFARE authentication. Disable the `Crypto1` bit from the status register to disable encryption. - -#### MFRC630.mfrc630\_iso14443a\_WUPA\_REQA\(instruction\) - -Send `WUPA` and `REQA`. Returns the response byte, the answer to request `A` byte \(`ATQA`\), or `0` in case of no answer. - -* instruction: `MFRC630_ISO14443_CMD_WUPA`, `MFRC630_ISO14443_CMD_REQA` - -#### MFRC630.mfrc630\_iso14443a\_select\(uid\) - -Performs the `SELECT` procedure to discover a card's UID. This performs the `SELECT` procedure as explained in _ISO14443A_, this determines the UID of the card, if multiple cards are present, a collision will occur, which is handled according to the norm. - -* `uid`: The UID of the card will be stored into this array. - -Returns the length of the UID in bytes \(`4, 7, 10`\), or `0` in case of failure. - -#### MFRC630.print\_debug\(msg\) - -Prints debug statements if `DEBUG` is enabled. - -#### MFRC630.format\_block\(block, length\) - -Prints `block` with `length`. - -#### MFRC630.mfrc630\_format\_block\(data, len\) - -Converts `data` to hexadecimal format. - -* `data` The array to be formatted -* `len` The number of bytes to format - -#### MFRC630.mfrc630\_print\_block\(data, len\) - -Prints the bytes in `data` array in hexadecimal format, separated by spaces using the `mfrc630_format_block` method. - -* `data` The array to be printed -* `len` The number of bytes to print - -{% 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 [Libraries GitHub repository](https://github.com/pycom/pycom-libraries) -{% endhint %} - diff --git a/pytrack-pysense-pyscan/apireference/pysense.md b/pytrack-pysense-pyscan/apireference/pysense.md deleted file mode 100644 index 66345ba..0000000 --- a/pytrack-pysense-pyscan/apireference/pysense.md +++ /dev/null @@ -1,106 +0,0 @@ -# Pysense - -This chapter describes the various libraries which are designed for the Pysense board. This includes details about the various methods and classes available for each of the Pysense’s sensors. - -## 3-Axis Accelerometer \(LIS2HH12\) - -Pysense has a 3-Axis Accelerometer that provides outputs for acceleration as well as roll, pitch and yaw. - -### Constructors - -#### class LIS2HH12\(pysense = None, sda = 'P22', scl = 'P21'\) - -Creates a `LIS2HH12` object, that will return values for acceleration, roll, pitch and yaw. Constructor must be passed a Pysense or I2C object to successfully construct. - -### Methods - -#### LIS2HH12.acceleration\(\) - -Read the acceleration from the `LIS2HH12`. Returns a **tuple** with the 3 values of acceleration \(G\). - -#### LIS2HH12.roll\(\) - -Read the current roll from the `LIS2HH12`. Returns a **float** in degrees in the range -180 to 180. - -#### LIS2HH12.pitch\(\) - -Read the current pitch from the `LIS2HH12`. Returns a **float** in degrees in the range -90 to 90. Once the board tilts beyond this range the values will repeat. This is due to a lack of yaw measurement, making it not possible to know the exact orientation of the board. - -## Digital Ambient Light Sensor \(LTR-329ALS-01\) - -Pysense has a dual light sensor that provides outputs for external light levels in lux. See the datasheet for more information about the wavelengths of the two sensors. - -### Constructors - -#### class LTR329ALS01\(pysense = None, sda = 'P22', scl = 'P21', gain = ALS\_GAIN\_1X, integration = ALS\_INT\_100, rate = ALS\_RATE\_500\) - -Creates a `LTR329ALS01` object, that will return values for light in lux. Constructor must be passed a Pysense or I2C object to successfully construct. - -### Methods - -#### LTR329ALS01.light\(\) - -Read the light levels of both `LTR329ALS01` sensors. Returns a **tuple** with two values for light levels in lux. - -### Arguments - -The following arguments may be passed into the constructor. - -* gain: `ALS_GAIN_1X`,`ALS_GAIN_2X`, `ALS_GAIN_4X`, `ALS_GAIN_8X`, `ALS_GAIN_48X`, `ALS_GAIN_96X` -* integration: `ALS_INT_50`, `ALS_INT_100`, `ALS_INT_150`, `ALS_INT_200`, `ALS_INT_250`, `ALS_INT_300`, `ALS_INT_350`, `ALS_INT_400` -* rate: `ALS_RATE_50`, `ALS_RATE_100`, `ALS_RATE_200`, `ALS_RATE_500`, `ALS_RATE_1000`, `ALS_RATE_2000` - -## Humidity and Temperature Sensor \(SI7006A20\) - -Pysense has a Humidity and Temperature sensor that provides values of relative humidity and external temperature. - -### Constructors - -#### class SI7006A20\(pysense = None, sda = 'P22', scl = 'P21'\) - -Creates a `SI7006A20` object, that will return values for humidity \(%\) and temperature \('C\). Constructor must be passed a Pysense or I2C object to successfully construct. - -### Methods - -#### SI7006A20.humidity\(\) - -Read the relative humidity of the `SI7006A20`. Returns a **float** with the percentage relative humidity. - -#### SI7006A20.temperature\(\) - -Read the external temperature of the `SI7006A20`. Returns a **float** with the temperature. - -## Barometric Pressure Sensor with Altimeter \(MPL3115A2\) - -Pysense has a Barometric Pressure sensor that provides readings for pressure, altitude as well as an additional temperature sensor. - -### Constructors - -#### class MPL3115A2\(pysense = None, sda = 'P22', scl = 'P21', mode = PRESSURE\) - -Creates a `MPL3115A2` object, that will return values for pressure \(Pa\), altitude \(m\) and temperature \('C\). Constructor must be passed a Pysense or I2C object to successfully construct. - -### Methods - -#### MPL3115A2.pressure\(\) - -Read the atmospheric pressure of the `MPL3115A2`. Returns a **float** with the pressure in \(Pa\). - -#### MPL3115A2.altitude\(\) - -Read the altitude of the `MPL3115A2`. Returns a **float** with the altitude in \(m\). - -#### MPL3115A2.temperature\(\) - -Read the temperature of the `MPL3115A2`. Returns a **float** with the temperature in \('C\). - -### Arguments - -The following arguments may be passed into the constructor. - -* mode: `PRESSURE`, `ALTITUDE` - -{% 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 [Libraries GitHub repository](https://github.com/pycom/pycom-libraries) -{% endhint %} - diff --git a/pytrack-pysense-pyscan/apireference/pytrack.md b/pytrack-pysense-pyscan/apireference/pytrack.md deleted file mode 100644 index 0ff52a1..0000000 --- a/pytrack-pysense-pyscan/apireference/pytrack.md +++ /dev/null @@ -1,48 +0,0 @@ -# Pytrack - -This chapter describes the various libraries which are designed for the Pytrack board. This includes details about the various methods and classes available for each of the Pytrack’s sensors. - -## 3-Axis Accelerometer \(LIS2HH12\) - -Pytrack has a 3-Axis Accelerometer that provides outputs for acceleration as well as roll, pitch and yaw. - -### Constructors - -#### class LIS2HH12\(pytrack = None, sda = 'P22', scl = 'P21'\) - -Creates a `LIS2HH12` object, that will return values for acceleration, roll, pitch and yaw. Constructor must be passed a Pytrack or I2C object to successfully construct. - -### Methods - -#### LIS2HH12.acceleration\(\) - -Read the acceleration from the `LIS2HH12`. Returns a **tuple** with the 3 values of acceleration \(G\). - -#### LIS2HH12.roll\(\) - -Read the current roll from the `LIS2HH12`. Returns a **float** in degrees in the range -180 to 180. - -#### LIS2HH12.pitch\(\) - -Read the current pitch from the `LIS2HH12`. Returns a **float** in degrees in the range -90 to 90. Once the board tilts beyond this range the values will repeat. This is due to a lack of yaw measurement, making it not possible to know the exact orientation of the board. - -## GPS with GLONASS \(Quectel L76-L GNSS\) - -Pytrack has a GPS \(with GLONASS\) that provides outputs longitude/latitude, speed and other information about the Pytrack's location. - -### Constructors - -#### class L76GNSS\(pytrack = None, sda = 'P22', scl = 'P21', timeout = None\) - -Creates a `L76GNSS` object, that will return values for longitude and latitude. Constructor must be passed a Pytrack or I2C object to successfully construct. Set the `timeout` to a time period \(in seconds\) for the GPS to search for a lock. If a lock is not found by the time the `timeout` has expired, the `coordinates` method will return `(None, None)`. - -### Methods - -#### L76GNSS.coordinates\(debug = False\) - -Read the longitude and latitude from the `L76GNSS`. Returns a **tuple** with the longitude and latitude. With `debug` set to `True` the output from the GPS is verbose. - -{% 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 [Libraries GitHub repository](https://github.com/pycom/pycom-libraries) -{% endhint %} - diff --git a/pytrack-pysense-pyscan/apireference/sleep.md b/pytrack-pysense-pyscan/apireference/sleep.md deleted file mode 100644 index 9b19b4c..0000000 --- a/pytrack-pysense-pyscan/apireference/sleep.md +++ /dev/null @@ -1,103 +0,0 @@ -# Sleep - -This chapter describes the various methods for sleep and wakeup which are embedded in Pytrack and Pysense libraries. Both Pytrack and Pysense have the same methods, although the appropriate class, either `pytrack` or `pysense`, has to be instantiated. - -## Quick Usage Example - -The following example is also available at [Sleep Wakeup Example Libraries GitHub repository](https://github.com/pycom/pycom-libraries/blob/master/examples/accelerometer_wake/main.py) - -```python -#from pytrack import Pytrack -from pysense import Pysense -from LIS2HH12 import LIS2HH12 -import time - -#py = Pytrack() -py = Pysense() - -# display the reset reason code and the sleep remaining in seconds -# possible values of wakeup reason are: -# WAKE_REASON_ACCELEROMETER = 1 -# WAKE_REASON_PUSH_BUTTON = 2 -# WAKE_REASON_TIMER = 4 -# WAKE_REASON_INT_PIN = 8 - -print("Wakeup reason: " + str(py.get_wake_reason())) -print("Approximate sleep remaining: " + str(py.get_sleep_remaining()) + " sec") -time.sleep(0.5) - -# enable wakeup source from INT pin -py.setup_int_pin_wake_up(False) - -acc = LIS2HH12() - -# enable activity and also inactivity interrupts, using the default callback handler -py.setup_int_wake_up(True, True) - -# set the acceleration threshold to 2000mG (2G) and the min duration to 200ms -acc.enable_activity_interrupt(2000, 200) - -# go to sleep for 5 minutes maximum if no accelerometer interrupt happens -py.setup_sleep(300) -py.go_to_sleep() -``` - -## Methods - -#### pytrack.get\_sleep\_remaining\(\) - -In the event of a sleep session that was awoken by an asynchronous event \(Accelerometer, INT pin or Reset button\) the approximate sleep remaining interval \(expressed in **seconds**\) can be found out. The user has to manually use `setup_sleep()` to configure the next sleep interval. - -#### pytrack.get\_wake\_reason\(\) - -Returns the last wakeup reason. Possible values are: - -```text -# WAKE_REASON_ACCELEROMETER = 1 # Accelerometer activity/inactivity detection -# WAKE_REASON_PUSH_BUTTON = 2 # Pytrack/Pysense reset buttom -# WAKE_REASON_TIMER = 4 # Normal timeout of the sleep interval -# WAKE_REASON_INT_PIN = 8 # INT pin -``` - -_Note: the_ `WAKE_REASON_INT_PIN` _can be used if the_ `PIC_RC1` _pin \(pin\#6 on External IO Header\) is toggled._ - -As in the above example, this method should be called at the beginning of the script, to find out the reset \(wakeup\) reason. - -#### pytrack.go\_to\_sleep\(\[gps=True\]\) - -Puts the board in sleep mode, for the duration, which has to be set previously with `pytrack.setup_sleep(timout_sec)`. The optional boolean parameter sets the GPS state during sleep. - -MicroPython code, which is after this function, is not executed, as wakeup will restart MicroPython. - -#### pytrack.setup\_int\_wake\_up\(rising, falling\]\) - -Enables as wakeup source, the accelerometer INT pin \(PIC - RA5\). The boolean parameters will indicate rising edge \(activity detection\) and/or falling edge \(inactivity detection\) is configured. - -**The accelerometer \(class** `LIS2HH12`**\)** has to be also configured for a certain acceleration threshold and duration. Code snippet: - -```python -from pytrack import Pytrack -from LIS2HH12 import LIS2HH12 - -py = Pytrack() -acc = LIS2HH12() - -# enable activity and also inactivity interrupts, using the default callback handler -py.setup_int_wake_up(True, True) - -# set the acceleration threshold to 2000mG (2G) and the min duration to 200ms -acc.enable_activity_interrupt(2000, 200) -``` - -#### pytrack.setup\_int\_pin\_wake\_up\(\[rising\_edge = True\]\) - -Enables as wakeup source, the INT pic \(PIC - RC1, pin\#6 on External IO Header\). Either rising or falling edge has to be set, by default it's rising edge. - -#### pytrack.setup\_sleep\(time\_seconds\) - -Sets the sleep interval, specified in seconds. The actual sleep will be started by calling `go_to_sleep()` method. - -{% 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 [Libraries GitHub repository](https://github.com/pycom/pycom-libraries) -{% endhint %} - diff --git a/pytrack-pysense-pyscan/installation/README.md b/pytrack-pysense-pyscan/installation/README.md deleted file mode 100644 index 841cde4..0000000 --- a/pytrack-pysense-pyscan/installation/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# Installing Software - -As the development for these devices are on going with additional features being added, every week, it is essential to ensure you frequently check for updates on the Pytrack/Pysense/Pyscan. As well as updating the device firmware, it is important to check the [GitHub repository](https://github.com/pycom/pycom-libraries) for the respective library files as they as also being updated, to include additional features/functionality. - diff --git a/pytrack-pysense-pyscan/installation/drivers.md b/pytrack-pysense-pyscan/installation/drivers.md deleted file mode 100644 index e1bfbfe..0000000 --- a/pytrack-pysense-pyscan/installation/drivers.md +++ /dev/null @@ -1,46 +0,0 @@ -# Installing Drivers - Windows 7 - -Pytrack and Pysense will work out of the box for Windows 8/10/+, macOS as well as Linux. If using Windows 7, drivers to support the boards will need to be installed. - -Please follow the instructions below to install the required drivers. - -## Download - -Please download the driver software from the link below. - -[Pytrack/Pysense/Pyscan/Expansion Board 3 Driver](https://github.com/pycom/pycom-documentation/blob/master/pytrackpysense/installation/pycom.inf) - -## 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) - diff --git a/pytrack-pysense-pyscan/installation/firmware.md b/pytrack-pysense-pyscan/installation/firmware.md deleted file mode 100644 index 1e354c1..0000000 --- a/pytrack-pysense-pyscan/installation/firmware.md +++ /dev/null @@ -1,150 +0,0 @@ -# Updating Firmware - -To update the firmware on the Pysense/Pytrack/Pyscan/Expansion Board v3, please see the following instructions. The firmware of Pysense/Pytrack/Pyscan/Expansion Board v3 can be updated via the USB port using the terminal tool, `DFU-util`. - -The latest firmware DFU file can be downloaded from the links below: - -* [Pytrack DFU](https://software.pycom.io/findupgrade?key=pytrack.dfu&type=all&redirect=true) -* [Pysense DFU](https://software.pycom.io/findupgrade?key=pysense.dfu&type=all&redirect=true) -* [Expansion Board DFU](https://software.pycom.io/findupgrade?key=expansion3.dfu&type=all&redirect=true) - -While in the normal, application mode, the Pysense/Pytrack/Pyscan/Expansion Board v3 require a Serial USB CDC driver, in DFU, bootloader mode, the DFU driver is required. Below, the USB Product ID is depicted for each case. - -| Board | DFU bootloader \(update mode\) | Application firmware \(normal mode\) | -| :--- | :--- | :--- | -| Pytrack | `0xF014` | `0xF013` | -| Pysense | `0xF011` | `0xF012` | -| Pyscan | `0xEF37` | `0xEF38` | -| Expansion Board v3 | `0xEF99` | `0xEF98` | - -_Note: USB Vendor ID is always_ `0x04D8`_._ - -## Installing the DFU-util Tools - -### macOS - -If using `homebrew`: - -```bash -$ brew install dfu-util -``` - -If using `MacPorts`: - -```bash -port install libusb dfu-util -``` - -### Linux - -Ubuntu or Debian: - -```bash -$ sudo apt-get install dfu-util -``` - -Fedora: - -```bash -$ sudo yum install dfu-util -``` - -Arch: - -```bash -$ sudo pacman -Sy dfu-util -``` - -### Windows - -* [DFU-util v0.9](http://dfu-util.sourceforge.net/releases/dfu-util-0.9-win64.zip) – Tool to upload the firmware to the Pytrack/Pysense -* [Zadig](http://zadig.akeo.ie/) – Installer tool for the Pytrack/Pysense board DFU Firmware - -To uploaded the latest DFU firmware to the Pytrack/Pysense, **first install the DFU drivers** to the host computer. Open Zadig and select `libusbK` as the driver. - -To install the drivers, the Pytrack/Pysense board must be in DFU-mode: - -1. Disconnect the USB cable -2. Hold down the button on the shield -3. Connect the USB cable -4. Keep the button pressed for at least one second -5. Release the button. When the board is connected in DFU-mode, it will be in this state for 7 seconds. -6. Click the`“Install Driver` button immediately. If the driver was unsuccessful, repeat from step 1. - * _Here the USB ID has to be the DFU-bootloader one \(_`0xF014`_for Pytrack or_ `0xF011` _for Pysense\)._ - * _This is a successful DFU driver installation for Pytrack:_ - -![](../../.gitbook/assets/pytrack_dfu_mode_zadig.png) - -Open the command prompt and navigate to the directory where the DFU-util and the firmware was downloaded \(must be in same directory\). Repeat the procedure to get the board in DFU-mode and run the command below but replace `X.X.X` with the firmware version and replace Pysense with Pytrack if it is the Pytrack that is to be updated \(e.g: `pytrack_0.0.8.dfu`\): - -```bash -dfu-util-static.exe -D pysense_X.X.X.dfu -``` - -If the update was successful, a message,"Done!" should appear in the bottom of the command prompt. - -**Double-check Serial USB \(CDC\) driver is installed in Application mode:** if, by mistake, the `libusbk` driver was installed while the USB ID is the Application mode \(`0xF013` for Pytrack or `0xF012` for Pysense\), then the `Serial USB (CDC)` driver has to be installed for application mode. This will allow Windows to allocate a COM port, which is required for REPL console. - -![](../../.gitbook/assets/pytrack_app_mode_zadig.png) - -## Using DFU-util with Pytrack, Pysense and Expansion Board v3 - -To enter update mode follow these steps: - -1. Unplug the device -2. Press the button and keep it held \(on the Expansion Board the `S1` button\) -3. Plug in the USB cable to the host computer and wait 1 second before releasing the button -4. After this you will have approximately 7 seconds to run the DFU-util tool - -### macOS and Linux: - -```bash -$ dfu-util -D pytrack_0.0.8.dfu -``` - -{% hint style="info" %} -You might need to run `dfu-util` as `sudo`. In that case, you will need to enter your password. -{% endhint %} - -An output, similar to the one below, will appear upon successful installation: - -```bash -dfu-util 0.9 - -Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. -Copyright 2010-2016 Tormod Volden and Stefan Schmidt -This program is Free Software and has ABSOLUTELY NO WARRANTY -Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ - -Match vendor ID from file: 04d8 -Match product ID from file: f014 -Opening DFU capable USB device... -ID 04d8:f014 -Run-time device DFU version 0100 -Claiming USB DFU Runtime Interface... -Determining device status: state = dfuIDLE, status = 0 -dfu-util: WARNING: Runtime device already in DFU state ?!? -Claiming USB DFU Interface... -Setting Alternate Setting #0 ... -Determining device status: state = dfuIDLE, status = 0 -dfuIDLE, continuing -DFU mode device DFU version 0100 -Device returned transfer size 64 -Copying data from PC to DFU device -Download [=========================] 100% 16384 bytes -Download done. -state(2) = dfuIDLE, status(0) = No error condition is present -Done! -``` - -#### Debugging - -Using `lsusb` command, the Pytrack/Pysense device should be visible in both normal and bootloader modes. - -For exemple, a Pytrack board is visible as either: - -* `Bus 020 Device 004: ID 04d8:f014 Microchip Technology Inc. Application Specific Device` - * this is bootloader mode \(`f014` is USB PID\), active just for 7-8 seconds, if the reset button was just pressed before plugging USB connector. -* `Bus 020 Device 005: ID 04d8:f013 Microchip Technology Inc. Pytrack Serial: Pyabcde0` - * this is normal, application mode \(`f013` is USB PID\), this means the bootloader verified application partition and it boot-up correctly. - diff --git a/pytrack-pysense-pyscan/installation/libraries.md b/pytrack-pysense-pyscan/installation/libraries.md deleted file mode 100644 index 235a667..0000000 --- a/pytrack-pysense-pyscan/installation/libraries.md +++ /dev/null @@ -1,40 +0,0 @@ -# Installing Libraries - -To utilise the sensors on the Pytrack and Pysense, Pycom has written libraries to make reading to/from the various sensors accessible via an API. These libraries reside at the Pycom GitHub repository and the latest versions can be found under the releases page. - -[GitHub Repository](https://github.com/pycom/pycom-libraries) - -Download the repository as a `.zip` file, navigate to the correct device \(Pysense/Pytrack\), extract the files and then upload the desired files to the device in the instructions below. - -## Uploading the Libraries to a Device - -These libraries should be uploaded to a device \(LoPy, SiPy, WiPy 2.0, etc.\) in the same process as a standard MicroPython library. The various `.py` files should be placed into the `/lib` folder on the device. For example, if using the Pysense and the user wishes to enable the only Accelerometer and the Light Sensor, they should place the following `.py` files into the device's `/lib` folder: - -```text -- pysense.py -- LIS2HH12.py -- LTR329ALS01.py -``` - -Add as many or as few of the libraries that are required. - -In addition to the Pysense or Pytrack specific libraries, you also need to upload the `pycoproc.py` file from the `_lib/pycoproc_` folder inside the libraries archive. - -{% hint style="info" %} -The Pytrack and Pysense boards behave the same as the Expansion Board. `Upload`, `Run` and upload code to Pycom modules via the Pymakr Plugin, in exactly the same process. -{% endhint %} - -## Importing/Using the Libraries - -Once the libraries are uploaded to the device, they can be used/imported as a typical MicroPython library would be. For example, importing and using the light sensor on the Pysense: - -```python -from pysense import Pysense -from LTR329ALS01 import LTR329ALS01 - -py = Pysense() -lt = LTR329ALS01(py) - -print(lt.light()) -``` - diff --git a/pytrack-pysense-pyscan/introduction.md b/pytrack-pysense-pyscan/introduction.md deleted file mode 100644 index dc442c2..0000000 --- a/pytrack-pysense-pyscan/introduction.md +++ /dev/null @@ -1,74 +0,0 @@ -# Introduction - -In addition to the Expansion Board, Pycom also offers three additional sensor boards, which are ideal for quickly building a fully functioning IoT solution! Whether the application is environment sensing or asset tracking, these additional boards support a variety of sensors. - -## Pytrack - -Pytrack is a location enabled version of the Expansion Board, intended for use in GPS applications such as asset tracking or monitoring. - -![](../.gitbook/assets/pytrack%20%281%29.png) - -### Features & Hardware - -The Pytrack is has a number of features including GPS, 3-Axis Accelerometer and Battery Charger. See the list below for detailed specifics about each sensor, including datasheets. - -* Serial USB -* 3-Axis Accelerometer \([LIS2HH12](apireference/pytrack.md#3-axis-accelerometer-lis-2-hh-12)\) -* Battery Charger \(BQ24040 with JST connector\) -* GPS and GLONASS \([L76-L](apireference/pytrack.md#gps-with-glonass-quectel-l-76-l-gnss)\) -* MicroSD Card Reader - -All of the included sensors are connected to the Pycom device via the I2C interface. These pins are located at `P22` \(SDA\) and `P21` \(SCL\). - -You can find the datasheet and more info here: - -{% page-ref page="../product-info-datasheets/boards/pytrack.md" %} - -## Pysense - -Pysense is a sensor packed version of the Expansion Board, intended for use in environment sensing applications such as temperature, humidity monitoring, and light sensing. - -![](../.gitbook/assets/pysense%20%281%29.png) - -### Features & Hardware - -The Pysense is packed with a number of sensors and hardware, see the list below for detailed specifics about each sensor, including datasheets. - -* Serial USB -* 3-Axis Accelerometer \([LIS2HH12](apireference/pysense.md#3-axis-accelerometer-lis-2-hh-12)\) -* Battery Charger \(BQ24040 with JST connector\) -* Digital Ambient Light Sensor \([LTR-329ALS-01](apireference/pysense.md#digital-ambient-light-sensor-ltr-329-als-01)\) -* Humidity and Temperature Sensor \([SI7006-A20](apireference/pysense.md#humidity-and-temperature-sensor-si-7006-a20)\) -* Barometric Pressure Sensor with Altimeter \([MPL3115A2](apireference/pysense.md#barometric-pressure-sensor-with-altimeter-mpl-3115-a2)\) -* MicroSD Card Reader - -All of the included sensors are connected to the Pycom device via the I2C interface. These pins are located at `GPI09` \(SDA\) and `GPI08` \(SCL\). - -You can find the datasheet and more info here: - -{% page-ref page="../product-info-datasheets/boards/pysense.md" %} - -## Pyscan - -Pyscan is a RFID-NFC enabled version of the Expansion Board, intended for use in scanning applications, such as RFID/NFC readers. - -![](../.gitbook/assets/pyscan-new%20%281%29.png) - -### Features & Hardware - -The Pyscan is packed with a number of sensors and hardware, see the list below for detailed specifics about each sensor, including datasheets. - -* 3-Axis Accelerometer \([LIS2HH12](apireference/pyscan.md#3-axis-accelerometer-lis-2-hh-12)\) -* Digital Ambient Light Sensor \([LTR-329ALS-01](apireference/pyscan.md#digital-ambient-light-sensor-ltr-329-als-01)\) -* RFID-NFC Chip \([MFRC63002HN](apireference/pyscan.md#pyscan-nfc-library-mfrc-6300)\) -* Serial USB -* Battery Charger \(BQ24040 with JST connector\) -* MicroSD Card Reader -* Ultra low power operation \(~1uA in deep sleep\) - -All of the included sensors are connected to the Pycom device via the I2C interface. These pins are located at `P22` \(SDA\) and `P21` \(SCL\). - -You can find the datasheet and more info here: - -{% page-ref page="../product-info-datasheets/boards/pyscan.md" %} - diff --git a/tutorials-and-examples/all/README.md b/tutorials-and-examples/all/README.md deleted file mode 100644 index 5a8d26a..0000000 --- a/tutorials-and-examples/all/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# All Pycom Device Examples - -This section contains generic examples that will work across all Pycom devices and Expansion Boards. - diff --git a/tutorials-and-examples/all/adc.md b/tutorials-and-examples/all/adc.md deleted file mode 100644 index 8a86ac4..0000000 --- a/tutorials-and-examples/all/adc.md +++ /dev/null @@ -1,35 +0,0 @@ -# ADC - -This example is a simple ADC sample. For more information please see [`ADC`](../../firmware-and-api-reference/pycom/machine/adc.md). - -```python -from machine import ADC -adc = ADC(0) -adc_c = adc.channel(pin='P13') -adc_c() -adc_c.value() -``` - -## Calibration - -Currently the ESP32's ADC is not calibrated from the factory. This means it must be calibrated each time you wish to use it. To do this you must firstly measure the internal voltage reference. The following code will connect the 1.1v reference to `P22` - -```python -from machine import ADC -adc = ADC() - -# Output Vref of P22 -adc.vref_to_pin('P22') -``` - -Now that the voltage reference is externally accessible you should measure it with the most accurate voltmeter you have access to. Note down the reading in millivolts, e.g. `1120`. To disconnect the 1.1v reference from `P22` please reset your module. You can now calibrate the ADC by telling it the true value of the internal reference. You should then check your calibration by connecting the ADC to a known voltage source. - -```python -# Set calibration - see note above -adc.vref(1100) - -# Check calibration by reading a known voltage -adc_c = adc.channel(pin='P16', attn=ADC.ATTN_11DB) -print(adc_c.voltage()) -``` - diff --git a/tutorials-and-examples/all/aws.md b/tutorials-and-examples/all/aws.md deleted file mode 100644 index 21b96fe..0000000 --- a/tutorials-and-examples/all/aws.md +++ /dev/null @@ -1,198 +0,0 @@ -# AWS - -The AWS IoT platform enables devices to connect to the Amazon cloud and lets applications in the cloud interact with Internet-connected things. Common IoT applications either collect and process telemetry from devices or enable users to control a device remotely. Things report their state by publishing messages, in JSON format, on MQTT topics. - -For more information see this [PDF File](http://docs.aws.amazon.com/iot/latest/developerguide/iot-dg.pdf). - -## Getting Started with AWS IoT - -### Creating the message broker \(Amazon website\): - -* Sign in to the [AWS Management Console](https://aws.amazon.com/console/) -* Navigate to the IoT Console by clicking on the [AWS IoT link](https://github.com/pycom/pycom-docs/tree/37661883902849b1a931ee273a23ae8e0f3d773e/img/aws-1.png) -* In the left navigation pane, choose [Register/Manage](https://github.com/pycom/pycom-docs/tree/37661883902849b1a931ee273a23ae8e0f3d773e/img/aws-2.png) -* Click on the create button, give your [device a name and press create](https://github.com/pycom/pycom-docs/tree/37661883902849b1a931ee273a23ae8e0f3d773e/img/aws-3.png) -* Click on the device that has been created -* On the Details page, in the left navigation pane, choose [Security](https://github.com/pycom/pycom-docs/tree/37661883902849b1a931ee273a23ae8e0f3d773e/img/aws-4.png) -* On the Certificates page, choose Create certificate -* Download all the certificates, then press the Activate and the Attach a Policy buttons. [See image](https://github.com/pycom/pycom-docs/tree/37661883902849b1a931ee273a23ae8e0f3d773e/img/aws-5.png) -* Click on the Create New Policy button -* On the [Create Policy](https://github.com/pycom/pycom-docs/tree/37661883902849b1a931ee273a23ae8e0f3d773e/img/aws-6.png) page, choose a policy name and the actions to authorise. -* Go to the certificates page, click on the three dots of your certificate and attach the policy to the certificate as shown in the [diagram](https://github.com/pycom/pycom-docs/tree/37661883902849b1a931ee273a23ae8e0f3d773e/img/aws-7.png) - -### Setting up the device \(Pycom device\): - -* Download the latest sample code from the Pycom [GitHub Repository](https://github.com/pycom/aws-pycom). -* Connect to the device via FTP and put the root CA certificate, the client certificate \(`*.pem.crt`\) and the private key \(`*.private.pem.key`\) in the `/flash/cert` folder. -* Update the config file with your WiFi settings, the [AWS Host](https://github.com/pycom/pycom-docs/tree/37661883902849b1a931ee273a23ae8e0f3d773e/img/aws-8.png) and the certificate paths. -* Put the `config.py` and the `main.py` in the device flash - -### Configuration \(`config.py`\): - -This file contains the WiFi, certificate paths and application specific settings that need to be updated by the user. - -```python -# WiFi configuration -WIFI_SSID = 'my_wifi_ssid' -WIFI_PASS = 'my_wifi_password' - -# AWS general configuration -AWS_PORT = 8883 -AWS_HOST = 'aws_host_url' -AWS_ROOT_CA = '/flash/cert/aws_root.ca' -AWS_CLIENT_CERT = '/flash/cert/aws_client.cert' -AWS_PRIVATE_KEY = '/flash/cert/aws_private.key' - -################## Subscribe / Publish client ################# -CLIENT_ID = 'PycomPublishClient' -TOPIC = 'PublishTopic' -OFFLINE_QUEUE_SIZE = -1 -DRAINING_FREQ = 2 -CONN_DISCONN_TIMEOUT = 10 -MQTT_OPER_TIMEOUT = 5 -LAST_WILL_TOPIC = 'PublishTopic' -LAST_WILL_MSG = 'To All: Last will message' - -####################### Shadow updater ######################## -#THING_NAME = "my thing name" -#CLIENT_ID = "ShadowUpdater" -#CONN_DISCONN_TIMEOUT = 10 -#MQTT_OPER_TIMEOUT = 5 - -####################### Delta Listener ######################## -#THING_NAME = "my thing name" -#CLIENT_ID = "DeltaListener" -#CONN_DISCONN_TIMEOUT = 10 -#MQTT_OPER_TIMEOUT = 5 - -####################### Shadow Echo ######################## -#THING_NAME = "my thing name" -#CLIENT_ID = "ShadowEcho" -#CONN_DISCONN_TIMEOUT = 10 -#MQTT_OPER_TIMEOUT = 5 -``` - -### Subscibe / Publish \(`main.py`\) - -To subscribe to a topic: - -* Go to the AWS Iot page, click on manage and choose your device -* From the left hand side, choose Activity and then click MQTT client. -* Choose the [topic name](https://github.com/pycom/pycom-docs/tree/37661883902849b1a931ee273a23ae8e0f3d773e/img/aws-9.png) you entered in the configuration file. -* Messages should be published as shown in the [diagram](https://github.com/pycom/pycom-docs/tree/37661883902849b1a931ee273a23ae8e0f3d773e/img/aws-10.png) - -```python -# user specified callback function -def customCallback(client, userdata, message): - print("Received a new message: ") - print(message.payload) - print("from topic: ") - print(message.topic) - print("--------------\n\n") - -# configure the MQTT client -pycomAwsMQTTClient = AWSIoTMQTTClient(config.CLIENT_ID) -pycomAwsMQTTClient.configureEndpoint(config.AWS_HOST, config.AWS_PORT) -pycomAwsMQTTClient.configureCredentials(config.AWS_ROOT_CA, config.AWS_PRIVATE_KEY, config.AWS_CLIENT_CERT) - -pycomAwsMQTTClient.configureOfflinePublishQueueing(config.OFFLINE_QUEUE_SIZE) -pycomAwsMQTTClient.configureDrainingFrequency(config.DRAINING_FREQ) -pycomAwsMQTTClient.configureConnectDisconnectTimeout(config.CONN_DISCONN_TIMEOUT) -pycomAwsMQTTClient.configureMQTTOperationTimeout(config.MQTT_OPER_TIMEOUT) -pycomAwsMQTTClient.configureLastWill(config.LAST_WILL_TOPIC, config.LAST_WILL_MSG, 1) - -#Connect to MQTT Host -if pycomAwsMQTTClient.connect(): - print('AWS connection succeeded') - -# Subscribe to topic -pycomAwsMQTTClient.subscribe(config.TOPIC, 1, customCallback) -time.sleep(2) - -# Send message to host -loopCount = 0 -while loopCount < 8: - pycomAwsMQTTClient.publish(config.TOPIC, "New Message " + str(loopCount), 1) - loopCount += 1 - time.sleep(5.0) -``` - -### Shadow updater \(`main.py`\) - -```python -# user specified callback functions -def customShadowCallback_Update(payload, responseStatus, token): - if responseStatus == "timeout": - print("Update request " + token + " time out!") - if responseStatus == "accepted": - payloadDict = json.loads(payload) - print("Update request with token: " + token + " accepted!") - print("property: " + str(payloadDict["state"]["desired"]["property"])) - if responseStatus == "rejected": - print("Update request " + token + " rejected!") - -def customShadowCallback_Delete(payload, responseStatus, token): - if responseStatus == "timeout": - print("Delete request " + token + " time out!") - if responseStatus == "accepted": - print("Delete request with token: " + token + " accepted!") - if responseStatus == "rejected": - print("Delete request " + token + " rejected!") - -# configure the MQTT client -pycomAwsMQTTShadowClient = AWSIoTMQTTShadowClient(config.CLIENT_ID) -pycomAwsMQTTShadowClient.configureEndpoint(config.AWS_HOST, config.AWS_PORT) -pycomAwsMQTTShadowClient.configureCredentials(config.AWS_ROOT_CA, config.AWS_PRIVATE_KEY, config.AWS_CLIENT_CERT) - -pycomAwsMQTTShadowClient.configureConnectDisconnectTimeout(config.CONN_DISCONN_TIMEOUT) -pycomAwsMQTTShadowClient.configureMQTTOperationTimeout(config.MQTT_OPER_TIMEOUT) - -# Connect to MQTT Host -if pycomAwsMQTTShadowClient.connect(): - print('AWS connection succeeded') - -deviceShadowHandler = pycomAwsMQTTShadowClient.createShadowHandlerWithName(config.THING_NAME, True) - -# Delete shadow JSON doc -deviceShadowHandler.shadowDelete(customShadowCallback_Delete, 5) - -# Update shadow in a loop -loopCount = 0 -while True: - JSONPayload = '{"state":{"desired":{"property":' + str(loopCount) + '}}}' - deviceShadowHandler.shadowUpdate(JSONPayload, customShadowCallback_Update, 5) - loopCount += 1 - time.sleep(5) -``` - -### Delta Listener \(`main.py`\) - -```python -# Custom Shadow callback -def customShadowCallback_Delta(payload, responseStatus, token): - payloadDict = json.loads(payload) - print("property: " + str(payloadDict["state"]["property"])) - print("version: " + str(payloadDict["version"])) - - # configure the MQTT client -pycomAwsMQTTShadowClient = AWSIoTMQTTShadowClient(config.CLIENT_ID) -pycomAwsMQTTShadowClient.configureEndpoint(config.AWS_HOST, config.AWS_PORT) -pycomAwsMQTTShadowClient.configureCredentials(config.AWS_ROOT_CA, config.AWS_PRIVATE_KEY, config.AWS_CLIENT_CERT) - -pycomAwsMQTTShadowClient.configureConnectDisconnectTimeout(config.CONN_DISCONN_TIMEOUT) -pycomAwsMQTTShadowClient.configureMQTTOperationTimeout(config.MQTT_OPER_TIMEOUT) - -# Connect to MQTT Host -if pycomAwsMQTTShadowClient.connect(): - print('AWS connection succeeded') - -deviceShadowHandler = pycomAwsMQTTShadowClient.createShadowHandlerWithName(config.THING_NAME, True) - -# Listen on deltas -deviceShadowHandler.shadowRegisterDeltaCallback(customShadowCallback_Delta) - -# Loop forever -while True: - time.sleep(1) -``` - diff --git a/tutorials-and-examples/all/ble.md b/tutorials-and-examples/all/ble.md deleted file mode 100644 index c10e93c..0000000 --- a/tutorials-and-examples/all/ble.md +++ /dev/null @@ -1,111 +0,0 @@ -# Bluetooth - -At present, basic BLE functionality is available. More features will be implemented in the near future, such as pairing. This page will be updated in line with these features. - -Full info on `bluetooth` can be found within [Bluetooth page]() of the Firmware API Reference. - -## Scan for BLE Devices - -Scan for all of the advertising devices within range of the scanning device. - -```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 -``` - -## Raw Data from a BLE Device - -A quick usage example that scans and prints the raw data from advertisements. - -```python -from network import Bluetooth - -bluetooth = Bluetooth() -bluetooth.start_scan(-1) # start scanning with no timeout - -while True: - print(bluetooth.get_adv()) -``` - -## Connect to a BLE Device - -Connecting to a device that is sending advertisements. - -```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))) -``` - -## Connect to a BLE Device and Retrieve Data - -Connecting to a device named 'Heart Rate' and receiving data from it’s services. - -```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: - pass - else: - time.sleep(0.050) -``` - -## Retrieve the Name & Manufacturer from a BLE Device - -Using `resolve_adv_data()` to attempt to retrieve the name and manufacturer data from the advertiser. - -```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)) -``` - diff --git a/tutorials-and-examples/all/https.md b/tutorials-and-examples/all/https.md deleted file mode 100644 index 59bcfaa..0000000 --- a/tutorials-and-examples/all/https.md +++ /dev/null @@ -1,28 +0,0 @@ -# HTTPS - -Basic connection using `ssl.wrap_socket()`. - -```python -import socket -import ssl - -s = socket.socket() -ss = ssl.wrap_socket(s) -ss.connect(socket.getaddrinfo('www.google.com', 443)[0][-1]) -``` - -Below is an example using certificates with the blynk cloud. - -Certificate was downloaded from the blynk examples [folder](https://github.com/wipy/wipy/tree/master/examples/blynk) and placed in `/flash/cert/` on the device. - -```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]) -``` - -For more info, check the [`ssl`](../../firmware-and-api-reference/micropython/ussl.md) module in the API reference. - diff --git a/tutorials-and-examples/all/i2c.md b/tutorials-and-examples/all/i2c.md deleted file mode 100644 index ce1e665..0000000 --- a/tutorials-and-examples/all/i2c.md +++ /dev/null @@ -1,94 +0,0 @@ -# I2C - -The following example receives data from a light sensor using I2C. Sensor used is the BH1750FVI Digital Light Sensor. - -```python -import time -from machine import I2C -import bh1750fvi - -i2c = I2C(0, I2C.MASTER, baudrate=100000) -light_sensor = bh1750fvi.BH1750FVI(i2c, addr=i2c.scan()[0]) - -while(True): - data = light_sensor.read() - print(data) - time.sleep(1) -``` - -## Drivers for the BH1750FVI - -Place this sample code into a file named `bh1750fvi.py`. This can then be imported as a library. - -```python -# Simple driver for the BH1750FVI digital light sensor - -class BH1750FVI: - MEASUREMENT_TIME = const(120) - - def __init__(self, i2c, addr=0x23, period=150): - self.i2c = i2c - self.period = period - self.addr = addr - self.time = 0 - self.value = 0 - self.i2c.writeto(addr, bytes([0x10])) # start continuos 1 Lux readings every 120ms - - def read(self): - self.time += self.period - if self.time >= MEASUREMENT_TIME: - self.time = 0 - data = self.i2c.readfrom(self.addr, 2) - self.value = (((data[0] << 8) + data[1]) * 1200) // 1000 - return self.value -``` - -## Light sensor and LoRa - -This is the same code, with added LoRa connectivity, sending the lux value from the light sensor to another LoRa enabled device. - -```python -import socket -import time -import pycom -import struct -from network import LoRa -from machine import I2C -import bh1750fvi - -LORA_PKG_FORMAT = "!BH" -LORA_CONFIRM_FORMAT = "!BB" - -DEVICE_ID = 1 - -pycom.heartbeat(False) - -lora = LoRa(mode=LoRa.LORA, tx_iq=True, region=LoRa.EU868) -lora_sock = socket.socket(socket.AF_LORA, socket.SOCK_RAW) -lora_sock.setblocking(False) - -i2c = I2C(0, I2C.MASTER, baudrate=100000) -light_sensor = bh1750fvi.BH1750FVI(i2c, addr=i2c.scan()[0]) - -while(True): - msg = struct.pack(LORA_PKG_FORMAT, DEVICE_ID, light_sensor.read()) - lora_sock.send(msg) - - pycom.rgbled(0x150000) - - wait = 5 - while (wait > 0): - wait = wait - 0.1 - time.sleep(0.1) - recv_data = lora_sock.recv(64) - - if (len (recv_data) >= 2): - status, device_id = struct.unpack(LORA_CONFIRM_FORMAT, recv_data) - - if (device_id == DEVICE_ID and status == 200): - pycom.rgbled(0x001500) - wait = 0 - - time.sleep(1) -``` - diff --git a/tutorials-and-examples/all/modbus.md b/tutorials-and-examples/all/modbus.md deleted file mode 100644 index 56c3829..0000000 --- a/tutorials-and-examples/all/modbus.md +++ /dev/null @@ -1,133 +0,0 @@ -# Modbus - -Modbus is a messaging protocol that defines the packet structure for transferring data between devices in a master/slave architecture. The protocol is independent of the transmission medium and is usually transmitted over TCP \(MODBUS TCP\) or serial communication \(MODBUS RTU\). Modbus is intended as a request/reply protocol and delivers services specified by function codes. The function code in the request tells the addressed slave what kind of action to perform. The function codes most commonly supported by devices are listed below. - -| Function Name | Function Code | -| :--- | :--- | -| Read Coils | 0x01 | -| Read Discrete Inputs | 0x02 | -| Read Holding Registers | 0x03 | -| Read Input Registers | 0x04 | -| Write Single Coil | 0x05 | -| Write Single Register | 0x06 | -| Write Multiple Coils | 0x0F | -| Write Multiple Registers | 0x10 | - -For more information on the MODBUS RTU see the following [PDF File](http://www.modbus.org/docs/Modbus_over_serial_line_V1_02.pdf). Information on the MODBUS TCP can be found [here](http://www.modbus.org/docs/Modbus_Messaging_Implementation_Guide_V1_0b.pdf). - -## Pycom Modbus Library - -Python libraries and sample code that support Modbus TCP and Modbus RTU are available at the following [GitHub Repository](https://github.com/pycom/pycom-modbus). To use this library, connect to the target Pycom device via ftp and upload the uModbus folder to `/flash`. A description of the supported function codes is found below. - -### Read Coils - -This function code requests the status \(ON/OFF\) of discrete coils on a remote device. The slave device address, the address of the first coil and the number of coils must be specified in the request. The address of the first coil is 0 and a maximum of 2000 contiguous coils can be read. Python sample code is shown below. - -```python -slave_addr=0x0A -starting_address=0x00 -coil_quantity=100 - -coil_status = modbus_obj.read_coils(slave_addr, starting_address, coil_quantity) -print('Coil status: ' + ' '.join('{:d}'.format(x) for x in coil_status)) -``` - -### Read Discrete Inputs - -This command is used to read the status \(ON/OFF\) of discrete inputs on a remote device. The slave address, the address of the first input, and the quantity of inputs to be read must be specified. The address of the first input is 0 and a maximum of 2000 continuous inputs can be read. The Python sample code is shown below. - -```python -slave_addr=0x0A -starting_address=0x0 -input_quantity=100 - -input_status = modbus_obj.read_discrete_inputs(slave_addr, starting_address, input_quantity) -print('Input status: ' + ' '.join('{:d}'.format(x) for x in input_status)) -``` - -### Read Holding Registers - -This function code is used to read the contents of analogue output holding registers. The slave address, the starting register address, the number of registers to read and the sign of the data must be specified. Register addresses start at 0 and a maximum of 125 continuous registers can be read. - -```python -slave_addr=0x0A -starting_address=0x00 -register_quantity=100 -signed=True - -register_value = modbus_obj.read_holding_registers(slave_addr, starting_address, register_quantity, signed) -print('Holding register value: ' + ' '.join('{:d}'.format(x) for x in register_value)) -``` - -### Read Input Registers - -This command is used to read up to 125 continuous input registers on a remote device. The slave address, the starting register address, the number of input registers and the sign of the data must be specified. The address of the first input registers is 0. - -```python -slave_addr=0x0A -starting_address=0x00 -register_quantity=100 -signed=True - -register_value = modbus_obj.read_input_registers(slave_addr, starting_address, register_quantity, signed) -print('Input register value: ' + ' '.join('{:d}'.format(x) for x in register_value)) -``` - -### Write Single Coil - -This function code is used to write the state of a discrete coil on a remote device. A value of `0xFF00` means the coil should be set to ON, while a value of `0x0000` means the coil should be set to OFF. The Python sample code to set the coil at address `0x00`, to an ON state is shown below. - -```python -slave_addr=0x0A -output_address=0x00 -output_value=0xFF00 - -return_flag = modbus_obj.write_single_coil(slave_addr, output_address, output_value) -output_flag = 'Success' if return_flag else 'Failure' -print('Writing single coil status: ' + output_flag) -``` - -### Write Single Register - -This command is used to write the contents of an analog output holding register on a remote device. The slave address, the register address, the register value, and the signature of the data must be specified. As for all the other commands, the register addresses start from 0. - -```python -slave_addr=0x0A -register_address=0x01 -register_value=-32768 -signed=True - -return_flag = modbus_obj.write_single_register(slave_addr, register_address, register_value, signed) -output_flag = 'Success' if return_flag else 'Failure' -print('Writing single coil status: ' + output_flag) -``` - -### Write Multiple Coils - -This function code is used to set a continuous sequence of coils, in a remote device, to either ON or OFF. The slave address, the starting address of the coils and an array with the coil states must be specified. - -```python -slave_addr=0x0A -starting_address=0x00 -output_values=[1,1,1,0,0,1,1,1,0,0,1,1,1] - -return_flag = modbus_obj.write_multiple_coils(slave_addr, starting_address, output_values) -output_flag = 'Success' if return_flag else 'Failure' -print('Writing multiple coil status: ' + output_flag) -``` - -### Write Multiple Registers - -This command is used to write the contents of a continuous sequence of analogue registers on a remote device. The slave address, the starting register address, the register values, and the signature of the data must be specified. The address of the first register is 0 and a maximum of 125 register values can be written. The Python sample code is shown below. - -```python -slave_addr=0x0A -register_address=0x01 -register_values=[2, -4, 6, -256, 1024] -signed=True - -return_flag = modbus_obj.write_multiple_registers(slave_addr, register_address, register_values, signed) -output_flag = 'Success' if return_flag else 'Failure' -print('Writing multiple register status: ' + output_flag) -``` - diff --git a/tutorials-and-examples/all/mqtt.md b/tutorials-and-examples/all/mqtt.md deleted file mode 100644 index c031536..0000000 --- a/tutorials-and-examples/all/mqtt.md +++ /dev/null @@ -1,43 +0,0 @@ -# MQTT - -MQTT is a lightweight messaging protocol that is ideal for sending small packets of data to and from IoT devices via WiFi. - -The broker used in this example is the [IO Adafruit](https://io.adafruit.com) platform, which is free and allows for tinkering with MQTT. - -Visit [IO Adafruit](https://io.adafruit.com) and create an account. You'll need to get hold of an API Key as well as your credentials. Visit this [guide](https://learn.adafruit.com/adafruit-io/mqtt-api) for more information about MQTT and how to use it with Adafruit's Broker. - -This example will send a message to a topic on the Adafruit MQTT broker and then also subscribe to the same topic, in order to show how to use the subscribe functionality. - -```python -from mqtt import MQTTClient -from network import WLAN -import machine -import time - -def sub_cb(topic, msg): - print(msg) - -wlan = WLAN(mode=WLAN.STA) -wlan.connect("yourwifinetwork", auth=(WLAN.WPA2, "wifipassword"), timeout=5000) - -while not wlan.isconnected(): - machine.idle() -print("Connected to WiFi\n") - -client = MQTTClient("device_id", "io.adafruit.com",user="your_username", password="your_api_key", port=1883) - -client.set_callback(sub_cb) -client.connect() -client.subscribe(topic="youraccount/feeds/lights") - -while True: - print("Sending ON") - client.publish(topic="youraccount/feeds/lights", msg="ON") - time.sleep(1) - print("Sending OFF") - client.publish(topic="youraccount/feeds/lights", msg="OFF") - client.check_msg() - - time.sleep(1) -``` - diff --git a/tutorials-and-examples/all/ota-lorawan.md b/tutorials-and-examples/all/ota-lorawan.md deleted file mode 100644 index 990aced..0000000 --- a/tutorials-and-examples/all/ota-lorawan.md +++ /dev/null @@ -1,5 +0,0 @@ -# OTA update (Lorawan) - -{% hint style="info" %} -Coming soon -{% endhint %} \ No newline at end of file diff --git a/tutorials-and-examples/all/ota.md b/tutorials-and-examples/all/ota.md deleted file mode 100644 index 9e353c4..0000000 --- a/tutorials-and-examples/all/ota.md +++ /dev/null @@ -1,207 +0,0 @@ -# OTA update - -## Overview - -Pycom modules come with the ability to update the devices firmware, while it is still running, we call this an "over the air" \(OTA\) update. The [`pycom`](../../firmware-and-api-reference/pycom/pycom.md) library provides several functions to achieve this. This example will demonstrate how you could potentially use this functionality to update deployed devices. The full source code of this example can be found [here](https://github.com/pycom/pycom-libraries/tree/master/examples/OTA). - -## Method - -Here we will describe one possible update methodology you could use that is implemented by this example. - -Imagine you a smart metering company and you wish to roll out an update for your Pycom based smart meter. These meters usually send data back via LoRa. Unfortunately LoRa downlink messages have a very limited size and several hundred if not thousand would be required to upload a complete firmware image. To get around this you can have your devices sending their regular data via LoRa and when they receive a special command via a downlink message, the devices will connect to a WiFi network. It is unfeasible to ask customers to allow your device to connect to their home network so instead this network could be provided by a vehicle. This vehicle will travel around a certain geographic area in which the devices have been sent the special downlink message to initiate the update. The devices will look for the WiFi network being broadcast by the vehicle and connect. The devices will then connect to a server running on this WiFi network. This server \(also shown in this example\) will generate manifest files that instruct the device on what it should update, and where to get the update data from. - -## Server - -Code available [here](https://github.com/pycom/pycom-libraries/blob/master/examples/OTA/OTA_server.py). - -This script runs a HTTP server on port `8000` that provisions over the air \(OTA\) update manifests in JSON format as well as serving the update content. This script should be run in a directory that contains every version of the end devices code, in the following structure: - -```text - - server directory - |- this_script.py - |- 1.0.0 - | |- flash - | | |- lib - | | | |- lib_a.py - | | |- main.py - | | |- boot.py - | |- sd - | |- some_asset.txt - | |- asset_that_will_be_removed.wav - |- 1.0.1 - | |- flash - | | |- lib - | | | |- lib_a.py - | | | |- new_lib.py - | | |- main.py - | | |- boot.py - | |- sd - | |- some_asset.txt - |- firmware_1.0.0.bin - |- firmware_1.0.1.bin -``` - -The top level directory that contains this script can contain one of two things: - -* Update directory: These should be named with a version number compatible - - with the python LooseVersion versioning scheme - - \([http://epydoc.sourceforge.net/stdlib/distutils.version.LooseVersion-class.html](http://epydoc.sourceforge.net/stdlib/distutils.version.LooseVersion-class.html)\). - - They should contain the entire file system of the end device for the - - corresponding version number. - -* Firmware: These files should be named in the format `firmare_VERSION.bin`, where VERSION is a a version number compatible with the python LooseVersion versioning scheme \([http://epydoc.sourceforge.net/stdlib/distutils.version.LooseVersion-class.html](http://epydoc.sourceforge.net/stdlib/distutils.version.LooseVersion-class.html)\). - - This file should be in the format of the `appimg.bin` created by the Pycom - - firmware build scripts. - -### How to use - -Once the directory has been setup as described above you simply need to start this script using python3. Once started this script will run a HTTP server on port `8000` \(this can be changed by changing the PORT variable\). This server will serve all the files in directory as expected along with one additional special file, `manifest.json`. This file does not exist on the file system but is instead generated when requested and contains the required changes to bring the end device from its current version to the latest available version. You can see an example of this by pointing your web browser at: - -`http://127.0.0.1:8000/manifest.json?current_ver=1.0.0` - -The `current_ver` field at the end of the URL should be set to the current firmware version of the end device. The generated manifest will contain lists of which files are new, have changed or need to be deleted along with SHA1 hashes of the files. Below is an example of what such a manifest might look like: - -```text -{ - "delete": [ - "flash/old_file.py", - "flash/other_old_file.py" - ], - "firmware": { - "URL": "http://192.168.1.144:8000/firmware_1.0.1b.bin", - "hash": "ccc6914a457eb4af8855ec02f6909316526bdd08" - }, - "new": [ - { - "URL": "http://192.168.1.144:8000/1.0.1b/flash/lib/new_lib.py", - "dst_path": "flash/lib/new_lib.py", - "hash": "1095df8213aac2983efd68dba9420c8efc9c7c4a" - } - ], - "update": [ - { - "URL": "http://192.168.1.144:8000/1.0.1b/flash/changed_file.py", - "dst_path": "flash/changed_file.py", - "hash": "1095df8213aac2983efd68dba9420c8efc9c7c4a" - } - ], - "version": "1.0.1b" -} -``` - -The manifest contains the following fields: - -* `delete`: A list of paths to files which are no longer needed -* `firmware`: The URL and SHA1 hash of the firmware image -* `new`: the URL, path on end device and SHA1 hash of all new files -* `update`: the URL, path on end device and SHA1 hash of all files which - - existed before but have changed. - -* `version`: The version number that this manifest will update the client to -* `previous_version`: The version the client is currently on before applying - - this update - -_Note_: The version number of the files might not be the same as the firmware. The highest available version number, higher than the current client version is used for both firmware and files. This may differ between the two. - -In order for the URL's to be properly formatted you are required to send a "host" header along with your HTTP get request e.g: - -```text -GET /manifest.json?current_ver=1.0.0 HTTP/1.0\r\nHost: 192.168.1.144:8000\r\n\r\n -``` - -## Client Library - -A MicroPyton library for interfacing with the server described above is available [here](https://github.com/pycom/pycom-libraries/blob/master/examples/OTA/1.0.0/flash/lib/OTA.py). - -This library is split into two layers. The top level `OTA` class implements all the high level functionality such as parsing the JSON file, making back copies of files being updated incase the update fails, etc. The layer of the library is agnostic to your chosen transport method. Below this is the `WiFiOTA` class. This class implements the actual transport mechanism of how the device fetches the files and update manifest \(via WiFi as the class name suggests\). The reason for this split is so that the high level functionality can be reused regardless of what transport mechanism you end up using. This could be implemented on top of Bluetooth for example, or the sever changed from HTTP to FTP. - -{% hint style="danger" %} -Although the above code is functional, it is provided only as an example of how an end user might implement a OTA update mechanism. It is not 100% feature complete e.g. even though it does backup previous versions of files, the roll back procedure is not implemented. This is left of the end user to do. -{% endhint %} - -## Example - -Below is am example implementing the methodology previously explained in this tutorial to initiate an OTA update. - -{% hint style="info" %} -The example below will only work on a Pycom device with LoRa capabilities. If want to test it out on a device without LoRa functionality then simply comment out any code relating to LoRa. Leaving just the `WiFiOTA` initialisation and they `ota.connect()` and `ota.update()` -{% endhint %} - -```python -from network import LoRa, WLAN -import socket -import time -from OTA import WiFiOTA -from time import sleep -import pycom -import ubinascii - -from config import WIFI_SSID, WIFI_PW, SERVER_IP - -# Turn on GREEN LED -pycom.heartbeat(False) -pycom.rgbled(0xff00) - -# Setup OTA -ota = WiFiOTA(WIFI_SSID, - WIFI_PW, - SERVER_IP, # Update server address - 8000) # Update server port - -# Turn off WiFi to save power -w = WLAN() -w.deinit() - -# Initialise LoRa in LORAWAN mode. -lora = LoRa(mode=LoRa.LORAWAN, region=LoRa.EU868) - -app_eui = ubinascii.unhexlify('70B3D57ED0008CD6') -app_key = ubinascii.unhexlify('B57F36D88691CEC5EE8659320169A61C') - -# 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...') - -# 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 blocking -# (waits for the data to be sent and for the 2 receive windows to expire) -s.setblocking(True) - -while True: - # send some data - s.send(bytes([0x04, 0x05, 0x06])) - - # make the socket non-blocking - # (because if there's no data received it will block forever...) - s.setblocking(False) - - # get any data received (if any...) - data = s.recv(64) - - # Some sort of OTA trigger - if data == bytes([0x01, 0x02, 0x03]): - print("Performing OTA") - # Perform OTA - ota.connect() - ota.update() - - sleep(5) -``` - diff --git a/tutorials-and-examples/all/owd.md b/tutorials-and-examples/all/owd.md deleted file mode 100644 index 5f89d21..0000000 --- a/tutorials-and-examples/all/owd.md +++ /dev/null @@ -1,246 +0,0 @@ -# Onewire Driver - -This tutorial explains how to connect and read data from a DS18x20 temperature sensor. The onewire library is also available at the [pycom-libraries](https://github.com/pycom/pycom-libraries/tree/master/lib/onewire) GitHub Repository. - -## Basic usage - -```python -import time -from machine import Pin -from onewire import DS18X20 -from onewire import OneWire - -# DS18B20 data line connected to pin P10 -ow = OneWire(Pin('P10')) -temp = DS18X20(ow) - -while True: - print(temp.read_temp_async()) - time.sleep(1) - temp.start_conversion() - time.sleep(1) -``` - -## Library - -```python -#!/usr/bin/env python3 - -""" -OneWire library for MicroPython -""" - -import time -import machine - -class OneWire: - CMD_SEARCHROM = const(0xf0) - CMD_READROM = const(0x33) - CMD_MATCHROM = const(0x55) - CMD_SKIPROM = const(0xcc) - - def __init__(self, pin): - self.pin = pin - self.pin.init(pin.OPEN_DRAIN, pin.PULL_UP) - - def reset(self): - """ - Perform the onewire reset function. - Returns True if a device asserted a presence pulse, False otherwise. - """ - sleep_us = time.sleep_us - disable_irq = machine.disable_irq - enable_irq = machine.enable_irq - pin = self.pin - - pin(0) - sleep_us(480) - i = disable_irq() - pin(1) - sleep_us(60) - status = not pin() - enable_irq(i) - sleep_us(420) - return status - - def read_bit(self): - sleep_us = time.sleep_us - enable_irq = machine.enable_irq - pin = self.pin - - pin(1) # half of the devices don't match CRC without this line - i = machine.disable_irq() - pin(0) - sleep_us(1) - pin(1) - sleep_us(1) - value = pin() - enable_irq(i) - sleep_us(40) - return value - - def read_byte(self): - value = 0 - for i in range(8): - value |= self.read_bit() << i - return value - - def read_bytes(self, count): - buf = bytearray(count) - for i in range(count): - buf[i] = self.read_byte() - return buf - - def write_bit(self, value): - sleep_us = time.sleep_us - pin = self.pin - - i = machine.disable_irq() - pin(0) - sleep_us(1) - pin(value) - sleep_us(60) - pin(1) - sleep_us(1) - machine.enable_irq(i) - - def write_byte(self, value): - for i in range(8): - self.write_bit(value & 1) - value >>= 1 - - def write_bytes(self, buf): - for b in buf: - self.write_byte(b) - - def select_rom(self, rom): - """ - Select a specific device to talk to. Pass in rom as a bytearray (8 bytes). - """ - self.reset() - self.write_byte(CMD_MATCHROM) - self.write_bytes(rom) - - def crc8(self, data): - """ - Compute CRC - """ - crc = 0 - for i in range(len(data)): - byte = data[i] - for b in range(8): - fb_bit = (crc ^ byte) & 0x01 - if fb_bit == 0x01: - crc = crc ^ 0x18 - crc = (crc >> 1) & 0x7f - if fb_bit == 0x01: - crc = crc | 0x80 - byte = byte >> 1 - return crc - - def scan(self): - """ - Return a list of ROMs for all attached devices. - Each ROM is returned as a bytes object of 8 bytes. - """ - devices = [] - diff = 65 - rom = False - for i in range(0xff): - rom, diff = self._search_rom(rom, diff) - if rom: - devices += [rom] - if diff == 0: - break - return devices - - def _search_rom(self, l_rom, diff): - if not self.reset(): - return None, 0 - self.write_byte(CMD_SEARCHROM) - if not l_rom: - l_rom = bytearray(8) - rom = bytearray(8) - next_diff = 0 - i = 64 - for byte in range(8): - r_b = 0 - for bit in range(8): - b = self.read_bit() - if self.read_bit(): - if b: # there are no devices or there is an error on the bus - return None, 0 - else: - if not b: # collision, two devices with different bit meaning - if diff > i or ((l_rom[byte] & (1 << bit)) and diff != i): - b = 1 - next_diff = i - self.write_bit(b) - if b: - r_b |= 1 << bit - i -= 1 - rom[byte] = r_b - return rom, next_diff - -class DS18X20(object): - def __init__(self, onewire): - self.ow = onewire - self.roms = [rom for rom in self.ow.scan() if rom[0] == 0x10 or rom[0] == 0x28] - - def isbusy(self): - """ - Checks wether one of the DS18x20 devices on the bus is busy - performing a temperature conversion - """ - return not self.ow.read_bit() - - def start_conversion(self, rom=None): - """ - Start the temp conversion on one DS18x20 device. - Pass the 8-byte bytes object with the ROM of the specific device you want to read. - If only one DS18x20 device is attached to the bus you may omit the rom parameter. - """ - rom = rom or self.roms[0] - ow = self.ow - ow.reset() - ow.select_rom(rom) - ow.write_byte(0x44) # Convert Temp - - def read_temp_async(self, rom=None): - """ - Read the temperature of one DS18x20 device if the conversion is complete, - otherwise return None. - """ - if self.isbusy(): - return None - rom = rom or self.roms[0] - ow = self.ow - ow.reset() - ow.select_rom(rom) - ow.write_byte(0xbe) # Read scratch - data = ow.read_bytes(9) - return self.convert_temp(rom[0], data) - - def convert_temp(self, rom0, data): - """ - Convert the raw temperature data into degrees celsius and return as a fixed point with 2 decimal places. - """ - temp_lsb = data[0] - temp_msb = data[1] - if rom0 == 0x10: - if temp_msb != 0: - # convert negative number - temp_read = temp_lsb >> 1 | 0x80 # truncate bit 0 by shifting, fill high bit with 1. - temp_read = -((~temp_read + 1) & 0xff) # now convert from two's complement - else: - temp_read = temp_lsb >> 1 # truncate bit 0 by shifting - count_remain = data[6] - count_per_c = data[7] - temp = 100 * temp_read - 25 + (count_per_c - count_remain) // count_per_c - return temp - elif rom0 == 0x28: - return (temp_msb << 8 | temp_lsb) * 100 // 16 - else: - assert False -``` - diff --git a/tutorials-and-examples/all/pir.md b/tutorials-and-examples/all/pir.md deleted file mode 100644 index 4dc7d88..0000000 --- a/tutorials-and-examples/all/pir.md +++ /dev/null @@ -1,125 +0,0 @@ -# PIR Sensor - -This code reads PIR sensor triggers from this simple [PIR sensor](https://www.kiwi-electronics.nl/PIR-Motion-Sensor) and sends an HTTP request for every trigger, in this case to a [Domoticz](https://domoticz.com/) installation. When motion is constantly detected, this PIR sensor keeps the pin high, in which case this code will keep sending HTTP requests every 10 seconds \(configurable with the hold\_time variable\). - -## Main \(`main.py`\) - -```python -import time -from network import WLAN -from machine import Pin -from domoticz import Domoticz - -wl = WLAN(WLAN.STA) -d = Domoticz("", 8080 ,"") - -#config -hold_time_sec = 10 - -#flags -last_trigger = -10 - -pir = Pin('G4',mode=Pin.IN, pull=Pin.PULL_UP) - -# main loop -print("Starting main loop") -while True: - if pir() == 1: - if time.time() - last_trigger > hold_time_sec: - last_trigger = time.time() - print("Presence detected, sending HTTP request") - try: - return_code = d.setVariable('Presence:LivingRoom','1') - print("Request result: "+str(return_code)) - except Exception as e: - print("Request failed") - print(e) - else: - last_trigger = 0 - print("No presence") - - time.sleep_ms(500) - -print("Exited main loop") -``` - -## Boot \(`boot.py`\) - -For more WiFi scripts, see the wlan step by step tutorial. - -```python -import os -import machine - -uart = machine.UART(0, 115200) -os.dupterm(uart) - -known_nets = { - 'NetworkID': {'pwd': '', 'wlan_config': ('10.0.0.8', '255.255.0.0', '10.0.0.1', '10.0.0.1')}, -} - -from network import WLAN -wl = WLAN() - - -if machine.reset_cause() != machine.SOFT_RESET: - - wl.mode(WLAN.STA) - original_ssid = wl.ssid() - original_auth = wl.auth() - - print("Scanning for known wifi nets") - available_nets = wl.scan() - nets = frozenset([e.ssid for e in available_nets]) - - known_nets_names = frozenset([key for key in known_nets]) - net_to_use = list(nets & known_nets_names) - try: - net_to_use = net_to_use[0] - net_properties = known_nets[net_to_use] - pwd = net_properties['pwd'] - sec = [e.sec for e in available_nets if e.ssid == net_to_use][0] - if 'wlan_config' in net_properties: - wl.ifconfig(config=net_properties['wlan_config']) - wl.connect(net_to_use, (sec, pwd), timeout=10000) - while not wl.isconnected(): - machine.idle() # save power while waiting - print("Connected to "+net_to_use+" with IP address:" + wl.ifconfig()[0]) - - except Exception as e: - print("Failed to connect to any known network, going into AP mode") - wl.init(mode=WLAN.AP, ssid=original_ssid, auth=original_auth, channel=6, antenna=WLAN.INT_ANT) -``` - -## Domoticz Wrapper \(`domoticz.py`\) - -```python -import socket -class Domoticz: - - def __init__(self, ip, port, basic): - self.basic = basic - self.ip = ip - self.port = port - - def setLight(self, idx, command): - return self.sendRequest("type=command¶m=switchlight&idx="+idx+"&switchcmd="+command) - - def setVariable(self, name, value): - return self.sendRequest("type=command¶m=updateuservariable&vtype=0&vname="+name+"&vvalue="+value) - - def sendRequest(self, path): - try: - s = socket.socket() - s.connect((self.ip,self.port)) - s.send(b"GET /json.htm?"+path+" HTTP/1.1\r\nHost: pycom.io\r\nAuthorization: Basic "+self.basic+"\r\n\r\n") - status = str(s.readline(), 'utf8') - code = status.split(" ")[1] - s.close() - return code - - except Exception: - print("HTTP request failed") - return 0 -``` - diff --git a/tutorials-and-examples/all/repl.md b/tutorials-and-examples/all/repl.md deleted file mode 100644 index 75ec25d..0000000 --- a/tutorials-and-examples/all/repl.md +++ /dev/null @@ -1,45 +0,0 @@ -# REPL - -Using the Pymakr Plugin, open and connect a device or use serial terminal \(PuTTY, screen, picocom, etc\). Upon connecting, there should be a blank screen with a flashing cursor. Press Enter and a MicroPython prompt should appear, i.e. `>>>`. Let’s make sure it is working with the obligatory test: - -```python ->>> print("Hello LoPy!") -Hello LoPy! -``` - -In the example above, the `>>>` characters should not be typed. They are there to indicate that the text should be placed after the prompt. Once the text has been entered `print("Hello LoPy!")` and pressed `Enter`, the output should appear on screen, identical to the example above. - -Basic Python commands can be tested out in a similar fashion. - -If this is not working, try either a hard reset or a soft reset; see below. - -Here are some other example, utilising the device's hardware features: - -```python ->>> from machine import Pin ->>> led = Pin('G16', mode=Pin.OUT, value=1) ->>> led(0) ->>> led(1) ->>> led.toggle() ->>> 1 + 2 -3 ->>> 5 / 2 -2.5 ->>> 20 * 'py' -'pypypypypypypypypypypypypypypypypypypypy' -``` - -## Resetting the Device - -If something goes wrong, the device can be reset with two methods. The first is to press `CTRL-D` at the MicroPython prompt, which will perform a soft reset. A message, as following, will appear: - -```python ->>> -PYB: soft reboot -MicroPython v1.4.6-146-g1d8b5e5 on 2016-10-21; LoPy with ESP32 -Type "help()" for more information. ->>> -``` - -If that still isn’t working a hard reset can be performed \(power-off/on\) by pressing the `RST` switch \(the small black button next to the RGB LED\). Using telnet, this will end the session, disconnecting the program that was used to connect to the Pycom Device. - diff --git a/tutorials-and-examples/all/rgbled.md b/tutorials-and-examples/all/rgbled.md deleted file mode 100644 index 12f934b..0000000 --- a/tutorials-and-examples/all/rgbled.md +++ /dev/null @@ -1,33 +0,0 @@ -# RGB LED - -By default the heartbeat LED flashes in blue colour once every 4s to signal that the system is alive. This can be overridden through the `pycom` module. - -```python -import pycom - -pycom.heartbeat(False) -pycom.rgbled(0xff00) # turn on the RGB LED in green colour -``` - -The heartbeat LED is also used to indicate that an error was detected. - -The following piece of code uses the RGB LED to make a traffic light that runs for 10 cycles. - -```python -import pycom -import time - -pycom.heartbeat(False) -for cycles in range(10): # stop after 10 cycles - pycom.rgbled(0x007f00) # green - time.sleep(5) - pycom.rgbled(0x7f7f00) # yellow - time.sleep(1.5) - pycom.rgbled(0x7f0000) # red - time.sleep(4) -``` - -Here is the expected result: - -![](../../.gitbook/assets/traffic.gif) - diff --git a/tutorials-and-examples/all/rmt.md b/tutorials-and-examples/all/rmt.md deleted file mode 100644 index 008cca5..0000000 --- a/tutorials-and-examples/all/rmt.md +++ /dev/null @@ -1,141 +0,0 @@ -# RMT - -Detailed information about this class can be found in [`RMT`](../../firmware-and-api-reference/pycom/machine/rmt.md). - -The RMT \(Remote Control\) peripheral of the ESP32 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, this class will allow you to do this. - -The RMT has 7 channels, of which 5 are available and can be mapped to any GPIO pin \(_Note:_ Pins `P13` -`P18` can only be used as inputs\). - -| 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 | - -## Transmitting - -The following examples create an RMT object on channel 4, configure it for transmission and send some data in various forms. The resolution of channel 4 is 1000 nano seconds, the given values are interpreted accordingly. - -In this first example, we define the signal as a tuple of binary values that define the shape of the desired signal along with the duration of a bit. - -```python -from machine import RMT -# Map RMT channel 4 to P21, when the RMT is idle, it will output LOW -rmt = RMT(channel=4, gpio="P21", tx_idle_level=RMT.LOW) - -# Produces the pattern shown in data, where each bit lasts -# duration * channel resolution = 10000 * 1000ns = 10ms -data = (1,0,1,1,1,0,1,0,1) -duration = 10000 -rmt.pulses_send(duration, data) -``` - -![Waveform of example 1](../../.gitbook/assets/rmt_ex_1%20%281%29.png) - -In this example we define the signal by a tuple of durations and what state the signal starts in. - -```python -from machine import RMT -# Map RMT channel 4 to P21, when the RMT is idle, it will output LOW -rmt = RMT(channel=4, gpio="P21", tx_idle_level=RMT.LOW) - -# The list of durations for each pulse to be, these are in units of the channels -# resolution: -# duration = Desired pulse length / Channel Resolution -duration = (8000,11000,8000,11000,6000,13000,6000,3000,8000) - -# `start_level` defines if the signal starts off as LOW or HIGH, it will then -# toggle state between each duration -rmt.pulses_send(duration, start_level=RMT.HIGH) -``` - -![Waveform of example 2](../../.gitbook/assets/rmt_ex_2.png) - -This third example, is a combination of the above two styles of defining a signal. Each pulse has a defined duration as well as a state. This is useful if you don't always want the signal to toggle state. - -```python -from machine import RMT -# Map RMT channel 4 to P21, when the RMT is idle, it will output LOW -rmt = RMT(channel=4, gpio="P21", tx_idle_level=RMT.LOW) - -# Produces the pattern shown in data, where each bit lasts -# duration[i] * channel resolution = duration[i] * 1000ns -data = (1,0,1,1,0,1) -duration = (400,200,100,300,200,400) -rmt.pulses_send(duration, data) -``` - -![Waveform of example 3](../../.gitbook/assets/rmt_ex_3%20%281%29.png) - -The following example creates an RMT object on channel 4 and configures it for transmission with carrier modulation. - -```python -from machine import RMT -rmt = RMT(channel=4, - gpio="P21", - tx_idle_level=RMT.LOW, - # Carrier = 100Hz, 80% duty, modules HIGH signals - tx_carrier = (100, 70, RMT.HIGH)) -data = (1,0,1) -duration = 10000 -rmt.pulses_send(duration, data) -``` - -![Waveform of example 4](../../.gitbook/assets/rmt_ex_4.png) - -The following example creates an RMT object on channel 2, configures it for receiving, then waits for the first, undefined number of pulses without timeout - -```python -from machine import RMT -rmt = machine.RMT(channel=2) -rmt.init(gpio="P21", rx_idle_threshold=1000) - -data = rmt.pulses_get() -``` - -{% hint style="danger" %} -If `tx_idle_level` is not set to the opposite of the third value in the `tx_carrier` tuple, the carrier wave will continue to be generated when the RMT channel is idle. -{% endhint %} - -## Receiving - -The following example creates an RMT object on channel 2, configures it for receiving a undefined number of pulses, then waits maximum of 1000us for the first pulse. - -```python -from machine import RMT -# Sets RMT channel 2 to P21 and sets the maximum length of a valid pulse to -# 1000*channel resolution = 1000 * 100ns = 100us -rmt = machine.RMT(channel=2, gpio="P21", rx_idle_threshold=1000) -rmt.init() - -# Get a undefined number of pulses, waiting a maximum of 500us for the first -# pulse (unlike other places where the absolute duration was based on the RMT -# channels resolution, this value is in us) until a pulse longer than -# rx_idle_threshold occurs. -data = rmt.pulses_get(timeout=500) -``` - -The following example creates an RMT object on channel 2, configures it for receiving, filters out pulses with width < 20\*100 nano seconds, then waits for 100 pulses - -```python -from machine import RMT - -rmt = machine.RMT(channel=2, # Resolution = 100ns - gpio="P21", - # Longest valid pulse = 1000*100ns = 100us - rx_idle_threshold=1000, - # Filter out pulses shorter than 20*100ns = 2us - rx_filter_threshold=20) - -# Receive 100 pulses, pulses shorter than 2us or longer than 100us will be -# ignored. That means if it receives 80 valid pulses but then the signal -# doesn't change for 10 hours and then 20 more pulses occur, this function -# will wait for 10h -data = rmt.pulses_get(pulses=100) -``` - diff --git a/tutorials-and-examples/all/threading.md b/tutorials-and-examples/all/threading.md deleted file mode 100644 index ccf249b..0000000 --- a/tutorials-and-examples/all/threading.md +++ /dev/null @@ -1,28 +0,0 @@ -# Threading - -MicroPython supports spawning threads by the `_thread` module. The following example demonstrates the use of this module. A thread is simply defined as a function that can receive any number of parameters. Below 3 threads are started, each one perform a print at a different interval. - -```python -import _thread -import time - -def th_func(delay, id): - while True: - time.sleep(delay) - print('Running thread %d' % id) - -for i in range(3): - _thread.start_new_thread(th_func, (i + 1, i)) -``` - -## Using Locks: - -```python -import _thread - -a_lock = _thread.allocate_lock() - -with a_lock: - print("a_lock is locked while this executes") -``` - diff --git a/tutorials-and-examples/all/timers.md b/tutorials-and-examples/all/timers.md deleted file mode 100644 index cbeb345..0000000 --- a/tutorials-and-examples/all/timers.md +++ /dev/null @@ -1,53 +0,0 @@ -# Timers - -Detailed information about this class can be found in [`Timer`](../../firmware-and-api-reference/pycom/machine/timer.md). - -## Chronometer - -The Chronometer can be used to measure how much time has elapsed in a block of code. The following example uses a simple stopwatch. - -```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)) -``` - -## Alarm - -The Alarm can be used to get interrupts at a specific interval. The following code executes a callback every second for 10 seconds. - -```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.callback(None) # stop counting after 10 seconds - -clock = Clock() -``` - -{% hint style="info" %} -There are no restrictions to what can be done in an interrupt. For example, it is possible to even do network requests with an interrupt. However, it is important to keep in mind that interrupts are handled sequentially, so it’s good practice to keep them short. More information can be found in [`Interrupt Handling`](../../firmware-and-api-reference/notes.md#interrupt-handling). -{% endhint %} - diff --git a/tutorials-and-examples/all/wlan.md b/tutorials-and-examples/all/wlan.md deleted file mode 100644 index f3ab22f..0000000 --- a/tutorials-and-examples/all/wlan.md +++ /dev/null @@ -1,144 +0,0 @@ -# WLAN - -The WLAN is a system feature of all Pycom devices, therefore it is enabled by default. - -In order to retrieve the current WLAN instance, run: - -```python ->>> from network import WLAN ->>> wlan = WLAN() # we call the constructor without params -``` - -The current mode \(`WLAN.AP` after power up\) may be checked by running: - -```python ->>> wlan.mode() -``` - -{% hint style="danger" %} - -When changing the WLAN mode, if following the instructions below, the WLAN connection to the Pycom device will be broken. This means commands will not run interactively over WiFi. - -**There are two ways around this:** - -1. Put this setup code into the `boot.py` file of the Pycom device so that it gets executed automatically after reset. -2. Duplicate the REPL on UART. This way commands can be run via Serial USB. - -## Connecting to a Router - -The WLAN network class always boots in `WLAN.AP` mode; to connect it to an existing network, the WiFi class must be configured as a station: - -```python -from network import WLAN -wlan = WLAN(mode=WLAN.STA) -``` - -Now the device may proceed to scan for networks: - -```python -nets = wlan.scan() -for net in nets: - if net.ssid == 'mywifi': - print('Network found!') - wlan.connect(net.ssid, auth=(net.sec, 'mywifikey'), timeout=5000) - while not wlan.isconnected(): - machine.idle() # save power while waiting - print('WLAN connection succeeded!') - break -``` - -## Assigning a Static IP Address at Boot Up - -If the users wants their device to connect to a home router upon boot up, using with a fixed IP address, use the following script as `/flash/boot.py`: - -```python -import machine -from network import WLAN -wlan = WLAN() # get current object, without changing the mode - -if machine.reset_cause() != machine.SOFT_RESET: - wlan.init(mode=WLAN.STA) - # configuration below MUST match your home router settings!! - wlan.ifconfig(config=('192.168.178.107', '255.255.255.0', '192.168.178.1', '8.8.8.8')) - -if not wlan.isconnected(): - # change the line below to match your network ssid, security and password - wlan.connect('mywifi', auth=(WLAN.WPA2, 'mywifikey'), timeout=5000) - while not wlan.isconnected(): - machine.idle() # save power while waiting -``` - -{% hint style="info" %} -Notice how we check for the reset cause and the connection status, this is crucial in order to be able to soft reset the LoPy during a telnet session without breaking the connection. -{% endhint %} - -## Multiple Networks using a Static IP Address - -The following script holds a list with nets and an optional list of `wlan_config` to set a fixed IP - -```python -import os -import machine - -uart = machine.UART(0, 115200) -os.dupterm(uart) - -known_nets = { - '': {'pwd': ''}, - '': {'pwd': '', 'wlan_config': ('10.0.0.114', '255.255.0.0', '10.0.0.1', '10.0.0.1')}, # (ip, subnet_mask, gateway, DNS_server) -} - -if machine.reset_cause() != machine.SOFT_RESET: - from network import WLAN - wl = WLAN() - wl.mode(WLAN.STA) - original_ssid = wl.ssid() - original_auth = wl.auth() - - print("Scanning for known wifi nets") - available_nets = wl.scan() - nets = frozenset([e.ssid for e in available_nets]) - - known_nets_names = frozenset([key for key in known_nets]) - net_to_use = list(nets & known_nets_names) - try: - net_to_use = net_to_use[0] - net_properties = known_nets[net_to_use] - pwd = net_properties['pwd'] - sec = [e.sec for e in available_nets if e.ssid == net_to_use][0] - if 'wlan_config' in net_properties: - wl.ifconfig(config=net_properties['wlan_config']) - wl.connect(net_to_use, (sec, pwd), timeout=10000) - while not wl.isconnected(): - machine.idle() # save power while waiting - print("Connected to "+net_to_use+" with IP address:" + wl.ifconfig()[0]) - - except Exception as e: - print("Failed to connect to any known network, going into AP mode") - wl.init(mode=WLAN.AP, ssid=original_ssid, auth=original_auth, channel=6, antenna=WLAN.INT_ANT) -``` - -## Connecting to a WPA2-Enterprise network - -### Connecting with EAP-TLS: - -Before connecting, obtain and copy the public and private keys to the device, e.g. under location `/flash/cert`. If it is required to validate the server’s public key, an appropriate CA certificate \(chain\) must also be provided. - -```python -from network import WLAN - -wlan = WLAN(mode=WLAN.STA) -wlan.connect(ssid='mywifi', auth=(WLAN.WPA2_ENT,), identity='myidentity', ca_certs='/flash/cert/ca.pem', keyfile='/flash/cert/client.key', certfile='/flash/cert/client.crt') -``` - -### Connecting with EAP-PEAP or EAP-TTLS: - -In case of EAP-PEAP \(or EAP-TTLS\), the client key and certificate are not necessary, only a username and password pair. If it is required to validate the server’s public key, an appropriate CA certificate \(chain\) must also be provided. - -```python -from network import WLAN - -wlan = WLAN(mode=WLAN.STA) -wlan.connect(ssid='mywifi', auth=(WLAN.WPA2_ENT, 'username', 'password'), identity='myidentity', ca_certs='/flash/cert/ca.pem') -``` - diff --git a/tutorials-and-examples/introduction.md b/tutorials-and-examples/introduction.md deleted file mode 100644 index e028c20..0000000 --- a/tutorials-and-examples/introduction.md +++ /dev/null @@ -1,14 +0,0 @@ -# Introduction - -![](../.gitbook/assets/tutorialsicon%20%281%29.png) - -## Tutorials and Examples - -This section contains tutorials and examples for use with Pycom modules and Expansion boards. - -General Pycom tutorials contains tutorials that may be run on any Pycom device, such as connecting to a WiFi network, Bluetooth, controlling I/O pins etc. Later sections are specific to the LoPy and SiPy devices such as setting up a LoRa node or connecting to the Sigfox network. The final sections are related to examples using the Pytrack and Pysense. - -Before starting, ensure that any Pycom devices are running the latest firmware; for instructions see [Firmware Updates](../getting-started/installation/firmwaretool.md). - -The source code for these tutorials, along with the required libraries can be found in in the [pycom-libraries](https://github.com/pycom/pycom-libraries) repository. - diff --git a/tutorials-and-examples/lora/README.md b/tutorials-and-examples/lora/README.md deleted file mode 100644 index 593f7a4..0000000 --- a/tutorials-and-examples/lora/README.md +++ /dev/null @@ -1,8 +0,0 @@ -# LoRa Examples - -The following tutorials demonstrate the use of the LoRa functionality on the LoPy. LoRa can work in 2 different modes; **LoRa-MAC** \(which we also call Raw-LoRa\) and **LoRaWAN** mode. - -LoRa-MAC mode basically accesses de radio directly and packets are sent using the LoRa modulation on the selected frequency without any headers, addressing information or encryption. Only a CRC is added at the tail of the packet and this is removed before the received frame is passed on to the application. This mode can be used to build any higher level protocol that can benefit from the long range features of the LoRa modulation. Typical uses cases include LoPy to LoPy direct communication and a LoRa packet forwarder. - -LoRaWAN mode implements the full LoRaWAN stack for a class A device. It supports both OTAA and ABP connection methods, as well as advanced features like adding and removing custom channels to support "special" frequencies plans like the those used in New Zealand. - diff --git a/tutorials-and-examples/lora/lora-mac-nano-gateway.md b/tutorials-and-examples/lora/lora-mac-nano-gateway.md deleted file mode 100644 index 58b935a..0000000 --- a/tutorials-and-examples/lora/lora-mac-nano-gateway.md +++ /dev/null @@ -1,106 +0,0 @@ -# LoRa-MAC Nano-Gateway - -This example allows a raw LoRa connection between two LoPys \(nodes\) to a single LoPy acting as a Nano-Gateway. - -For more information and discussions about this code, see this forum [post](https://forum.pycom.io/topic/236/lopy-nano-gateway). - -## Gateway Code - -```python -import socket -import struct -from network import LoRa - -# A basic package header, B: 1 byte for the deviceId, B: 1 byte for the pkg size, %ds: Formatted string for string -_LORA_PKG_FORMAT = "!BB%ds" -# A basic ack package, B: 1 byte for the deviceId, B: 1 byte for the pkg size, B: 1 byte for the Ok (200) or error messages -_LORA_PKG_ACK_FORMAT = "BBB" - -# Open a LoRa Socket, use rx_iq to avoid listening to our own messages -# 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.LORA, rx_iq=True, region=LoRa.EU868) -lora_sock = socket.socket(socket.AF_LORA, socket.SOCK_RAW) -lora_sock.setblocking(False) - -while (True): - recv_pkg = lora_sock.recv(512) - if (len(recv_pkg) > 2): - recv_pkg_len = recv_pkg[1] - - device_id, pkg_len, msg = struct.unpack(_LORA_PKG_FORMAT % recv_pkg_len, recv_pkg) - -# If the uart = machine.UART(0, 115200) and os.dupterm(uart) are set in the boot.py this print should appear in the serial port - print('Device: %d - Pkg: %s' % (device_id, msg)) - - ack_pkg = struct.pack(_LORA_PKG_ACK_FORMAT, device_id, 1, 200) - lora_sock.send(ack_pkg) -``` - -The `_LORA_PKG_FORMAT` is used as a method of identifying the different devices within a network. The `_LORA_PKG_ACK_FORMAT` is a simple `ack` package as a response to the nodes package. - -## Node - -```python -import os -import socket -import time -import struct -from network import LoRa - -# A basic package header, B: 1 byte for the deviceId, B: 1 byte for the pkg size -_LORA_PKG_FORMAT = "BB%ds" -_LORA_PKG_ACK_FORMAT = "BBB" -DEVICE_ID = 0x01 - - -# Open a Lora Socket, use tx_iq to avoid listening to our own messages -# 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.LORA, tx_iq=True, region=LoRa.EU868) -lora_sock = socket.socket(socket.AF_LORA, socket.SOCK_RAW) -lora_sock.setblocking(False) - -while(True): - # Package send containing a simple string - msg = "Device 1 Here" - pkg = struct.pack(_LORA_PKG_FORMAT % len(msg), DEVICE_ID, len(msg), msg) - lora_sock.send(pkg) - - # Wait for the response from the gateway. NOTE: For this demo the device does an infinite loop for while waiting the response. Introduce a max_time_waiting for you application - waiting_ack = True - while(waiting_ack): - recv_ack = lora_sock.recv(256) - - if (len(recv_ack) > 0): - device_id, pkg_len, ack = struct.unpack(_LORA_PKG_ACK_FORMAT, recv_ack) - if (device_id == DEVICE_ID): - if (ack == 200): - waiting_ack = False - # If the uart = machine.UART(0, 115200) and os.dupterm(uart) are set in the boot.py this print should appear in the serial port - print("ACK") - else: - waiting_ack = False - # If the uart = machine.UART(0, 115200) and os.dupterm(uart) are set in the boot.py this print should appear in the serial port - print("Message Failed") - - time.sleep(5) -``` - -The node is always sending packages and waiting for the `ack` from the gateway. - -{% hint style="info" %} -To adapt this code to user specific needs: - -* Put a max waiting time for the `ack` to arrive and resend the package or mark it as invalid -* Increase the package size changing the `_LORA_PKG_FORMAT` to `BH%ds`. The `H` will allow the keeping of 2 bytes for size \(for more information about [struct format](https://docs.python.org/2/library/struct.html#format-characters)\) -* Reduce the package size with bitwise manipulation -* Reduce the message size \(for this demo, a string\) to something more useful for specific development -{% endhint %} - diff --git a/tutorials-and-examples/lora/lora-mac.md b/tutorials-and-examples/lora/lora-mac.md deleted file mode 100644 index 3973f8d..0000000 --- a/tutorials-and-examples/lora/lora-mac.md +++ /dev/null @@ -1,38 +0,0 @@ -# LoRa-MAC \(Raw LoRa\) - -Basic LoRa connection example, sending and receiving data. In LoRa-MAC mode the LoRaWAN layer is bypassed and the radio is used directly. The data sent is not formatted or encrypted in any way, and no addressing information is added to the frame. - -For the example below, you will need two LoPys. A `while` loop with a random delay time is used to minimise the chances of the 2 LoPy’s transmitting at the same time. Run the code below on the 2 LoPy modules and you will see the word 'Hello' being received on both sides. - -```python -from network import LoRa -import socket -import machine -import time - -# initialise LoRa in LORA 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 -# more params can also be given, like frequency, tx power and spreading factor -lora = LoRa(mode=LoRa.LORA, region=LoRa.EU868) - -# create a raw LoRa socket -s = socket.socket(socket.AF_LORA, socket.SOCK_RAW) - -while True: - # send some data - s.setblocking(True) - s.send('Hello') - - # get any data received... - s.setblocking(False) - data = s.recv(64) - print(data) - - # wait a random amount of time - time.sleep(machine.rng() & 0x0F) -``` - diff --git a/tutorials-and-examples/lora/lorawan-abp.md b/tutorials-and-examples/lora/lorawan-abp.md deleted file mode 100644 index e2dc793..0000000 --- a/tutorials-and-examples/lora/lorawan-abp.md +++ /dev/null @@ -1,50 +0,0 @@ -# LoRaWAN with ABP - -ABP stands for Authentication By Personalisation. It means that the encryption keys are configured manually on the device and can start sending frames to the Gateway without needing a 'handshake' procedure to exchange the keys \(such as the one performed during an OTAA join procedure\). - -The example below attempts to get any data received after sending the frame. Keep in mind that the Gateway might not be sending any data back, therefore we make the socket non-blocking before attempting to receive, in order to prevent getting stuck waiting for a packet that will never arrive. - -```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 Personalization) -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 blocking -# (waits for the data to be sent and for the 2 receive windows to expire) -s.setblocking(True) - -# send some data -s.send(bytes([0x01, 0x02, 0x03])) - -# make the socket non-blocking -# (because if there's no data received it will block forever...) -s.setblocking(False) - -# get any data received (if any...) -data = s.recv(64) -print(data) -``` - diff --git a/tutorials-and-examples/lora/lorawan-nano-gateway.md b/tutorials-and-examples/lora/lorawan-nano-gateway.md deleted file mode 100644 index e75aa16..0000000 --- a/tutorials-and-examples/lora/lorawan-nano-gateway.md +++ /dev/null @@ -1,549 +0,0 @@ -# LoRaWAN Nano-Gateway - -This example allows to connect a LoPy to a LoRaWAN network such as The Things Network \(TTN\) or Loriot to be used as a nano-gateway. - -This example uses settings specifically for connecting to The Things Network within the European 868 MHz region. For another usage, please see the `config.py` file for relevant sections that need changing. - -Up to date versions of these snippets can be found at the following [GitHub Repository](https://github.com/pycom/pycom-libraries/tree/master/examples/lorawan-nano-gateway). For more information and discussion about this code, see this forum [post](https://forum.pycom.io/topic/810/new-firmware-release-1-6-7-b1-lorawan-nano-gateway-with-ttn-example). - -## Nano-Gateway - -The Nano-Gateway code is split into 3 files, `main.py`, `config.py` and `nanogateway.py`. These are used to configure and specify how the gateway will connect to a preferred network and how it can act as packet forwarder. - -### Gateway ID - -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 ubinascii -wl = WLAN() -ubinascii.hexlify(wl.mac())[:6] + 'FFFE' + ubinascii.hexlify(wl.mac())[6:] -``` - -The result will by something like `b'240ac4FFFE008d88'` where `240ac4FFFE008d88` is your Gateway ID to be used in your network provider configuration. - -## Main \(`main.py`\) - -This file runs at boot and calls the library and `config.py` files to initialise the nano-gateway. Once configuration is set, the nano-gateway is then started. - -```python -""" LoPy LoRaWAN Nano Gateway example usage """ - -import config -from nanogateway import NanoGateway - -if __name__ == '__main__': - nanogw = NanoGateway( - id=config.GATEWAY_ID, - frequency=config.LORA_FREQUENCY, - datarate=config.LORA_GW_DR, - ssid=config.WIFI_SSID, - password=config.WIFI_PASS, - server=config.SERVER, - port=config.PORT, - ntp_server=config.NTP, - ntp_period=config.NTP_PERIOD_S - ) - - nanogw.start() - nanogw._log('You may now press ENTER to enter the REPL') - input() -``` - -## Configuration \(`config.py`\) - -This file contains settings for the server and network it is connecting to. Depending on the nano-gateway region and provider \(TTN, Loriot, etc.\) these will vary. The provided example will work with The Things Network \(TTN\) in the European, 868Mhz, region. - -The Gateway ID is generated in the script using the process described above. - -**Please change the WIFI\_SSID and WIFI\_PASS variables to match your desired WiFi network** - -```python -""" LoPy LoRaWAN Nano Gateway configuration options """ - -import machine -import ubinascii - -WIFI_MAC = ubinascii.hexlify(machine.unique_id()).upper() -# Set the Gateway ID to be the first 3 bytes of MAC address + 'FFFE' + last 3 bytes of MAC address -GATEWAY_ID = WIFI_MAC[:6] + "FFFE" + WIFI_MAC[6:12] - -SERVER = 'router.eu.thethings.network' -PORT = 1700 - -NTP = "pool.ntp.org" -NTP_PERIOD_S = 3600 - -WIFI_SSID = 'my-wifi' -WIFI_PASS = 'my-wifi-password' - -# for EU868 -LORA_FREQUENCY = 868100000 -LORA_GW_DR = "SF7BW125" # DR_5 -LORA_NODE_DR = 5 - -# for US915 -# LORA_FREQUENCY = 903900000 -# LORA_GW_DR = "SF7BW125" # DR_3 -# LORA_NODE_DR = 3 -``` - -## Library \(`nanogateway.py`\) - -The nano-gateway library controls all of the packet generation and forwarding for the LoRa data. This does not require any user configuration and the latest version of this code should be downloaded from the Pycom [GitHub Repository](https://github.com/pycom/pycom-libraries/tree/master/examples/lorawan-nano-gateway). - -```python -""" LoPy Nano Gateway class """ - -from network import WLAN -from network import LoRa -from machine import Timer -import os -import ubinascii -import machine -import json -import time -import errno -import _thread -import socket - - -PROTOCOL_VERSION = const(2) - -PUSH_DATA = const(0) -PUSH_ACK = const(1) -PULL_DATA = const(2) -PULL_ACK = const(4) -PULL_RESP = const(3) - -TX_ERR_NONE = "NONE" -TX_ERR_TOO_LATE = "TOO_LATE" -TX_ERR_TOO_EARLY = "TOO_EARLY" -TX_ERR_COLLISION_PACKET = "COLLISION_PACKET" -TX_ERR_COLLISION_BEACON = "COLLISION_BEACON" -TX_ERR_TX_FREQ = "TX_FREQ" -TX_ERR_TX_POWER = "TX_POWER" -TX_ERR_GPS_UNLOCKED = "GPS_UNLOCKED" - -STAT_PK = {"stat": {"time": "", "lati": 0, - "long": 0, "alti": 0, - "rxnb": 0, "rxok": 0, - "rxfw": 0, "ackr": 100.0, - "dwnb": 0, "txnb": 0}} - -RX_PK = {"rxpk": [{"time": "", "tmst": 0, - "chan": 0, "rfch": 0, - "freq": 868.1, "stat": 1, - "modu": "LORA", "datr": "SF7BW125", - "codr": "4/5", "rssi": 0, - "lsnr": 0, "size": 0, - "data": ""}]} - -TX_ACK_PK = {"txpk_ack":{"error":""}} - - -class NanoGateway: - - def __init__(self, id, frequency, datarate, ssid, password, server, port, ntp='pool.ntp.org', ntp_period=3600): - self.id = id - self.frequency = frequency - self.sf = self._dr_to_sf(datarate) - self.ssid = ssid - self.password = password - self.server = server - self.port = port - self.ntp = ntp - self.ntp_period = ntp_period - - self.rxnb = 0 - self.rxok = 0 - self.rxfw = 0 - self.dwnb = 0 - self.txnb = 0 - - self.stat_alarm = None - self.pull_alarm = None - self.uplink_alarm = None - - self.udp_lock = _thread.allocate_lock() - - self.lora = None - self.lora_sock = None - - def start(self): - # Change WiFi to STA mode and connect - self.wlan = WLAN(mode=WLAN.STA) - self._connect_to_wifi() - - # Get a time Sync - self.rtc = machine.RTC() - self.rtc.ntp_sync(self.ntp, update_period=self.ntp_period) - - # Get the server IP and create an UDP socket - self.server_ip = socket.getaddrinfo(self.server, self.port)[0][-1] - self.sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP) - self.sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) - self.sock.setblocking(False) - - # Push the first time immediately - self._push_data(self._make_stat_packet()) - - # Create the alarms - self.stat_alarm = Timer.Alarm(handler=lambda t: self._push_data(self._make_stat_packet()), s=60, periodic=True) - self.pull_alarm = Timer.Alarm(handler=lambda u: self._pull_data(), s=25, periodic=True) - - # Start the UDP receive thread - _thread.start_new_thread(self._udp_thread, ()) - - # Initialize LoRa in LORA mode - self.lora = LoRa(mode=LoRa.LORA, frequency=self.frequency, bandwidth=LoRa.BW_125KHZ, sf=self.sf, - preamble=8, coding_rate=LoRa.CODING_4_5, tx_iq=True) - # Create a raw LoRa socket - self.lora_sock = socket.socket(socket.AF_LORA, socket.SOCK_RAW) - self.lora_sock.setblocking(False) - self.lora_tx_done = False - - self.lora.callback(trigger=(LoRa.RX_PACKET_EVENT | LoRa.TX_PACKET_EVENT), handler=self._lora_cb) - - def stop(self): - # TODO: Check how to stop the NTP sync - # TODO: Create a cancel method for the alarm - # TODO: kill the UDP thread - self.sock.close() - - def _connect_to_wifi(self): - self.wlan.connect(self.ssid, auth=(None, self.password)) - while not self.wlan.isconnected(): - time.sleep(0.5) - print("WiFi connected!") - - def _dr_to_sf(self, dr): - sf = dr[2:4] - if sf[1] not in '0123456789': - sf = sf[:1] - return int(sf) - - def _sf_to_dr(self, sf): - return "SF7BW125" - - def _make_stat_packet(self): - now = self.rtc.now() - STAT_PK["stat"]["time"] = "%d-%02d-%02d %02d:%02d:%02d GMT" % (now[0], now[1], now[2], now[3], now[4], now[5]) - STAT_PK["stat"]["rxnb"] = self.rxnb - STAT_PK["stat"]["rxok"] = self.rxok - STAT_PK["stat"]["rxfw"] = self.rxfw - STAT_PK["stat"]["dwnb"] = self.dwnb - STAT_PK["stat"]["txnb"] = self.txnb - return json.dumps(STAT_PK) - - def _make_node_packet(self, rx_data, rx_time, tmst, sf, rssi, snr): - RX_PK["rxpk"][0]["time"] = "%d-%02d-%02dT%02d:%02d:%02d.%dZ" % (rx_time[0], rx_time[1], rx_time[2], rx_time[3], rx_time[4], rx_time[5], rx_time[6]) - RX_PK["rxpk"][0]["tmst"] = tmst - RX_PK["rxpk"][0]["datr"] = self._sf_to_dr(sf) - RX_PK["rxpk"][0]["rssi"] = rssi - RX_PK["rxpk"][0]["lsnr"] = float(snr) - RX_PK["rxpk"][0]["data"] = ubinascii.b2a_base64(rx_data)[:-1] - RX_PK["rxpk"][0]["size"] = len(rx_data) - return json.dumps(RX_PK) - - def _push_data(self, data): - token = os.urandom(2) - packet = bytes([PROTOCOL_VERSION]) + token + bytes([PUSH_DATA]) + ubinascii.unhexlify(self.id) + data - with self.udp_lock: - try: - self.sock.sendto(packet, self.server_ip) - except Exception: - print("PUSH exception") - - def _pull_data(self): - token = os.urandom(2) - packet = bytes([PROTOCOL_VERSION]) + token + bytes([PULL_DATA]) + ubinascii.unhexlify(self.id) - with self.udp_lock: - try: - self.sock.sendto(packet, self.server_ip) - except Exception: - print("PULL exception") - - def _ack_pull_rsp(self, token, error): - TX_ACK_PK["txpk_ack"]["error"] = error - resp = json.dumps(TX_ACK_PK) - packet = bytes([PROTOCOL_VERSION]) + token + bytes([PULL_ACK]) + ubinascii.unhexlify(self.id) + resp - with self.udp_lock: - try: - self.sock.sendto(packet, self.server_ip) - except Exception: - print("PULL RSP ACK exception") - - def _lora_cb(self, lora): - events = lora.events() - if events & LoRa.RX_PACKET_EVENT: - self.rxnb += 1 - self.rxok += 1 - rx_data = self.lora_sock.recv(256) - stats = lora.stats() - self._push_data(self._make_node_packet(rx_data, self.rtc.now(), stats.timestamp, stats.sf, stats.rssi, stats.snr)) - self.rxfw += 1 - if events & LoRa.TX_PACKET_EVENT: - self.txnb += 1 - lora.init(mode=LoRa.LORA, frequency=self.frequency, bandwidth=LoRa.BW_125KHZ, - sf=self.sf, preamble=8, coding_rate=LoRa.CODING_4_5, tx_iq=True) - - def _send_down_link(self, data, tmst, datarate, frequency): - self.lora.init(mode=LoRa.LORA, frequency=frequency, bandwidth=LoRa.BW_125KHZ, - sf=self._dr_to_sf(datarate), preamble=8, coding_rate=LoRa.CODING_4_5, - tx_iq=True) - while time.ticks_us() < tmst: - pass - self.lora_sock.send(data) - - def _udp_thread(self): - while True: - try: - data, src = self.sock.recvfrom(1024) - _token = data[1:3] - _type = data[3] - if _type == PUSH_ACK: - print("Push ack") - elif _type == PULL_ACK: - print("Pull ack") - elif _type == PULL_RESP: - self.dwnb += 1 - ack_error = TX_ERR_NONE - tx_pk = json.loads(data[4:]) - tmst = tx_pk["txpk"]["tmst"] - t_us = tmst - time.ticks_us() - 5000 - if t_us < 0: - t_us += 0xFFFFFFFF - if t_us < 20000000: - self.uplink_alarm = Timer.Alarm(handler=lambda x: self._send_down_link(ubinascii.a2b_base64(tx_pk["txpk"]["data"]), - tx_pk["txpk"]["tmst"] - 10, tx_pk["txpk"]["datr"], - int(tx_pk["txpk"]["freq"] * 1000000)), us=t_us) - else: - ack_error = TX_ERR_TOO_LATE - print("Downlink timestamp error!, t_us:", t_us) - self._ack_pull_rsp(_token, ack_error) - print("Pull rsp") - except socket.timeout: - pass - except OSError as e: - if e.errno == errno.EAGAIN: - pass - else: - print("UDP recv OSError Exception") - except Exception: - print("UDP recv Exception") - # Wait before trying to receive again - time.sleep(0.025) -``` - -## Registering with TTN - -To set up the gateway with The Things Network \(TTN\), 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, the nano-gateway can then be registered. To do this, navigate to the TTN Console web page. - -## Registering the Gateway - -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 | - -The Gateway EUI should match your Gateway ID from the `config.py` file. We suggest you follow the procedure described near the top of this document to create your own unique Gateway ID. - -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. Next, one or more nodes can now be configured to use the nano-gateway and TTN applications may be built. - -## LoPy Node - -There are two methods of connecting LoPy devices to the nano-gateway, Over the Air Activation \(OTAA\) and Activation By Personalisation \(ABP\). The code and instructions for registering these methods are shown below, followed by instruction for how to connect them to an application on TTN. - -{% hint style="info" %} -It’s important that the following code examples \(also on GitHub\) are used to connect to the nano-gateway as it only supports single channel connections. -{% endhint %} - -### OTAA \(Over The Air Activation\) - -When the LoPy connects an application \(via TTN\) using OTAA, the network configuration is derived automatically during a handshake between the LoPy and network server. Note that the network keys derived using the OTAA methodology are specific to the device and are used to encrypt and verify transmissions at the network level. - -```python -""" OTAA Node example compatible with the LoPy Nano Gateway """ - -from network import LoRa -import socket -import ubinascii -import struct -import time - -# Initialize LoRa in LORAWAN mode. -lora = LoRa(mode=LoRa.LORAWAN) - -# create an OTA authentication params -dev_eui = ubinascii.unhexlify('AABBCCDDEEFF7778') # these settings can be found from TTN -app_eui = ubinascii.unhexlify('70B3D57EF0003BFD') # these settings can be found from TTN -app_key = ubinascii.unhexlify('36AB7625FE77776881683B495300FFD6') # these settings can be found from TTN - -# set the 3 default channels to the same frequency (must be before sending the OTAA join request) -lora.add_channel(0, frequency=868100000, dr_min=0, dr_max=5) -lora.add_channel(1, frequency=868100000, dr_min=0, dr_max=5) -lora.add_channel(2, frequency=868100000, dr_min=0, dr_max=5) - -# join a network using OTAA -lora.join(activation=LoRa.OTAA, auth=(dev_eui, 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 joined yet...') - -# remove all the non-default channels -for i in range(3, 16): - lora.remove_channel(i) - -# 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) - -time.sleep(5.0) - -""" Your own code can be written below! """ - -for i in range (200): - s.send(b'PKT #' + bytes([i])) - time.sleep(4) - rx = s.recv(256) - if rx: - print(rx) - time.sleep(6) -``` - -### ABP \(Activation By Personalisation\) - -Using ABP join mode requires the user to define the following values and input them into both the LoPy and the TTN Application: - -* Device Address -* Application Session Key -* Network Session Key - -```python -""" ABP Node example compatible with the LoPy Nano Gateway """ - -from network import LoRa -import socket -import ubinascii -import struct -import time - -# Initialise LoRa in LORAWAN mode. -lora = LoRa(mode=LoRa.LORAWAN) - -# create an ABP authentication params -dev_addr = struct.unpack(">l", ubinascii.unhexlify('2601147D'))[0] # these settings can be found from TTN -nwk_swkey = ubinascii.unhexlify('3C74F4F40CAE2221303BC24284FCF3AF') # these settings can be found from TTN -app_swkey = ubinascii.unhexlify('0FFA7072CC6FF69A102A0F39BEB0880F') # these settings can be found from TTN - -# join a network using ABP (Activation By Personalisation) -lora.join(activation=LoRa.ABP, auth=(dev_addr, nwk_swkey, app_swkey)) - -# remove all the non-default channels -for i in range(3, 16): - lora.remove_channel(i) - -# set the 3 default channels to the same frequency -lora.add_channel(0, frequency=868100000, dr_min=0, dr_max=5) -lora.add_channel(1, frequency=868100000, dr_min=0, dr_max=5) -lora.add_channel(2, frequency=868100000, dr_min=0, dr_max=5) - -# 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) - -""" Your own code can be written below! """ - -for i in range (200): - s.send(b'PKT #' + bytes([i])) - time.sleep(4) - rx = s.recv(256) - if rx: - print(rx) - time.sleep(6) -``` - -## TTN Applications - -Now that the gateway & nodes have been setup, a TTN Application can be built; i.e. what happens to the LoRa data once it is received by TTN. There are a number of different setups/systems that can be used, however the following example demonstrates the HTTP request integration. - -## Registering an Application - -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 LoPy nodes must be registered to send data up to the new Application. - -### Registering Devices \(LoPy\) - -To connect nodes to the nano-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` is also user specified but must consist of exactly 8 bytes, given in hexadecimal. - -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. - -### Adding Application Integrations - -Now that the data is arriving on the TTN Backend, TTN can be managed as to where data should be delivered to. To do this, use the `Integrations` tab within the new Application’s settings. - -![](../../.gitbook/assets/ttn-7%20%281%29.png) - -Upon clicking `add integration`, a screen with 4 different options will appear. These have various functionality and more information about them can be found on the TTN website/documentation. - -For this example, use the `HTTP Integration` to forward the LoRaWAN Packets to a remote server/address. - -![](../../.gitbook/assets/ttn-8%20%281%29.png) - -Click `HTTP Integration` to connect up an endpoint that can receive the data. - -For testing, a website called [RequestBin](https://requestb.in/) may be used to receive the data that TTN forwards \(via POST Request\). To set this up, navigate to [RequestBin](https://requestb.in/) and click the `Create a RequestBin`. - -![](../../.gitbook/assets/ttn-9%20%281%29.png) - -Copy the URL that is generated and past this into the `URL` form under the `Application Settings`. - -![](../../.gitbook/assets/ttn-10%20%281%29.png) - -This is the address that TTN will forward data onto. As soon as a LoPy starts sending messages, TTN will forward these onto `RequestBin` and they will appear at the unique `RequestBin URL`. - diff --git a/tutorials-and-examples/lora/lorawan-otaa.md b/tutorials-and-examples/lora/lorawan-otaa.md deleted file mode 100644 index 182d319..0000000 --- a/tutorials-and-examples/lora/lorawan-otaa.md +++ /dev/null @@ -1,54 +0,0 @@ -# LoRaWAN with OTAA - -OTAA stands for Over The Air Authentication. With this method the LoPy sends a Join request to the LoRaWAN Gateway using the `APPEUI` and `APPKEY` provided. If the keys are correct the Gateway will reply to the LoPy with a join accept message and from that point on the LoPy is able to send and receive packets to/from the Gateway. If the keys are incorrect no response will be received and the `has_joined()` method will always return `False`. - -The example below attempts to get any data received after sending the frame. Keep in mind that the Gateway might not be sending any data back, therefore we make the socket non-blocking before attempting to receive, in order to prevent getting stuck waiting for a packet that will never arrive. - -```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...') - -# 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 blocking -# (waits for the data to be sent and for the 2 receive windows to expire) -s.setblocking(True) - -# send some data -s.send(bytes([0x01, 0x02, 0x03])) - -# make the socket non-blocking -# (because if there's no data received it will block forever...) -s.setblocking(False) - -# get any data received (if any...) -data = s.recv(64) -print(data) -``` - diff --git a/tutorials-and-examples/lora/module-module.md b/tutorials-and-examples/lora/module-module.md deleted file mode 100644 index a97e1de..0000000 --- a/tutorials-and-examples/lora/module-module.md +++ /dev/null @@ -1,46 +0,0 @@ -# LoPy to LoPy - -This example shows how to connect two Pycode LoRa capable modules \(nodes\) via raw LoRa. - -## Node A - -```python -from network import LoRa -import socket -import time - -# 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.LORA, region=LoRa.EU868) -s = socket.socket(socket.AF_LORA, socket.SOCK_RAW) -s.setblocking(False) - -while True: - if s.recv(64) == b'Ping': - s.send('Pong') - time.sleep(5) -``` - -## Node B - -```python -from network import LoRa -import socket -import time - -# 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.LORA, region=LoRa.EU868) -s = socket.socket(socket.AF_LORA, socket.SOCK_RAW) -s.setblocking(False) -while True: - s.send('Ping') - time.sleep(5) -``` - diff --git a/tutorials-and-examples/lora/rn2483-to-lopy.md b/tutorials-and-examples/lora/rn2483-to-lopy.md deleted file mode 100644 index 6d14620..0000000 --- a/tutorials-and-examples/lora/rn2483-to-lopy.md +++ /dev/null @@ -1,39 +0,0 @@ -# RN2483 to LoPy - -This example shows how to send data between a Microchip RN2483 and a LoPy via raw LoRa. - -## RN2483 - -```text -mac pause -radio set freq 868000000 - -radio set mod lora -radio set bw 250 -radio set sf sf7 -radio set cr 4/5 -radio set bw 125 -radio set sync 12 -radio set prlen 8 - -# Transmit via radio tx: -radio tx 48656c6C6F #(should send ‘Hello’) -``` - -## LoPy - -```python -from network import LoRa -import socket - -lora = LoRa(mode=LoRa.LORA, frequency= 868000000, 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, public=False) - -s = socket.socket(socket.AF_LORA, socket.SOCK_RAW) - -# This keeps listening for data "forever". -while(True): - s.recv(64) -``` - diff --git a/tutorials-and-examples/lte/README.md b/tutorials-and-examples/lte/README.md deleted file mode 100644 index c572242..0000000 --- a/tutorials-and-examples/lte/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# LTE Examples - -The following tutorials demonstrate the use of the LTE CAT-M1 and NB-IoT functionality on cellular enabled Pycom modules. - -Our cellular modules support both LTE CAT-M1 and NB-IoT, these are new lower power, long range, cellular protocols. These are not the same as the full version of 2G/3G/LTE supported by cell phones, and require your local carriers to support them. At the time of writing, CAT-M1 and NB-IoT connectivity is not widely available so be sure to check with local carriers if support is available where you are. - diff --git a/tutorials-and-examples/lte/cat-m1.md b/tutorials-and-examples/lte/cat-m1.md deleted file mode 100644 index b56c677..0000000 --- a/tutorials-and-examples/lte/cat-m1.md +++ /dev/null @@ -1,43 +0,0 @@ -# CAT-M1 - -{% hint style="info" %} -Please ensure you have the latest Sequans modem firmware for the best network compatibility. Instructions for this can be found [here](firmware.md). -{% endhint %} - -The LTE Cat M1 service gives full IP access through the cellular modem. - -Once the `lte.connect()` function has completed all the IP socket functions - including SSL - will be routed through this connection. This mean any code using WLAN can be adapted to Cat M1 by simply adding the connection setup step first and disconnect after. - -For example to connect over LTE Cat M1 to Google's web server over secure SSL: - -```python -import socket -import ssl -import time -from network import LTE - -lte = LTE() # instantiate the LTE object -lte.attach() # attach the cellular modem to a base station -while not lte.isattached(): - time.sleep(0.25) -lte.connect() # start a data session and obtain an IP address -while not lte.isconnected(): - time.sleep(0.25) - -s = socket.socket() -s = ssl.wrap_socket(s) -s.connect(socket.getaddrinfo('www.google.com', 443)[0][-1]) -s.send(b"GET / HTTP/1.0\r\n\r\n") -print(s.recv(4096)) -s.close() - -lte.disconnect() -lte.dettach() -``` - -This also applies to our MQTT and AWS examples. - -**IMPORTANT:** Once the LTE radio is initialised, it must be de-initialised before going to deepsleep in order to ensure minimum power consumption. 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\). - -When using the expansion board and the FiPy together, the RTS/CTS jumpers **MUST** be removed as those pins are being used by the LTE radio. Keeping those jumpers in place will lead to erratic operation and higher current consumption specially while in deepsleep. - diff --git a/tutorials-and-examples/lte/firmware.md b/tutorials-and-examples/lte/firmware.md deleted file mode 100644 index 61513c2..0000000 --- a/tutorials-and-examples/lte/firmware.md +++ /dev/null @@ -1,218 +0,0 @@ -# Modem Firmware Update - -{% hint style="info" %} -This article is only related to GPy, FiPy, and G01 boards -{% endhint %} - -{% hint style="danger" %} -**Important**: When upgrading your modem for the first time, even if you have updated it in the past with the old firmware update method, you **MUST** use the "recovery" upgrade method described below. Otherwise you will risk breaking your module -{% endhint %} - -Please read the following instructions carefully as there are some significant changes compared to the previous updater version. - -Most importantly, the updater is now integrated in the latest stable firmware release \(we will also publish a new development and pybytes firmware in the coming days\), so you no longer need to upload any scripts to your module. The built-in updater will take precedence over any scripts uploaded. - -Please start with the following steps: - -1. Upgrade the Pycom Firmware Updater tool to latest version -2. Select Firmware Type `stable` in the communication window to upgrade to version `v1.18.1.r1` - -You can find the different versions of firmwares available here: [https://software.pycom.io/downloads/sequans.html](https://software.pycom.io/downloads/sequans2.html) - -These files are password protected, to download them you should be a forum.pycom.io member and access to: Announcements & News --> Announcements only for members --> Firmware Files for Sequans LTE modem now are secured, or clicking [Here](https://forum.pycom.io/topic/4020/firmware-files-for-sequans-lte-modem-now-are-secured). - -We are using `CATM1-38638.zip` and `NB1-37781.zip` as examples in this tutorial. - -After unpacking the zip archive, you will find each firmware packages contains two files, one being the firmware file \(e.g. `CATM1-38638.dup` or `NB1-37781.dup`\) and the `updater.elf` file, which is required when using the "recovery" firmware update method or if a previous upgrade failed and the modem is in recovery mode. - -Please note that the `updater.elf` file is only around 300K so you can also store it inside the flash file system of the module. The firmware dup files will NOT fit into the available `/flash` file system on the module, so you either need to use an SD card or upload it directly from your computer. - -## Via SD card - -To transfer the firmware files onto the SD card you have two options: - -1. Format your SD card as with the FAT file system and then copy the files onto the card using your computer -2. Make sure your SD card has an MBR and a single primary partition, the format it directly on the module, mount it and transfer the firmware files onto the SD card using FTP. Please ensure the transfer is successful and that each file on the module has the same size as the original file on your PC. - -```python -from machine import SD - -sd = SD() -os.mkfs(sd) # format SD card -os.mount(sd, '/sd') # mount it -os.listdir('/sd') # list its content -``` - -Once you copied/uploaded the firmware files on to the SD card you can flash the LTE modem using the following command: - -To flash the CAT-M1 firmware onto your device using the recovery method: - -```python -import sqnsupgrade -sqnsupgrade.run('/sd/CATM1-38638.dup', '/sd/updater.elf') -``` - -To flash the NB-IoT firmware onto your device using the recovery method: - -```python -import sqnsupgrade -sqnsupgrade.run('/sd/NB1-37781.dup', '/sd/updater.elf') -``` - -Please note you can directly flash the desired firmware onto your module, it is not necessary to upgrade to the latest CAT-M1 firmware before switching to NB-IoT. - -If you have already mounted the SD card, please use the path you used when mounting it. Otherwise, if an absolute path other than `/flash` is specified, the script will automatically mount the SD card using the path specified. - -Once update is finished successfully you will have a summary of new updated versions. The full output from the upgrade will looks similar to this: - -```text -<<< Welcome to the SQN3330 firmware updater >>> -Attempting AT wakeup... -Starting STP (DO NOT DISCONNECT POWER!!!) -Session opened: version 1, max transfer 8192 bytes -Sending 54854 bytes: [########################################] 100% -Bootrom updated successfully, switching to upgrade mode -Attempting AT auto-negotiation... -Session opened: version 1, max transfer 2048 bytes -Sending 306076 bytes: [########################################] 100% -Attempting AT wakeup... -Upgrader loaded successfully, modem is in upgrade mode -Attempting AT wakeup... -Starting STP ON_THE_FLY -Session opened: version 1, max transfer 8192 bytes -Sending 5996938 bytes: [########################################] 100% -Code download done, returning to user mode -Resetting (DO NOT DISCONNECT POWER!!!)................ -Upgrade completed! -Here's the current firmware version: - -SYSTEM VERSION -============== - FIRMWARE VERSION - Bootloader0 : 5.1.1.0 [33080] - Bootloader1 : 5.1.1.0 [38638] - Bootloader2* : 5.1.1.0 [38638] - NV Info : 1.1,0,0 - Software : 5.1.1.0 [38638] by robot-soft at 2018-08-20 09:51:46 - UE : 5.0.0.0d - COMPONENTS - ZSP0 : 1.0.99-13604 - ZSP1 : 1.0.99-12341 -``` - -{% hint style="info" %} -Please note that the firmware update may seem to "stall" around 7-10% and again at 99%. This is not an indication of a failure but the fact that the modem has to do some tasks during and the updater will wait for these tasks to be completed. Unless the upgrade process is hanging for more than 5 minutes, **do not interrupt the process** as you will have to start again if you don't finish it. It may also take several minutes for the updater to load before responding to the AT wakeup command. -{% endhint %} - -After you have updated your modem once using the recovery method, you can now flash your modem again using just the `CATM1-38638.dup` or `NB1-37781.dup` file without specifying the `updater.elf` file. However, should the upgrade fail, your modem may end up in recovery mode and you will need the `updater.elf` file again. The updater will check for this and prompt you if using the `updater.elf` file is necessary. - -Example output using just the firmware file: - -```text -<<< Welcome to the SQN3330 firmware updater >>> -Attempting AT wakeup... - -Starting STP ON_THE_FLY -Session opened: version 1, max transfer 8192 bytes -Sending 5996938 bytes: [########################################] 100% -Code download done, returning to user mode -Resetting (DO NOT DISCONNECT POWER!!!)............................................................................ -Upgrade completed! -Here's the current firmware version: - -SYSTEM VERSION -============== - FIRMWARE VERSION - Bootloader0 : 5.1.1.0 [33080] - Bootloader1* : 5.1.1.0 [38638] - Bootloader2 : 5.1.1.0 [38638] - NV Info : 1.1,0,0 - Software : 5.1.1.0 [38638] by robot-soft at 2018-08-20 09:51:46 - UE : 5.0.0.0d - COMPONENTS - ZSP0 : 1.0.99-13604 - ZSP1 : 1.0.99-12341 -``` - -## Via UART Serial Interface - -If you can't use an SD card to hold the firmware images, you can use the existing UART interface you have with the board to load these firmware files from your Computer. - -You will need the following software installed on your computer: - -1. [Python 3](https://www.python.org/downloads), if it's not directly available through your OS distributor -2. [PySerial](https://pythonhosted.org/pyserial/pyserial.html#installation) - -You will also need to download the following Python scripts: [https://github.com/pycom/pycom-libraries/tree/master/lib/sqnsupgrade](https://github.com/pycom/pycom-libraries/tree/master/lib/sqnsupgrade) - -**Important**: When upgrading your modem for the first time, even if you have updated it in the past with the old firmware update method, you **MUST** use the "recovery" upgrade method described below. Otherwise, you will risk breaking your module. - -You can upload the `updater.elf` file to the module's flash file system rather than uploading it via UART directly to the modem, which will slightly increase the speed of the upgrade. - -First, you need to prepare your modem for upgrade mode by using the following commands. - -### **Commands to run on the Pycom module** - -To use the recovery method: - -```python -import sqnsupgrade -sqnsupgrade.uart(True) -``` - -To use the recovery method using the `updater.elf` file on the module**:** - -```python - import sqnsupgrade - sqnsupgrade.uart(True,'/flash/updater.elf') -``` - -To use the normal method: - -```python - import sqnsupgrade - sqnsupgrade.uart() -``` - -After this command is executed a message will be displayed asking you to close the port. - -```text -Going into MIRROR mode... please close this terminal to resume the upgrade via UART -``` - -### **Commands to be run on your computer** - -You must close the terminal/Atom or Visual Studio Code console to run the following commands from your computer: - -Go to the directory where you saved the `sqnsupgrade` scripts and run the following commands in terminal: - -When using the recovery method: - -```python -$ python3 -Python 3.6.5 (default, Apr 25 2018, 14:23:58) -[GCC 4.2.1 Compatible Apple LLVM 9.1.0 (clang-902.0.39.1)] on darwin -Type "help", "copyright", "credits" or "license" for more information. ->>> ->>> import sqnsupgrade ->>> sqnsupgrade.run('Serial_Port', '/path/to/CATM1-38638.dup', '/path/to/updater.elf') -``` - -When using the standard method \(or if the `updater.elf` was loaded on the module\): - -```python - $ python3 - Python 3.6.5 (default, Apr 25 2018, 14:23:58) - [GCC 4.2.1 Compatible Apple LLVM 9.1.0 (clang-902.0.39.1)] on darwin - Type "help", "copyright", "credits" or "license" for more information. - >>> - >>> import sqnsupgrade - >>> sqnsupgrade.run('Serial_Port', '/path/to/CATM1-38638.dup') -``` - -Please note that the firmware update may seem to "stall" around 7-10% and again at 99%. This is not an indication of a failure but the fact that the modem has to do some tasks during and the updater will wait for these tasks to be completed. Unless the upgrade process is hanging for more than 5 minutes, **do not interrupt the process** as you will have to start again if you don't finish it. It may also take several minutes for the updater to load before responding to the AT wakeup command. - -## Retrying process - -In case of any failure or interruption to the process of LTE modem upgrade you can repeat the same steps **after doing a hard reset to the board \(i.e disconnecting and reconnecting power\), pressing the reset button is not enough.** - diff --git a/tutorials-and-examples/lte/imei.md b/tutorials-and-examples/lte/imei.md deleted file mode 100644 index dff1d81..0000000 --- a/tutorials-and-examples/lte/imei.md +++ /dev/null @@ -1,20 +0,0 @@ -# Module IMEI - -In order to retrieve the IMEI of your cellular enabled Pycom module you will firstly need to make sure you are on firmware version `1.17.0.b1` or higher. You can check your firmware version by running the following code on you device via the interactive REPL. - -```python ->>> import os ->>> os.uname() -(sysname='GPy', nodename='GPy', release='1.17.0.b1', version='v1.8.6-849-d0dc708 on 2018-02-27', machine='GPy with ESP32') -``` - -Once you have a compatible firmware, you can run the following code to get your modules IMEI number: - -```python -from network import LTE -lte = LTE() -lte.send_at_cmd('AT+CGSN=1') -``` - -You’ll get a return string like this `\r\n+CGSN: "354347xxxxxxxxx"\r\n\r\nOK`. The value between the double quotes is your IMEI. - diff --git a/tutorials-and-examples/lte/nb-iot.md b/tutorials-and-examples/lte/nb-iot.md deleted file mode 100644 index e0a8f4b..0000000 --- a/tutorials-and-examples/lte/nb-iot.md +++ /dev/null @@ -1,37 +0,0 @@ -# NB-IoT - -## LTE class for Narrow Band IoT - -{% hint style="info" %} -As shipped, Pycom modules only support CAT-M1, in order to use NB-IoT you need to flash a different firmware to the Sequans modem. Instructions for this can be found [here](firmware.md). -{% endhint %} - -## NB-IoT usage - -Example with Vodafone: - -```python -from network import LTE - -lte = LTE() -lte.send_at_cmd('AT+CFUN=0') -lte.send_at_cmd('AT!="clearscanconfig"') -lte.send_at_cmd('AT!="addscanband band=20"') -lte.send_at_cmd('AT!="disablelog 1"') -lte.send_at_cmd('AT+CGDCONT=1,"IP","nb.inetd.gdsp"') -lte.send_at_cmd('AT+CFUN=1') - -while not lte.isattached(): - pass - -lte.connect() -while not lte.isconnected(): - pass - -# now use socket as usual... -``` - -**IMPORTANT:** Once the LTE radio is initialised, it must be de-initialised before going to deepsleep in order to ensure minimum power consumption. 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\). - -When using the expansion board and the FiPy together, the RTS/CTS jumpers **MUST** be removed as those pins are being used by the LTE radio. Keeping those jumpers in place will lead to erratic operation and higher current consumption specially while in deepsleep. - diff --git a/tutorials-and-examples/pyscan.md b/tutorials-and-examples/pyscan.md deleted file mode 100644 index b77f3dc..0000000 --- a/tutorials-and-examples/pyscan.md +++ /dev/null @@ -1,58 +0,0 @@ -# Pyscan Examples - -This basic example shows how to read an NFC card and authenticate it using a pre-defined access list. - -```python -from pyscan import Pyscan -from MFRC630 import MFRC630 -import time -import pycom -import _thread - -VALID_CARDS = [[0x43, 0x95, 0xDD, 0xF8], - [0x43, 0x95, 0xDD, 0xF9]] - -py = Pyscan() -nfc = MFRC630(py) - -RGB_BRIGHTNESS = 0x8 - -RGB_RED = (RGB_BRIGHTNESS << 16) -RGB_GREEN = (RGB_BRIGHTNESS << 8) -RGB_BLUE = (RGB_BRIGHTNESS) - -# Make sure heartbeat is disabled before setting RGB LED -pycom.heartbeat(False) - -# Initialise the MFRC630 with some settings -nfc.mfrc630_cmd_init() - -def check_uid(uid, len): - return VALID_CARDS.count(uid[:len]) - -def discovery_loop(nfc, id): - while True: - # Send REQA for ISO14443A card type - atqa = nfc.mfrc630_iso14443a_WUPA_REQA(nfc.MFRC630_ISO14443_CMD_REQA) - if (atqa != 0): - # A card has been detected, read UID - uid = bytearray(10) - uid_len = nfc.mfrc630_iso14443a_select(uid) - if (uid_len > 0): - if (check_uid(list(uid), uid_len)) > 0: - pycom.rgbled(RGB_GREEN) - else: - pycom.rgbled(RGB_RED) - else: - # No card detected - pycom.rgbled(RGB_BLUE) - nfc.mfrc630_cmd_reset() - time.sleep(.5) - nfc.mfrc630_cmd_init() - -# This is the start of our main execution... start the thread -_thread.start_new_thread(discovery_loop, (nfc, 0)) -``` - -You can find this, and all the other examples in our [pycom-libraries GitHub repository](https://github.com/pycom/pycom-libraries) - diff --git a/tutorials-and-examples/pysense.md b/tutorials-and-examples/pysense.md deleted file mode 100644 index 4d67d2f..0000000 --- a/tutorials-and-examples/pysense.md +++ /dev/null @@ -1,23 +0,0 @@ -# Pysense Examples - -## Accelerometer - -This basic example shows how to read pitch and roll from the on-board accelerometer and output it in comma separated value \(CSV\) format over serial. - -```python -from LIS2HH12 import LIS2HH12 -from pytrack import Pytrack -py = Pytrack() -acc = LIS2HH12() - -while True: - pitch = acc.pitch() - roll = acc.roll() - print('{},{}'.format(pitch, roll)) - time.sleep_ms(100) -``` - -![](../.gitbook/assets/accelerometer_visualiser%20%281%29.png) - -If you want to visualise the data output by this script a Processing sketch is available [here](https://github.com/pycom/pycom-libraries/tree/master/examples/pytrack_pysense_accelerometer) that will show the board orientation in 3D. - diff --git a/tutorials-and-examples/pytrack.md b/tutorials-and-examples/pytrack.md deleted file mode 100644 index 89a9dae..0000000 --- a/tutorials-and-examples/pytrack.md +++ /dev/null @@ -1,50 +0,0 @@ -# Pytrack Examples - -Both the Pysense and Pytrack use the same accelerometer. Please see the [Pysense Examples](pysense.md) to see how to use the accelerometer. - -## Example - -You can find this example in the [pycom/pycom-libraries](https://github.com/pycom/pycom-libraries) GitHub repository. - -```python -import machine -import math -import network -import os -import time -import utime -import gc -from machine import RTC -from machine import SD -from L76GNSS import L76GNSS -from pytrack import Pytrack - -time.sleep(2) -gc.enable() - -# setup rtc -rtc = machine.RTC() -rtc.ntp_sync("pool.ntp.org") -utime.sleep_ms(750) -print('\nRTC Set from NTP to UTC:', rtc.now()) -utime.timezone(7200) -print('Adjusted from UTC to EST timezone', utime.localtime(), '\n') - -py = Pytrack() -l76 = L76GNSS(py, timeout=30) - -# sd = SD() -# os.mount(sd, '/sd') -# f = open('/sd/gps-record.txt', 'w') - -while (True): - coord = l76.coordinates() - #f.write("{} - {}\n".format(coord, rtc.now())) - print("{} - {} - {}".format(coord, rtc.now(), gc.mem_free())) -``` - -## Alternative Libraries - -* [micropyGPS](https://github.com/inmcm/micropyGPS) -* [Alternative L76GNSS module](https://github.com/andrethemac/L76GLNSV4/blob/master/L76GNSV4.py) - diff --git a/tutorials-and-examples/sigfox.md b/tutorials-and-examples/sigfox.md deleted file mode 100644 index 29a4c1e..0000000 --- a/tutorials-and-examples/sigfox.md +++ /dev/null @@ -1,50 +0,0 @@ -# Sigfox Examples - -Before you start, make sure that your device was registered with [Sigfox](../getting-started/registration/sigfox.md). - -The following tutorials demonstrate how to register and get started with the SiPy. The board can be configured for operation in various countries based upon specified RCZ zones \(see the `Sigfox` class for more info\). The SiPy, LoPy 4, and FiPy supports both uplink and downlink `Sigfox` messages as well as device to device communication via its FSK Mode `Sigfox`. - -```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 %} - -## Disengage Sequence Number - -If your are experiencing issues with Sigfox connectivity, this could be due to the sequence number being out of sync. To prevent replay on the network, the Sigfox protocol uses sequence numbers. If there is a large difference between the sequence number sent by the device and the one expected by the backend, your message is dropped by the network. - -You can use the `Disengage sequence number` button on the device information or on the device type information page of the Sigfox backend to reset the number expected by the backend. If the sequence number of your next message is different from the last trashed sequence number, the message will be accepted. - -Issues with the sequence number can occur when a lot of messages are sent when outside of Sigfox coverage for instance. - -Firstly you will need to log into the [Sigfox Backend](https://backend.sigfox.com), navigate to device, and click on the Sigfox ID of the affected SiPy. - -![](../.gitbook/assets/seq_dis_1-1.png) - -You should now see the Information page with an entry `Device Type:` followed by a link. Please follow the link - -![screenshot of sigfox ID](../.gitbook/assets/seq_dis_2%20%281%29.png) - -Finally, on this page click on `Disengage sequence number` button in the upper right corner. - -![screenshot of sigfox ID](../.gitbook/assets/seq_dis_3.png) -