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

GitBook: [master] 331 pages modified

Browse Source
This commit is contained in:
Daniel Spindelbauer
2018-09-04 10:13:29 +00:00
committed by gitbook-bot
parent f179b56b33
commit 514f62ebce
169 changed files with 289 additions and 289 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,249 +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.
#### bluetooth.deinit\(\)
Disables the Bluetooth radio.
#### bluetooth.start\_scan\(timeout\)
Starts performing a scan listening for BLE devices sending advertisements. This function always returns immediately, the scanning will be performed on the background. The return value is `None`. After starting the scan the function `get_adv()` can be used to retrieve the advertisements messages from the FIFO. The internal FIFO has space to cache 16 advertisements.
The arguments are:
* `timeout` specifies the amount of time in seconds to scan for advertisements, cannot be zero. If timeout is > 0, then the BLE radio will listen for advertisements until the specified value in seconds elapses. If timeout < 0, then there’s no timeout at all, and stop\_scan\(\) needs to be called to cancel the scanning process.
Examples:
```python
bluetooth.start_scan(10) # starts scanning and stop after 10 seconds
bluetooth.start_scan(-1) # starts scanning indefinitely until bluetooth.stop_scan() is called
```
#### bluetooth.stop\_scan\(\)
Stops an ongoing scanning process. Returns `None`.
#### bluetooth.isscanning\(\)
Returns `True` if a Bluetooth scan is in progress. `False` otherwise.
#### bluetooth.get\_adv\(\)
Gets an named tuple with the advertisement data received during the scanning. The tuple has the following structure: `(mac, addr_type, adv_type, rssi, data)`
* `mac` is the 6-byte ling mac address of the device that sent the advertisement.
* `addr_type` is the address type. See the constants section below for more details.
* `adv_type` is the advertisement type received. See the constants section below fro more details.
* `rssi` is signed integer with the signal strength of the advertisement.
* `data` contains the complete 31 bytes of the advertisement message. In order to parse the data and get the specific types, the method `resolve_adv_data()` can be used.
Example for getting `mac` address of an advertiser:
```python
import ubinascii
bluetooth = Bluetooth()
bluetooth.start_scan(20) # scan for 20 seconds
adv = bluetooth.get_adv() #
ubinascii.hexlify(adv.mac) # convert hexadecimal to ascii
```
#### bluetooth.get\_advertisements\(\)
Same as the `get_adv()` method, but this one returns a list with all the advertisements received.
#### bluetooth.resolve\_adv\_data\(data, data\_type\)
Parses the advertisement data and returns the requested `data_type` if present. If the data type is not present, the function returns `None`.
Arguments:
* `data` is the bytes object with the complete advertisement data.
* `data_type` is the data type to resolve from from the advertisement data. See constants section below for details.
Example:
```python
import ubinascii
from network import Bluetooth
bluetooth = Bluetooth()
bluetooth.start_scan(20)
while bluetooth.isscanning():
adv = bluetooth.get_adv()
if adv:
# try to get the complete name
print(bluetooth.resolve_adv_data(adv.data, Bluetooth.ADV_NAME_CMPL))
mfg_data = bluetooth.resolve_adv_data(adv.data, Bluetooth.ADV_MANUFACTURER_DATA)
if mfg_data:
# try to get the manufacturer data (Apple's iBeacon data is sent here)
print(ubinascii.hexlify(mfg_data))
```
#### bluetooth.connect\(mac\_addr\)
Opens a BLE connection with the device specified by the `mac_addr` argument. This function blocks until the connection succeeds or fails. If the connections succeeds it returns a object of type `GATTCConnection`.
```python
bluetooth.connect('112233eeddff') # mac address is accepted as a string
```
#### bluetooth.callback\(trigger=None, handler=None, arg=None\)
Creates a callback that will be executed when any of the triggers occurs. The arguments are:
* `trigger` can be either `Bluetooth.NEW_ADV_EVENT`, `Bluetooth.CLIENT_CONNECTED`, or `Bluetooth.CLIENT_DISCONNECTED`
* `handler` is the function that will be executed when the callback is triggered.
* `arg` is the argument that gets passed to the callback. If nothing is given the bluetooth object itself is used.
An example of how this may be used can be seen in the [`bluetooth.events()`](./#bluetooth-events) method.
#### bluetooth.events\(\)
Returns a value with bit flags identifying the events that have occurred since the last call. Calling this function clears the events.
Example of usage:
```python
from network import Bluetooth
bluetooth = Bluetooth()
bluetooth.set_advertisement(name='LoPy', service_uuid=b'1234567890123456')
def conn_cb (bt_o):
events = bt_o.events() # this method returns the flags and clears the internal registry
if events & Bluetooth.CLIENT_CONNECTED:
print("Client connected")
elif events & Bluetooth.CLIENT_DISCONNECTED:
print("Client disconnected")
bluetooth.callback(trigger=Bluetooth.CLIENT_CONNECTED | Bluetooth.CLIENT_DISCONNECTED, handler=conn_cb)
bluetooth.advertise(True)
```
#### bluetooth.set\_advertisement\(\* , name=None, manufacturer\_data=None, service\_data=None, service\_uuid=None\)
Configure the data to be sent while advertising. If left with the default of `None` the data won’t be part of the advertisement message.
The arguments are:
* `name` is the string name to be shown on advertisements.
* `manufacturer_data` manufacturer data to be advertised \(hint: use it for iBeacons\).
* `service_data` service data to be advertised.
* `service_uuid` uuid of the service to be advertised.
Example:
```python
bluetooth.set_advertisement(name="advert", manufacturer_data="lopy_v1")
```
#### bluetooth.advertise\(\[Enable\]\)
Start or stop sending advertisements. The `set_advertisement()` method must have been called prior to this one.
#### bluetooth.service\(uuid, \* , isprimary=True, nbr\_chars=1, start=True\)
Create a new service on the internal GATT server. Returns a object of type `BluetoothServerService`.
The arguments are:
* `uuid` is the UUID of the service. Can take an integer or a 16 byte long string or bytes object.
* `isprimary` selects if the service is a primary one. Takes a `bool` value.
* `nbr_chars` specifies the number of characteristics that the service will contain.
* `start` if `True` the service is started immediately.
```python
bluetooth.service('abc123')
```
#### bluetooth.disconnect\_client\(\)
Closes the BLE connection with the client.
## Constants
* Bluetooth mode: `Bluetooth.BLE`
* Advertisement type: `Bluetooth.CONN_ADV`, `Bluetooth.CONN_DIR_ADV`, `Bluetooth.DISC_ADV`, `Bluetooth.NON_CONN_ADV`, `Bluetooth.SCAN_RSP`
* Address type: `Bluetooth.PUBLIC_ADDR`, `Bluetooth.RANDOM_ADDR`, `Bluetooth.PUBLIC_RPA_ADDR`, `Bluetooth.RANDOM_RPA_ADDR`
* Advertisement data type: `Bluetooth.ADV_FLAG`, `Bluetooth.ADV_16SRV_PART`, `Bluetooth.ADV_T16SRV_CMPL`, `Bluetooth.ADV_32SRV_PART`, `Bluetooth.ADV_32SRV_CMPL`, `Bluetooth.ADV_128SRV_PART`, `Bluetooth.ADV_128SRV_CMPL`, `Bluetooth.ADV_NAME_SHORT`, `Bluetooth.ADV_NAME_CMPL`, `Bluetooth.ADV_TX_PWR`, `Bluetooth.ADV_DEV_CLASS`, `Bluetooth.ADV_SERVICE_DATA`, `Bluetooth.ADV_APPEARANCE`, `Bluetooth.ADV_ADV_INT`, `Bluetooth.ADV_32SERVICE_DATA`, `Bluetooth.ADV_128SERVICE_DATA`, `Bluetooth.ADV_MANUFACTURER_DATA`
* Characteristic properties \(bit values that can be combined\): `Bluetooth.PROP_BROADCAST`, `Bluetooth.PROP_READ`, `Bluetooth.PROP_WRITE_NR`, `Bluetooth.PROP_WRITE`, `Bluetooth.PROP_NOTIFY`, `Bluetooth.PROP_INDICATE`, `Bluetooth.PROP_AUTH`, `Bluetooth.PROP_EXT_PROP`
* Characteristic callback events: `Bluetooth.CHAR_READ_EVENT`, `Bluetooth.CHAR_WRITE_EVENT`, `Bluetooth.NEW_ADV_EVENT`, `Bluetooth.CLIENT_CONNECTED`, `Bluetooth.CLIENT_DISCONNECTED`, `Bluetooth.CHAR_NOTIFY_EVENT`
* Antenna type: `Bluetooth.INT_ANT`, `Bluetooth.EXT_ANT`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,125 +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\(\)
Disables LTE modem completely. This reduces the power consumption to the minimum. Call this before entering deepsleep.
#### lte.attach\(\*, band=None\)
Enable radio functionality and attach to the LTE Cat M1 network authorised by the inserted SIM card. Optionally specify the band to scan for networks. If no band \(or `None`\) is specified, all 6 bands will be scanned. The possible values for the band are: `3, 4, 12, 13, 20 and 28`.
#### lte.isattached\(\)
Returns `True` if the cellular mode is attached to the network. `False` otherwise.
#### lte.dettach\(\)
Detach the modem from the LTE Cat M1 and disable the radio functionality.
#### lte.connect\(\*, cid=1\)
Start a data session and obtain and IP address. Optionally specify a CID \(Connection ID\) for the data session. The arguments are:
* `cid` is a Connection ID. This is carrier specific, for Verizon use `cid=3`. For others like Telstra it should be `cid=1`.
For instance, to attach and connect to Verizon:
```python
import time
from network import LTE
lte = LTE(carrier="verizon")
lte.attach(band=13)
while not lte.isattached():
time.sleep(0.5)
print('Attaching...')
lte.connect(cid=3)
while not lte.isconnected():
time.sleep(0.5)
print('Connecting...')
# Now use sockets as usual...
```
#### lte.isconnected\(\)
Returns `True` if there is an active LTE data session and IP address has been obtained. `False` otherwise.
#### lte.disconnect\(\)
End the data session with the network.
#### lte.send\_at\_cmd\(cmd\)
Send an AT command directly to the modem. Returns the raw response from the modem as a string object. **IMPORTANT:** If a data session is active \(i.e. the modem is _connected_\), sending the AT commands requires to pause and then resume the data session. This is all done automatically, but makes the whole request take around 2.5 seconds.
Example:
```python
lte.send_at_cmd('AT+CEREG?') # check for network registration manually (sames as lte.isattached())
```
Optionally the response can be parsed for pretty printing:
```python
def send_at_cmd_pretty(cmd):
response = lte.send_at_cmd(cmd).split('\r\n')
for line in response:
print(line)
send_at_cmd_pretty('AT!="showphy"') # get the PHY status
send_at_cmd_pretty('AT!="fsm"') # get the System FSM
```
#### lte.imei\(\)
Returns a string object with the IMEI number of the LTE modem.
#### lte.iccid\(\)
Returns a string object with the ICCID number of the SIM card.
#### lte.reset\(\)
Perform a hardware reset on the cellular modem. This function can take up to 5 seconds to return as it waits for the modem to shutdown and reboot.

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

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

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

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

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

@@ -1,156 +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)
```
#### wlan.deinit\(\)
Disables the WiFi radio.
#### wlan.connect\(ssid, \* , auth=None, bssid=None, timeout=None, ca\_certs=None, keyfile=None, certfile=None, identity=None\)
Connect to a wifi access point using the given SSID, and other security parameters.
* `auth` is a tuple with `(sec, key)`. Security can be `None`, `WLAN.WEP`, `WLAN.WPA`, `WLAN.WPA2` or `WLAN.WPA2_ENT`. The key is a string with the network password.
* If `sec` is `WLAN.WEP` the key must be a string representing hexadecimal values \(e.g. `ABC1DE45BF`\).
* If `sec` is `WLAN.WPA2_ENT` then the `auth` tuple can have either 3 elements: `(sec, username, password)`, or just 1: `(sec,)`. When passing the 3 element tuple, the`keyfile` and `certifle` arguments must not be given.
* `bssid` is the MAC address of the AP to connect to. Useful when there are several APs with the same SSID.
* `timeout` is the maximum time in milliseconds to wait for the connection to succeed.
* `ca_certs` is the path to the CA certificate. This argument is not mandatory.
* `keyfile` is the path to the client key. Only used if `username` and `password` are not part of the `auth` tuple.
* `certfile` is the path to the client certificate. Only used if `username` and `password` are not part of the `auth` tuple.
* `identity` is only used in case of `WLAN.WPA2_ENT` security. Needed by the server.
{% hint style="info" %}
The ESP32 only handles certificates with `pkcs8` format \(but not the "Traditional SSLeay RSAPrivateKey" format\). The private key should be RSA coded with 2048 bits at maximum.
{% endhint %}
#### wlan.scan\(\)
Performs a network scan and returns a list of named tuples with `(ssid, bssid, sec, channel, rssi)`. Note that channel is always `None` since this info is not provided by the WiPy.
#### wlan.disconnect\(\)
Disconnect from the WiFi access point.
#### wlan.isconnected\(\)
In case of STA mode, returns `True` if connected to a WiFi access point and has a valid IP address. In AP mode returns `True` when a station is connected, `False` otherwise.
#### wlan.ifconfig\(id=0, config=\['dhcp' or configtuple\]\)
When `id` is 0, the configuration will be get/set on the Station interface. When `id` is 1 the configuration will be done for the AP interface.
With no parameters given returns a 4-tuple of `(ip, subnet_mask, gateway, DNS_server)`.
If `dhcp` is passed as a parameter then the DHCP client is enabled and the IP params are negotiated with the AP.
If the 4-tuple config is given then a static IP is configured. For instance:
```python
wlan.ifconfig(config=('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
```
#### wlan.mode\(\[mode\]\)
Get or set the WLAN mode.
#### wlan.ssid\(\[ssid\]\)
Get or set the SSID when in AP mode.
#### wlan.auth\(\[auth\]\)
Get or set the authentication type when in AP mode.
#### wlan.channel\(\[channel\]\)
Get or set the channel \(only applicable in AP mode\).
#### wlan.antenna\(\[antenna\]\)
Get or set the antenna type \(external or internal\).
#### wlan.mac\(\)
Get a 6-byte long `bytes` object with the WiFI MAC address.
## Constants
* WLAN mode: `WLAN.STA`, `WLAN.AP`, `WLAN.STA_AP`
* WLAN network security: `WLAN.WEP`, `WLAN.WPA`, `WLAN.WPA2`, `WLAN.WPA2_ENT`
* Antenna type: `WLAN.INT_ANT`, `WLAN.EXT_ANT`

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

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