micropython-samples/pyboard_d/README.md

Unofficial guide to the Pyboard D

Note: official docs may now be found here so I expect to remove this guide soon.

LED's

The board has one RGB led. Each colour is addressed as pyb.LED(n) where n is in range 1 (R) to 3 (B).

Accel

These boards do not have an accelerometer.

WiFi

After a power cycle a connection must be established with explicit credentials: the board behaves more like ESP32 than ESP8266. If a WiFi outage occurs it will attempt automatically to reconnect. The following code fragments may be used.

wl = network.WLAN()
wl.connect(my_ssid, my_password)
wl.active(1)
print(wl)

It can be in state down, join or up. down means that it's not trying to connect. join means it's trying to connect and get an IP address, and up means it's connected with an IP address and ready to send/receive. If the AP disappears then it goes from up to join, and will go back to up if the AP reappears. wl.status() will give numeric values of these states:
0=down, 1 and 2 mean join (different variants of it), 3=``up`.

You can also debug the wlan using tracing:

wl = network.WLAN()
wl.config(trace=value)

value can be a bit-wise or of 1=async-events, 2=eth-tx, 4=eth-rx. So:

wl = network.WLAN()
wl.config(trace=7)  # To see everything.
wl.config(trace=0)  # To stop

This will work on both STA and AP interfaces, so you can watch how two PYBD's connect to each other.

Setting antenna type and TX power

wl = network.WLAN()
wl.config(antenna=value)  # 0 internal 1 external
wl.config(txpower=value)  # In dbm

Flash memory

The SF2W and SF3W have 512KiB of internal flash, the SF6W has 2048KiB. All have two external 2048KiB flash chips, one for the filesystem and the other for executable code (it can be memory mapped). On SF2W and SF3W, if you freeze a lot of code the firmware can become too big for the internal flash. To put frozen code in external flash, edit the file ports/stm32/boards/PYBD_SF2/f722_qspi.ld (or the corresponding one for PYBD_SF3 to add the line *frozen_content.o(.text* .rodata*):

     .text_ext :
     {
         . = ALIGN(4);
         *frozen_content.o(.text* .rodata*)
         *lib/btstack/*(.text* .rodata*)
         *lib/mbedtls/*(.text* .rodata*)
         . = ALIGN(512);
         *(.big_const*)

There is a small performance penalty in doing this of around 10%.

Bootloader and boot options

You can boot into special modes by holding down the usr button and briefly pressing reset. The LED flashes in sequence: red, green, blue, white. The boot mode is determined by the color showing at the time when you release the usr button.

1. red: Normal
2. green: safe boot (don't execute boot.py or main.py)
3. blue: factory reset. Re-initialises the filesystem on /flash wiping any user files. Does not affect the SD card.
4. white: bootloader mode for firmware update. The red LED then flashes once a second indicating bootloader mode.

You can also put the board in booloader mode by executing pyb.bootloader().

Once in booloader mode upload the firmware as usual:

tools/pydfu.py -u `path_to_firmware`

Code emitters

Native, Viper and inline Arm Thumb assembler features are supported.

SD Card

Unlike the Pyboard 1.x this is not mounted by default. To auto-mount it, include the following in boot.py:

import sys, os, pyb

if pyb.SDCard().present():
    os.mount(pyb.SDCard(), '/sd')
    sys.path[1:1] = ['/sd', '/sd/lib']