djsundog/circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/main' into pool-fix-circuitpython

Browse Source
This commit is contained in:
Jeff Epler 2021-08-27 09:26:29 -05:00
commit 955c0276c2
5637 changed files with 471358 additions and 410508 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
.gitattributes vendored
View File

@ -1,3 +1,7 @@
# SPDX-FileCopyrightText: 2014 MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)
#
# SPDX-License-Identifier: MIT
# Per default everything gets normalized and gets LF line endings on checkout.
* text eol=lf
@ -12,6 +16,10 @@
*.jpg binary
*.dxf binary
*.mpy binary
*.deb binary
*.zip binary
*.pdf binary
*.wav binary
# These should also not be modified by git.
tests/basics/string_cr_conversion.py -text

1
.github/FUNDING.yml vendored
View File

@ -1 +0,0 @@
github: micropython

63
.github/ISSUE_TEMPLATE/bug_report.yml vendored Normal file
View File

@ -0,0 +1,63 @@
name: 🐞 Bug Report
description: Create a bug report to help us improve
labels:
- bug
body:
- type: markdown
attributes:
value: >-
Thanks! for testing out CircuitPython. Now that you have encountered a
bug... you can file a report for it.
- type: textarea
id: firmware
attributes:
label: CircuitPython version
description: >-
Include the version of CircuitPython you're running. You can see it in
the `boot_out.txt` file, as well as in the `REPL`.
placeholder: Adafruit CircuitPython 6.2.0 on 2021-03-01; Raspberry Pi Pico with rp2040
render: python
validations:
required: true
- type: textarea
id: code
attributes:
label: Code/REPL
description: This is automatically rendered as Python, so no need for backticks.
placeholder: |
import busio, bitbangio
i2c = bitbangio.I2C(board.GP1, board.GP0)
render: python
validations:
required: true
- type: textarea
id: behavior
attributes:
label: Behavior
description: What happens when you run the code above? Include error messages (if any).
placeholder: |
```python
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TimeoutError: Clock stretch too long
```
On-board led pulses red.
validations:
required: true
- type: textarea
id: description
attributes:
label: Description
description: Optionally, describe the bug in more detail.
placeholder: |
- Error while using i2c...
- Only happens when...
- might be related to #4291...
- type: textarea
id: more-info
attributes:
label: Additional information
description: >-
Optionally, add any other information like hardware connection, scope
output etc. If you have already done some debugging, mention it here.
placeholder: Removing [this](url) line resolves the issue.

7
.github/ISSUE_TEMPLATE/config.yml vendored Normal file
View File

@ -0,0 +1,7 @@
contact_links:
- name: 🔗 Adafruit Forum
url: https://forums.adafruit.com/
about: Official Adafruit technical support forum. Good for getting help on getting a project working.
- name: 🔗 Adafruit Discord
url: https://adafru.it/discord
about: Unofficial chat with many helpful folks and normally prompt replies.

11
.github/ISSUE_TEMPLATE/feature_request.md vendored Normal file
View File

@ -0,0 +1,11 @@
---
name: 🚀 Feature Request
about: Suggest an idea for this project
title: ''
labels: 'enhancement'
assignees: ''
---
<!-- We keep adding new features and enhancements to CircuitPython 🚀
and would love ❤ to see what new challenge you have got for us... 🙂 -->

612
.github/workflows/build.yml vendored Normal file
View File

@ -0,0 +1,612 @@
# SPDX-FileCopyrightText: 2014 MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)
#
# SPDX-License-Identifier: MIT
name: Build CI
on:
push:
pull_request:
release:
types: [published]
check_suite:
types: [rerequested]
jobs:
test:
runs-on: ubuntu-20.04
steps:
- name: Dump GitHub context
env:
GITHUB_CONTEXT: ${{ toJson(github) }}
run: echo "$GITHUB_CONTEXT"
- uses: actions/checkout@v2.2.0
with:
submodules: true
fetch-depth: 0
- run: git fetch --recurse-submodules=no https://github.com/adafruit/circuitpython refs/tags/*:refs/tags/*
- name: CircuitPython version
run: |
git describe --dirty --tags
echo >>$GITHUB_ENV CP_VERSION=$(git describe --dirty --tags)
- name: Set up Python 3.8
uses: actions/setup-python@v1
with:
python-version: 3.8
- name: Install deps
run: |
sudo apt-get update
sudo apt-get install -y eatmydata
sudo eatmydata apt-get install -y gettext librsvg2-bin mingw-w64 latexmk texlive-fonts-recommended texlive-latex-recommended texlive-latex-extra gcc-aarch64-linux-gnu
pip install -r requirements-dev.txt
- name: Versions
run: |
gcc --version
python3 --version
- name: New boards check
run: python3 -u ci_new_boards_check.py
working-directory: tools
- name: Duplicate USB VID/PID Check
run: python3 -u -m tools.ci_check_duplicate_usb_vid_pid
- name: Build and Validate Stubs
run: make check-stubs -j2
- uses: actions/upload-artifact@v2
with:
name: stubs
path: circuitpython-stubs/dist/*
- name: Install pypi dependencies
run: |
python -m pip install --upgrade pip
pip install setuptools wheel twine
- name: Test Documentation Build (HTML)
run: sphinx-build -E -W -b html -D version=${{ env.CP_VERSION }} -D release=${{ env.CP_VERSION }} . _build/html
- uses: actions/upload-artifact@v2
with:
name: docs
path: _build/html
- name: Test Documentation Build (LaTeX/PDF)
run: |
make latexpdf
- uses: actions/upload-artifact@v2
with:
name: docs
path: _build/latex
- name: Build mpy-cross
run: make -C mpy-cross -j2
- name: Build unix port
run: |
make -C ports/unix VARIANT=coverage -j2
- name: Test all
run: MICROPY_CPYTHON3=python3.8 MICROPY_MICROPYTHON=../ports/unix/micropython-coverage ./run-tests.py -j1
working-directory: tests
- name: Print failure info
run: MICROPY_CPYTHON3=python3.8 MICROPY_MICROPYTHON=../ports/unix/micropython-coverage ./run-tests.py -j1 --print-failures
if: failure()
working-directory: tests
- name: Native Tests
run: MICROPY_CPYTHON3=python3.8 MICROPY_MICROPYTHON=../ports/unix/micropython-coverage ./run-tests.py -j1 --emit native
working-directory: tests
- name: mpy Tests
run: MICROPY_CPYTHON3=python3.8 MICROPY_MICROPYTHON=../ports/unix/micropython-coverage ./run-tests.py -j1 --mpy-cross-flags='-mcache-lookup-bc' --via-mpy -d basics float micropython
working-directory: tests
- name: Native mpy Tests
run: MICROPY_CPYTHON3=python3.8 MICROPY_MICROPYTHON=../ports/unix/micropython-coverage ./run-tests.py -j1 --mpy-cross-flags='-mcache-lookup-bc' --via-mpy --emit native -d basics float micropython
working-directory: tests
- name: Build mpy-cross.static-aarch64
run: make -C mpy-cross -j2 -f Makefile.static-aarch64
- uses: actions/upload-artifact@v2
with:
name: mpy-cross.static-aarch64
path: mpy-cross/mpy-cross.static-aarch64
- name: Build mpy-cross.static-raspbian
run: make -C mpy-cross -j2 -f Makefile.static-raspbian
- uses: actions/upload-artifact@v2
with:
name: mpy-cross.static-raspbian
path: mpy-cross/mpy-cross.static-raspbian
- name: Build mpy-cross.static
run: make -C mpy-cross -j2 -f Makefile.static
- uses: actions/upload-artifact@v2
with:
name: mpy-cross.static-amd64-linux
path: mpy-cross/mpy-cross.static
- name: Build mpy-cross.static-mingw
run: make -C mpy-cross -j2 -f Makefile.static-mingw
- uses: actions/upload-artifact@v2
with:
name: mpy-cross.static-x64-windows
path: mpy-cross/mpy-cross.static.exe
- name: Upload mpy-cross builds to S3
if: (github.event_name == 'push' && github.ref == 'refs/heads/main' && github.repository_owner == 'adafruit') || (github.event_name == 'release' && (github.event.action == 'published' || github.event.action == 'rerequested'))
env:
AWS_PAGER: ''
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
run: |
[ -z "$AWS_ACCESS_KEY_ID" ] || aws s3 cp mpy-cross/mpy-cross.static-aarch64 s3://adafruit-circuit-python/bin/mpy-cross/mpy-cross.static-aarch64-${{ env.CP_VERSION }} --no-progress --region us-east-1
[ -z "$AWS_ACCESS_KEY_ID" ] || aws s3 cp mpy-cross/mpy-cross.static-raspbian s3://adafruit-circuit-python/bin/mpy-cross/mpy-cross.static-raspbian-${{ env.CP_VERSION }} --no-progress --region us-east-1
[ -z "$AWS_ACCESS_KEY_ID" ] || aws s3 cp mpy-cross/mpy-cross.static s3://adafruit-circuit-python/bin/mpy-cross/mpy-cross.static-amd64-linux-${{ env.CP_VERSION }} --no-progress --region us-east-1
[ -z "$AWS_ACCESS_KEY_ID" ] || aws s3 cp mpy-cross/mpy-cross.static.exe s3://adafruit-circuit-python/bin/mpy-cross/mpy-cross.static-x64-windows-${{ env.CP_VERSION }}.exe --no-progress --region us-east-1
zip -9r circuitpython-stubs.zip circuitpython-stubs
[ -z "$AWS_ACCESS_KEY_ID" ] || aws s3 cp circuitpython-stubs/dist/*.tar.gz s3://adafruit-circuit-python/bin/stubs/circuitpython-stubs-${{ env.CP_VERSION }}.zip --no-progress --region us-east-1
- name: Upload stubs to PyPi
if: github.event_name == 'push' && github.ref == 'refs/heads/main' && github.repository_owner == 'adafruit'
env:
TWINE_USERNAME: ${{ secrets.pypi_username }}
TWINE_PASSWORD: ${{ secrets.pypi_password }}
run: |
# setup.py sdist was run by 'make stubs'
[ -z "$TWINE_USERNAME" ] || echo "Uploading dev release to PyPi"
[ -z "$TWINE_USERNAME" ] || twine upload circuitpython-stubs/dist/*
mpy-cross-mac:
runs-on: macos-10.15
steps:
- name: Dump GitHub context
env:
GITHUB_CONTEXT: ${{ toJson(github) }}
run: echo "$GITHUB_CONTEXT"
- uses: actions/checkout@v2.2.0
with:
submodules: true
fetch-depth: 0
- run: git fetch --recurse-submodules=no https://github.com/adafruit/circuitpython refs/tags/*:refs/tags/*
- name: CircuitPython version
run: |
git describe --dirty --tags
echo >>$GITHUB_ENV CP_VERSION=$(git describe --dirty --tags)
- name: Install dependencies
run: |
brew install gettext
echo >>$GITHUB_PATH /usr/local/opt/gettext/bin
- name: Versions
run: |
gcc --version
python3 --version
msgfmt --version
- name: Build mpy-cross
run: make -C mpy-cross -j2
- uses: actions/upload-artifact@v2
with:
name: mpy-cross-macos-catalina
path: mpy-cross/mpy-cross
- name: Select SDK for M1 build
run: sudo xcode-select -switch /Applications/Xcode_12.3.app
- name: Build mpy-cross (arm64)
run: make -C mpy-cross -j2 -f Makefile.m1 V=2
- uses: actions/upload-artifact@v2
with:
name: mpy-cross-macos-bigsur-arm64
path: mpy-cross/mpy-cross-arm64
- name: Make universal binary
run: lipo -create -output mpy-cross-macos-universal mpy-cross/mpy-cross mpy-cross/mpy-cross-arm64
- uses: actions/upload-artifact@v2
with:
name: mpy-cross-macos-universal
path: mpy-cross-macos-universal
- name: Upload mpy-cross build to S3
run: |
[ -z "$AWS_ACCESS_KEY_ID" ] || aws s3 cp mpy-cross-macos-universal s3://adafruit-circuit-python/bin/mpy-cross/mpy-cross-macos-universal-${{ env.CP_VERSION }} --no-progress --region us-east-1
[ -z "$AWS_ACCESS_KEY_ID" ] || aws s3 cp mpy-cross/mpy-cross-arm64 s3://adafruit-circuit-python/bin/mpy-cross/mpy-cross-macos-bigsur-${{ env.CP_VERSION }}-arm64 --no-progress --region us-east-1
[ -z "$AWS_ACCESS_KEY_ID" ] || aws s3 cp mpy-cross/mpy-cross s3://adafruit-circuit-python/bin/mpy-cross/mpy-cross-macos-catalina-${{ env.CP_VERSION }} --no-progress --region us-east-1
env:
AWS_PAGER: ''
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
if: (github.event_name == 'push' && github.ref == 'refs/heads/main' && github.repository_owner == 'adafruit') || (github.event_name == 'release' && (github.event.action == 'published' || github.event.action == 'rerequested'))
build-arm:
runs-on: ubuntu-20.04
needs: test
strategy:
fail-fast: false
matrix:
board:
- "8086_commander"
- "ADM_B_NRF52840_1"
- "TG-Watch"
- "adafruit_feather_rp2040"
- "adafruit_itsybitsy_rp2040"
- "adafruit_led_glasses_nrf52840"
- "adafruit_macropad_rp2040"
- "adafruit_neokey_trinkey_m0"
- "adafruit_proxlight_trinkey_m0"
- "adafruit_qt2040_trinkey"
- "adafruit_qtpy_rp2040"
- "adafruit_rotary_trinkey_m0"
- "adafruit_slide_trinkey_m0"
- "aloriumtech_evo_m51"
- "aramcon2_badge"
- "aramcon_badge_2019"
- "arduino_mkr1300"
- "arduino_mkrzero"
- "arduino_nano_33_ble"
- "arduino_nano_33_iot"
- "arduino_nano_rp2040_connect"
- "arduino_zero"
- "bast_pro_mini_m0"
- "bastble"
- "bdmicro_vina_d21"
- "bdmicro_vina_d51"
- "bdmicro_vina_d51_pcb7"
- "bless_dev_board_multi_sensor"
- "blm_badge"
- "bluemicro840"
- "capablerobot_usbhub"
- "catwan_usbstick"
- "circuitbrains_basic_m0"
- "circuitbrains_deluxe_m4"
- "circuitplayground_bluefruit"
- "circuitplayground_express"
- "circuitplayground_express_crickit"
- "circuitplayground_express_displayio"
- "clue_nrf52840_express"
- "cp32-m4"
- "cp_sapling_m0"
- "cp_sapling_m0_revb"
- "cp_sapling_m0_spiflash"
- "cytron_maker_pi_rp2040"
- "datalore_ip_m4"
- "datum_distance"
- "datum_imu"
- "datum_light"
- "datum_weather"
- "dynalora_usb"
- "dynossat_edu_eps"
- "dynossat_edu_obc"
- "electronut_labs_blip"
- "electronut_labs_papyr"
- "escornabot_makech"
- "espruino_pico"
- "espruino_wifi"
- "feather_bluefruit_sense"
- "feather_m0_adalogger"
- "feather_m0_basic"
- "feather_m0_express"
- "feather_m0_express_crickit"
- "feather_m0_rfm69"
- "feather_m0_rfm9x"
- "feather_m0_supersized"
- "feather_m4_can"
- "feather_m4_express"
- "feather_m7_1011"
- "feather_mimxrt1011"
- "feather_mimxrt1062"
- "feather_nrf52840_express"
- "feather_stm32f405_express"
- "fluff_m0"
- "gemma_m0"
- "grandcentral_m4_express"
- "hallowing_m0_express"
- "hallowing_m4_express"
- "hiibot_bluefi"
- "huntercat_nfc"
- "ikigaisense_vita"
- "imxrt1010_evk"
- "imxrt1020_evk"
- "imxrt1060_evk"
- "itsybitsy_m0_express"
- "itsybitsy_m4_express"
- "itsybitsy_nrf52840_express"
- "kicksat-sprite"
- "loc_ber_m4_base_board"
- "makerdiary_m60_keyboard"
- "makerdiary_nrf52840_m2_devkit"
- "makerdiary_nrf52840_mdk"
- "makerdiary_nrf52840_mdk_usb_dongle"
- "matrixportal_m4"
- "meowbit_v121"
- "meowmeow"
- "metro_m0_express"
- "metro_m4_airlift_lite"
- "metro_m4_express"
- "metro_m7_1011"
- "metro_nrf52840_express"
- "microbit_v2"
- "mini_sam_m4"
- "monster_m4sk"
- "ndgarage_ndbit6"
- "ndgarage_ndbit6_v2"
- "neopixel_trinkey_m0"
- "nfc_copy_cat"
- "nice_nano"
- "nucleo_f746zg"
- "nucleo_f767zi"
- "nucleo_h743zi_2"
- "ohs2020_badge"
- "openbook_m4"
- "openmv_h7"
- "particle_argon"
- "particle_boron"
- "particle_xenon"
- "pca10056"
- "pca10059"
- "pca10100"
- "pewpew10"
- "pewpew_m4"
- "picoplanet"
- "pimoroni_interstate75"
- "pimoroni_keybow2040"
- "pimoroni_pga2040"
- "pimoroni_picolipo_16mb"
- "pimoroni_picolipo_4mb"
- "pimoroni_picosystem"
- "pimoroni_plasma2040"
- "pimoroni_tiny2040"
- "pitaya_go"
- "pyb_nano_v2"
- "pybadge"
- "pyboard_v11"
- "pycubed"
- "pycubed_mram"
- "pygamer"
- "pyportal"
- "pyportal_titano"
- "pyruler"
- "qtpy_m0"
- "qtpy_m0_haxpress"
- "raspberry_pi_pico"
- "raytac_mdbt50q-db-40"
- "raytac_mdbt50q-rx"
- "robohatmm1_m4"
- "sam32"
- "same54_xplained"
- "seeeduino_wio_terminal"
- "seeeduino_xiao"
- "sensebox_mcu"
- "serpente"
- "shirtty"
- "silicognition-m4-shim"
- "simmel"
- "snekboard"
- "sparkfun_lumidrive"
- "sparkfun_micromod_rp2040"
- "sparkfun_nrf52840_micromod"
- "sparkfun_nrf52840_mini"
- "sparkfun_pro_micro_rp2040"
- "sparkfun_qwiic_micro_no_flash"
- "sparkfun_qwiic_micro_with_flash"
- "sparkfun_redboard_turbo"
- "sparkfun_samd21_dev"
- "sparkfun_samd21_mini"
- "sparkfun_samd51_micromod"
- "sparkfun_samd51_thing_plus"
- "sparkfun_stm32f405_micromod"
- "sparkfun_thing_plus_rp2040"
- "spresense"
- "stackrduino_m0_pro"
- "stm32f411ce_blackpill"
- "stm32f411ce_blackpill_with_flash"
- "stm32f411ve_discovery"
- "stm32f412zg_discovery"
- "stm32f4_discovery"
- "stm32f746g_discovery"
- "stringcar_m0_express"
- "teensy40"
- "teensy41"
- "teknikio_bluebird"
- "thunderpack_v11"
- "thunderpack_v12"
- "tinkeringtech_scoutmakes_azul"
- "trellis_m4_express"
- "trinket_m0"
- "trinket_m0_haxpress"
- "uartlogger2"
- "uchip"
- "ugame10"
- "warmbit_bluepixel"
- "winterbloom_big_honking_button"
- "winterbloom_sol"
- "xinabox_cc03"
- "xinabox_cs11"
steps:
- name: Set up Python 3.8
uses: actions/setup-python@v1
with:
python-version: 3.8
- uses: actions/checkout@v2.2.0
with:
submodules: true
fetch-depth: 0
- run: git fetch --recurse-submodules=no https://github.com/adafruit/circuitpython refs/tags/*:refs/tags/*
- name: Install deps
run: |
sudo apt-get install -y gettext
pip install -r requirements-dev.txt
wget --no-verbose https://adafruit-circuit-python.s3.amazonaws.com/gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux.tar.bz2
sudo tar -C /usr --strip-components=1 -xaf gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux.tar.bz2
- name: Versions
run: |
gcc --version
arm-none-eabi-gcc --version
python3 --version
- name: mpy-cross
run: make -C mpy-cross -j2
- name: Setup build failure matcher
run: echo "::add-matcher::$GITHUB_WORKSPACE/.github/workflows/match-build-fail.json"
- name: build
run: python3 -u build_release_files.py
working-directory: tools
env:
BOARDS: ${{ matrix.board }}
- uses: actions/upload-artifact@v2
with:
name: ${{ matrix.board }}
path: bin/${{ matrix.board }}
- name: Upload to S3
run: "[ -z \"$AWS_ACCESS_KEY_ID\" ] || aws s3 cp bin/ s3://adafruit-circuit-python/bin/ --recursive --no-progress --region us-east-1"
env:
AWS_PAGER: ''
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
if: (github.event_name == 'push' && github.ref == 'refs/heads/main' && github.repository_owner == 'adafruit') || (github.event_name == 'release' && (github.event.action == 'published' || github.event.action == 'rerequested'))
build-riscv:
runs-on: ubuntu-20.04
needs: test
strategy:
fail-fast: false
matrix:
board:
- "fomu"
steps:
- name: Set up Python 3.8
uses: actions/setup-python@v1
with:
python-version: 3.8
- uses: actions/checkout@v2.2.0
with:
submodules: true
fetch-depth: 0
- run: git fetch --recurse-submodules=no https://github.com/adafruit/circuitpython refs/tags/*:refs/tags/*
- name: Install deps
run: |
sudo apt-get install -y gettext
pip install -r requirements-dev.txt
wget https://static.dev.sifive.com/dev-tools/riscv64-unknown-elf-gcc-8.3.0-2019.08.0-x86_64-linux-centos6.tar.gz
sudo tar -C /usr --strip-components=1 -xaf riscv64-unknown-elf-gcc-8.3.0-2019.08.0-x86_64-linux-centos6.tar.gz
- name: Versions
run: |
gcc --version
riscv64-unknown-elf-gcc --version
python3 --version
- name: mpy-cross
run: make -C mpy-cross -j2
- name: Setup build failure matcher
run: echo "::add-matcher::$GITHUB_WORKSPACE/.github/workflows/match-build-fail.json"
- name: build
run: python3 -u build_release_files.py
working-directory: tools
env:
BOARDS: ${{ matrix.board }}
- uses: actions/upload-artifact@v2
with:
name: ${{ matrix.board }}
path: bin/${{ matrix.board }}
- name: Upload to S3
run: "[ -z \"$AWS_ACCESS_KEY_ID\" ] || aws s3 cp bin/ s3://adafruit-circuit-python/bin/ --recursive --no-progress --region us-east-1"
env:
AWS_PAGER: ''
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
if: (github.event_name == 'push' && github.ref == 'refs/heads/main' && github.repository_owner == 'adafruit') || (github.event_name == 'release' && (github.event.action == 'published' || github.event.action == 'rerequested'))
build-xtensa:
runs-on: ubuntu-20.04
needs: test
strategy:
fail-fast: false
matrix:
board:
- "adafruit_feather_esp32s2_nopsram"
- "adafruit_feather_esp32s2_tftback_nopsram"
- "adafruit_funhouse"
- "adafruit_magtag_2.9_grayscale"
- "adafruit_metro_esp32s2"
- "ai_thinker_esp_12k_nodemcu"
- "artisense_rd00"
- "atmegazero_esp32s2"
- "crumpspace_crumps2"
- "electroniccats_bastwifi"
- "espressif_kaluga_1"
- "espressif_kaluga_1.3"
- "espressif_saola_1_wroom"
- "espressif_saola_1_wrover"
- "franzininho_wifi_wroom"
- "franzininho_wifi_wrover"
- "gravitech_cucumber_m"
- "gravitech_cucumber_ms"
- "gravitech_cucumber_r"
- "gravitech_cucumber_rs"
- "lilygo_ttgo_t8_s2_st7789"
- "microdev_micro_s2"
- "morpheans_morphesp-240"
- "muselab_nanoesp32_s2_wroom"
- "muselab_nanoesp32_s2_wrover"
- "odt_pixelwing_esp32_s2"
- "targett_module_clip_wroom"
- "targett_module_clip_wrover"
- "unexpectedmaker_feathers2"
- "unexpectedmaker_feathers2_prerelease"
- "unexpectedmaker_tinys2"
steps:
- name: Set up Python 3.8
uses: actions/setup-python@v1
with:
python-version: 3.8
- uses: actions/checkout@v2.2.0
with:
submodules: true
fetch-depth: 0
- run: git fetch --recurse-submodules=no https://github.com/adafruit/circuitpython refs/tags/*:refs/tags/*
- name: CircuitPython version
run: git describe --dirty --tags
- uses: actions/cache@v2
name: Fetch IDF tool cache
id: idf-cache
with:
path: ${{ github.workspace }}/.idf_tools
key: ${{ runner.os }}-idf-tools-${{ hashFiles('.git/modules/ports/esp32s2/esp-idf/HEAD') }}-20210716
- name: Clone IDF submodules
run: |
(cd $IDF_PATH && git submodule update --init)
env:
IDF_PATH: ${{ github.workspace }}/ports/esp32s2/esp-idf
- name: Install IDF tools
run: |
$IDF_PATH/tools/idf_tools.py --non-interactive install required
$IDF_PATH/tools/idf_tools.py --non-interactive install cmake
$IDF_PATH/tools/idf_tools.py --non-interactive install-python-env
rm -rf $IDF_TOOLS_PATH/dist
env:
IDF_PATH: ${{ github.workspace }}/ports/esp32s2/esp-idf
IDF_TOOLS_PATH: ${{ github.workspace }}/.idf_tools
- name: Install CircuitPython deps
run: |
source $IDF_PATH/export.sh
pip install -r requirements-dev.txt
sudo apt-get install -y gettext ninja-build
env:
IDF_PATH: ${{ github.workspace }}/ports/esp32s2/esp-idf
IDF_TOOLS_PATH: ${{ github.workspace }}/.idf_tools
- name: Versions
run: |
source $IDF_PATH/export.sh
gcc --version
xtensa-esp32s2-elf-gcc --version
python3 --version
ninja --version
cmake --version
shell: bash
env:
IDF_PATH: ${{ github.workspace }}/ports/esp32s2/esp-idf
IDF_TOOLS_PATH: ${{ github.workspace }}/.idf_tools
- name: mpy-cross
run: make -C mpy-cross -j2
- name: Setup build failure matcher
run: echo "::add-matcher::$GITHUB_WORKSPACE/.github/workflows/match-build-fail.json"
- name: build
run: |
source $IDF_PATH/export.sh
python3 -u build_release_files.py
working-directory: tools
shell: bash
env:
IDF_PATH: ${{ github.workspace }}/ports/esp32s2/esp-idf
IDF_TOOLS_PATH: ${{ github.workspace }}/.idf_tools
BOARDS: ${{ matrix.board }}
- uses: actions/upload-artifact@v2
with:
name: ${{ matrix.board }}
path: bin/${{ matrix.board }}
- name: Upload to S3
run: "[ -z \"$AWS_ACCESS_KEY_ID\" ] || aws s3 cp bin/ s3://adafruit-circuit-python/bin/ --recursive --no-progress --region us-east-1"
env:
AWS_PAGER: ''
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
if: (github.event_name == 'push' && github.ref == 'refs/heads/main' && github.repository_owner == 'adafruit') || (github.event_name == 'release' && (github.event.action == 'published' || github.event.action == 'rerequested'))

16
.github/workflows/code_formatting.yml vendored
View File

@ -1,16 +0,0 @@
name: Check code formatting
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v1
- name: Install packages
run: source tools/ci.sh && ci_code_formatting_setup
- name: Run code formatting
run: source tools/ci.sh && ci_code_formatting_run
- name: Check code formatting
run: git diff --exit-code

27
.github/workflows/code_size.yml vendored
View File

@ -1,27 +0,0 @@
name: Check code size
on:
push:
pull_request:
paths:
- '.github/workflows/*.yml'
- 'tools/**'
- 'py/**'
- 'extmod/**'
- 'lib/**'
- 'ports/bare-arm/**'
- 'ports/minimal/**'
jobs:
build:
runs-on: ubuntu-20.04
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 100
- name: Install packages
run: source tools/ci.sh && ci_code_size_setup
- name: Build
run: source tools/ci.sh && ci_code_size_build
- name: Compute code size difference
run: tools/metrics.py diff --error-threshold 0 ~/size0 ~/size1

14
.github/workflows/commit_formatting.yml vendored
View File

@ -1,14 +0,0 @@
name: Check commit message formatting
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
fetch-depth: '100'
- uses: actions/setup-python@v1
- name: Check commit message formatting
run: source tools/ci.sh && ci_commit_formatting_run

43
.github/workflows/create_website_pr.yml vendored Normal file
View File

@ -0,0 +1,43 @@
# SPDX-FileCopyrightText: 2014 MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)
#
# SPDX-License-Identifier: MIT
name: Update CircuitPython.org
on:
release:
types: [published]
jobs:
website:
runs-on: ubuntu-20.04
steps:
- name: Dump GitHub context
env:
GITHUB_CONTEXT: ${{ toJson(github) }}
run: echo "$GITHUB_CONTEXT"
- uses: actions/checkout@v2.2.0
with:
submodules: true
fetch-depth: 0
- name: Set up Python 3.8
uses: actions/setup-python@v1
with:
python-version: 3.8
- name: Install deps
run: |
pip install -r requirements-dev.txt
- name: Versions
run: |
gcc --version
python3 --version
- run: git fetch --recurse-submodules=no https://github.com/adafruit/circuitpython refs/tags/*:refs/tags/*
- name: CircuitPython version
run: git describe --dirty --tags
- name: Website
run: python3 build_board_info.py
working-directory: tools
env:
RELEASE_TAG: ${{ github.event.release.tag_name }}
ADABOT_GITHUB_ACCESS_TOKEN: ${{ secrets.BLINKA_GITHUB_ACCESS_TOKEN }}
if: github.event_name == 'release' && (github.event.action == 'published' || github.event.action == 'rerequested')

18
.github/workflows/docs.yml vendored
View File

@ -1,18 +0,0 @@
name: Build docs
on:
pull_request:
paths:
- docs/**
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v1
- name: Install Python packages
run: pip install Sphinx
- name: Build docs
run: make -C docs/ html

14
.github/workflows/match-build-fail.json vendored Normal file
View File

@ -0,0 +1,14 @@
{
"problemMatcher": [
{
"severity": "error",
"pattern": [
{
"regexp": "^(Build .+ and \\x1b\\[31mfailed\\x1b\\[0m)$",
"message": 1
}
],
"owner": "build-failed"
}
]
}

23
.github/workflows/ports_cc3200.yml vendored
View File

@ -1,23 +0,0 @@
name: cc3200 port
on:
push:
pull_request:
paths:
- '.github/workflows/*.yml'
- 'tools/**'
- 'py/**'
- 'extmod/**'
- 'lib/**'
- 'drivers/**'
- 'ports/cc3200/**'
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_cc3200_setup
- name: Build
run: source tools/ci.sh && ci_cc3200_build

32
.github/workflows/ports_esp32.yml vendored
View File

@ -1,32 +0,0 @@
name: esp32 port
on:
push:
pull_request:
paths:
- '.github/workflows/*.yml'
- 'tools/**'
- 'py/**'
- 'extmod/**'
- 'lib/**'
- 'drivers/**'
- 'ports/esp32/**'
jobs:
build_idf402:
runs-on: ubuntu-20.04
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_esp32_idf402_setup
- name: Build
run: source tools/ci.sh && ci_esp32_build
build_idf43:
runs-on: ubuntu-20.04
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_esp32_idf43_setup
- name: Build
run: source tools/ci.sh && ci_esp32_build

23
.github/workflows/ports_esp8266.yml vendored
View File

@ -1,23 +0,0 @@
name: esp8266 port
on:
push:
pull_request:
paths:
- '.github/workflows/*.yml'
- 'tools/**'
- 'py/**'
- 'extmod/**'
- 'lib/**'
- 'drivers/**'
- 'ports/esp8266/**'
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_esp8266_setup && ci_esp8266_path >> $GITHUB_PATH
- name: Build
run: source tools/ci.sh && ci_esp8266_build

23
.github/workflows/ports_mimxrt.yml vendored
View File

@ -1,23 +0,0 @@
name: mimxrt port
on:
push:
pull_request:
paths:
- '.github/workflows/*.yml'
- 'tools/**'
- 'py/**'
- 'extmod/**'
- 'lib/**'
- 'drivers/**'
- 'ports/mimxrt/**'
jobs:
build:
runs-on: ubuntu-20.04
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_mimxrt_setup
- name: Build
run: source tools/ci.sh && ci_mimxrt_build

23
.github/workflows/ports_nrf.yml vendored
View File

@ -1,23 +0,0 @@
name: nrf port
on:
push:
pull_request:
paths:
- '.github/workflows/*.yml'
- 'tools/**'
- 'py/**'
- 'extmod/**'
- 'lib/**'
- 'drivers/**'
- 'ports/nrf/**'
jobs:
build:
runs-on: ubuntu-20.04
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_nrf_setup
- name: Build
run: source tools/ci.sh && ci_nrf_build

23
.github/workflows/ports_powerpc.yml vendored
View File

@ -1,23 +0,0 @@
name: powerpc port
on:
push:
pull_request:
paths:
- '.github/workflows/*.yml'
- 'tools/**'
- 'py/**'
- 'extmod/**'
- 'lib/**'
- 'drivers/**'
- 'ports/powerpc/**'
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_powerpc_setup
- name: Build
run: source tools/ci.sh && ci_powerpc_build

27
.github/workflows/ports_qemu-arm.yml vendored
View File

@ -1,27 +0,0 @@
name: qemu-arm port
on:
push:
pull_request:
paths:
- '.github/workflows/*.yml'
- 'tools/**'
- 'py/**'
- 'extmod/**'
- 'lib/**'
- 'drivers/**'
- 'ports/qemu-arm/**'
- 'tests/**'
jobs:
build_and_test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_qemu_arm_setup
- name: Build and run test suite
run: source tools/ci.sh && ci_qemu_arm_build
- name: Print failures
if: failure()
run: grep --text "FAIL" ports/qemu-arm/build/console.out

23
.github/workflows/ports_rp2.yml vendored
View File

@ -1,23 +0,0 @@
name: rp2 port
on:
push:
pull_request:
paths:
- '.github/workflows/*.yml'
- 'tools/**'
- 'py/**'
- 'extmod/**'
- 'lib/**'
- 'drivers/**'
- 'ports/rp2/**'
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_rp2_setup
- name: Build
run: source tools/ci.sh && ci_rp2_build

23
.github/workflows/ports_samd.yml vendored
View File

@ -1,23 +0,0 @@
name: samd port
on:
push:
pull_request:
paths:
- '.github/workflows/*.yml'
- 'tools/**'
- 'py/**'
- 'extmod/**'
- 'lib/**'
- 'drivers/**'
- 'ports/samd/**'
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_samd_setup
- name: Build
run: source tools/ci.sh && ci_samd_build

32
.github/workflows/ports_stm32.yml vendored
View File

@ -1,32 +0,0 @@
name: stm32 port
on:
push:
pull_request:
paths:
- '.github/workflows/*.yml'
- 'tools/**'
- 'py/**'
- 'extmod/**'
- 'lib/**'
- 'drivers/**'
- 'ports/stm32/**'
jobs:
build_pyb:
runs-on: ubuntu-20.04
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_stm32_setup
- name: Build
run: source tools/ci.sh && ci_stm32_pyb_build
build_nucleo:
runs-on: ubuntu-20.04
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_stm32_setup
- name: Build
run: source tools/ci.sh && ci_stm32_nucleo_build

23
.github/workflows/ports_teensy.yml vendored
View File

@ -1,23 +0,0 @@
name: teensy port
on:
push:
pull_request:
paths:
- '.github/workflows/*.yml'
- 'tools/**'
- 'py/**'
- 'extmod/**'
- 'lib/**'
- 'drivers/**'
- 'ports/teensy/**'
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_teensy_setup
- name: Build
run: source tools/ci.sh && ci_teensy_build

216
.github/workflows/ports_unix.yml vendored
View File

@ -1,216 +0,0 @@
name: unix port
on:
push:
pull_request:
paths:
- '.github/workflows/*.yml'
- 'tools/**'
- 'py/**'
- 'extmod/**'
- 'lib/**'
- 'examples/**'
- 'ports/unix/**'
- 'tests/**'
jobs:
minimal:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Build
run: source tools/ci.sh && ci_unix_minimal_build
- name: Run main test suite
run: source tools/ci.sh && ci_unix_minimal_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
reproducible:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Build with reproducible date
run: source tools/ci.sh && ci_unix_minimal_build
env:
SOURCE_DATE_EPOCH: 1234567890
- name: Check reproducible build date
run: echo | ports/unix/micropython-minimal -i | grep 'on 2009-02-13;'
standard:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Build
run: source tools/ci.sh && ci_unix_standard_build
- name: Run main test suite
run: source tools/ci.sh && ci_unix_standard_run_tests
- name: Run performance benchmarks
run: source tools/ci.sh && ci_unix_standard_run_perfbench
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
coverage:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_unix_coverage_setup
- name: Build
run: source tools/ci.sh && ci_unix_coverage_build
- name: Run main test suite
run: source tools/ci.sh && ci_unix_coverage_run_tests
- name: Build native mpy modules
run: source tools/ci.sh && ci_native_mpy_modules_build
- name: Test importing .mpy generated by mpy_ld.py
run: source tools/ci.sh && ci_unix_coverage_run_native_mpy_tests
- name: Run lcov coverage analysis
run: |
mkdir -p coverage
lcov --rc lcov_branch_coverage=1 --directory ports/unix/build-coverage --capture --output-file coverage/lcov.info.all
lcov --remove coverage/lcov.info.all '*/lib/*' '*/ports/unix/*' '*/utils/*' --output-file coverage/lcov.info
- name: Send to coveralls
uses: coverallsapp/github-action@master
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
coverage_32bit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_unix_32bit_setup
- name: Build
run: source tools/ci.sh && ci_unix_coverage_32bit_build
- name: Run main test suite
run: source tools/ci.sh && ci_unix_coverage_32bit_run_tests
- name: Build native mpy modules
run: source tools/ci.sh && ci_native_mpy_modules_32bit_build
- name: Test importing .mpy generated by mpy_ld.py
run: source tools/ci.sh && ci_unix_coverage_32bit_run_native_mpy_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
nanbox:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_unix_32bit_setup
- name: Build
run: source tools/ci.sh && ci_unix_nanbox_build
- name: Run main test suite
run: source tools/ci.sh && ci_unix_nanbox_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
float:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Build
run: source tools/ci.sh && ci_unix_float_build
- name: Run main test suite
run: source tools/ci.sh && ci_unix_float_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
stackless_clang:
runs-on: ubuntu-20.04
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_unix_clang_setup
- name: Build
run: source tools/ci.sh && ci_unix_stackless_clang_build
- name: Run main test suite
run: source tools/ci.sh && ci_unix_stackless_clang_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
float_clang:
runs-on: ubuntu-20.04
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_unix_clang_setup
- name: Build
run: source tools/ci.sh && ci_unix_float_clang_build
- name: Run main test suite
run: source tools/ci.sh && ci_unix_float_clang_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
settrace:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Build
run: source tools/ci.sh && ci_unix_settrace_build
- name: Run main test suite
run: source tools/ci.sh && ci_unix_settrace_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
settrace_stackless:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Build
run: source tools/ci.sh && ci_unix_settrace_stackless_build
- name: Run main test suite
run: source tools/ci.sh && ci_unix_settrace_stackless_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
macos:
runs-on: macos-11.0
steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v1
- name: Build
run: source tools/ci.sh && ci_unix_macos_build
- name: Run tests
run: source tools/ci.sh && ci_unix_macos_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
qemu_mips:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_unix_qemu_mips_setup
- name: Build
run: source tools/ci.sh && ci_unix_qemu_mips_build
- name: Run main test suite
run: source tools/ci.sh && ci_unix_qemu_mips_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
qemu_arm:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_unix_qemu_arm_setup
- name: Build
run: source tools/ci.sh && ci_unix_qemu_arm_build
- name: Run main test suite
run: source tools/ci.sh && ci_unix_qemu_arm_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures

93
.github/workflows/ports_windows.yml vendored
View File

@ -14,10 +14,93 @@ on:
jobs:
build:
runs-on: ubuntu-latest
runs-on: windows-2019
defaults:
run:
# We define a custom shell script here, although `msys2.cmd` does neither exist nor is it available in the PATH yet
shell: msys2 {0}
steps:
# We want to change the configuration of the git command that actions/checkout will be using (since it is not possible to set autocrlf through the action yet, see actions/checkout#226).
- run: git config --global core.autocrlf input
shell: bash
- name: Check python coding (cmd)
run: |
python -c "import sys, locale; print(sys.getdefaultencoding(), locale.getpreferredencoding(False))"
shell: cmd
# We use a JS Action, which calls the system terminal or other custom terminals directly, if required
- uses: msys2/setup-msys2@v2
with:
update: true
install: base-devel git wget unzip gcc python-pip
# The goal of this was to test how things worked when the default file
# encoding (locale.getpreferedencoding()) was not UTF-8. However, msys2
# python does use utf-8 as the preferred file encoding, and using
# actions/setup-python python3.8 gave a broken build, so we're not really
# testing what we wanted to test.
#
# however, commandline length limits are being tested so that does some
# good.
- name: Check python coding (msys2)
run: |
locale -v
which python; python --version
python -c "import sys, locale; print(sys.getdefaultencoding(), locale.getpreferredencoding(False))"
which python3; python3 --version
python3 -c "import sys, locale; print(sys.getdefaultencoding(), locale.getpreferredencoding(False))"
- name: Install dependencies
run: |
wget --no-verbose -O gcc-arm.zip https://developer.arm.com/-/media/Files/downloads/gnu-rm/10-2020q4/gcc-arm-none-eabi-10-2020-q4-major-win32.zip
unzip -q -d /tmp gcc-arm.zip
tar -C /tmp/gcc-arm-none-* -cf - . | tar -C /usr/local -xf -
pip install wheel
# requirements_dev.txt doesn't install on windows. (with msys2 python)
# instead, pick a subset for what we want to do
pip install cascadetoml jinja2 typer intelhex
# check that installed packages work....?
which python; python --version; python -c "import cascadetoml"
which python3; python3 --version; python3 -c "import cascadetoml"
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_windows_setup
- name: Build
run: source tools/ci.sh && ci_windows_build
with:
submodules: true
fetch-depth: 0
- run: git fetch --recurse-submodules=no https://github.com/adafruit/circuitpython refs/tags/*:refs/tags/*
- name: CircuitPython version
run: |
git describe --dirty --tags
echo >>$GITHUB_ENV CP_VERSION=$(git describe --dirty --tags)
- name: build mpy-cross
run: make -j2 -C mpy-cross
- name: build rp2040
run: make -j2 -C ports/raspberrypi BOARD=adafruit_feather_rp2040 TRANSLATION=de_DE
- name: build samd21
run: make -j2 -C ports/atmel-samd BOARD=feather_m0_express TRANSLATION=zh_Latn_pinyin
- name: build samd51
run: make -j2 -C ports/atmel-samd BOARD=feather_m4_express TRANSLATION=es
- name: build nrf
run: make -j2 -C ports/nrf BOARD=feather_nrf52840_express TRANSLATION=fr
- name: build stm
run: make -j2 -C ports/stm BOARD=feather_stm32f405_express TRANSLATION=pt_BR
# I gave up trying to do esp32 builds on windows when I saw
# ERROR: Platform MINGW64_NT-10.0-17763-x86_64 appears to be unsupported
# https://github.com/espressif/esp-idf/issues/7062
#
# - name: prepare esp
# run: ports/esp32s2/esp-idf/install.bat
# shell: cmd
#
# - name: build esp
# run: . ports/esp32s2/esp-idf/export.sh && make -j2 -C ports/esp32s2 BOARD=adafruit_metro_esp32s2

24
.github/workflows/ports_zephyr.yml vendored
View File

@ -1,24 +0,0 @@
name: zephyr port
on:
push:
pull_request:
paths:
- '.github/workflows/ports_zephyr.yml'
- 'tools/**'
- 'py/**'
- 'extmod/**'
- 'lib/**'
- 'ports/zephyr/**'
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install packages
run: source tools/ci.sh && ci_zephyr_setup
- name: Install Zephyr
run: source tools/ci.sh && ci_zephyr_install
- name: Build
run: source tools/ci.sh && ci_zephyr_build

30
.github/workflows/pre-commit.yml vendored Normal file
View File

@ -0,0 +1,30 @@
# SPDX-FileCopyrightText: Copyright (c) 2019 Anthony Sottile
#
# SPDX-License-Identifier: MIT
name: pre-commit
on:
pull_request:
push:
jobs:
pre-commit:
runs-on: ubuntu-20.04
steps:
- uses: actions/checkout@v1
- uses: actions/setup-python@v1
- name: Install deps
run: |
sudo apt-add-repository -y -u ppa:pybricks/ppa
sudo apt-get install -y black gettext uncrustify
pip3 install -r requirements-dev.txt
- name: Populate selected submodules
run: git submodule update --init extmod/ulab
- name: Set PY
run: echo >>$GITHUB_ENV PY="$(python -c 'import hashlib, sys;print(hashlib.sha256(sys.version.encode()+sys.executable.encode()).hexdigest())')"
- uses: actions/cache@v2
with:
path: ~/.cache/pre-commit
key: pre-commit|${{ env.PY }}|${{ hashFiles('.pre-commit-config.yaml') }}
- uses: pre-commit/action@v1.1.0

50
.gitignore vendored
View File

@ -1,7 +1,12 @@
# SPDX-FileCopyrightText: 2014 MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)
#
# SPDX-License-Identifier: MIT
# Compiled Sources
###################
*.o
*.a
!atmel-samd/asf/**/*.a
*.elf
*.bin
*.map
@ -11,6 +16,9 @@
# Packages
############
dist/
*.egg-info
.eggs
# Logs and Databases
######################
@ -23,6 +31,9 @@
# Build directories
######################
build/
bin/
circuitpython-stubs/
test-stubs/
build-*/
# Test failure outputs
@ -39,10 +50,43 @@ __pycache__/
GNUmakefile
user.props
# Sphinx output
###############
_build
# Generated rst files
######################
genrst/
/autoapi/
/shared-bindings/*/**/*.rst
# MacOS desktop metadata files
######################
.DS_Store
# ctags and similar
###################
TAGS
# Merge leftovers
#################
*.orig
# Emacs backup files
####################
*~
*.DS_Store
**/*.DS_Store
*.icloud
# POEdit mo files
####################
*.mo
.vscode
.idea
# Python Virtual Environments
####################
.venv
.env
# Uncrustify formatting
*.uncrustify

211
.gitmodules vendored
View File

@ -1,3 +1,7 @@
# SPDX-FileCopyrightText: 2014 MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)
#
# SPDX-License-Identifier: MIT
[submodule "lib/axtls"]
path = lib/axtls
url = https://github.com/pfalcon/axtls
@ -5,40 +9,185 @@
[submodule "lib/libffi"]
path = lib/libffi
url = https://github.com/atgreen/libffi
[submodule "lib/lwip"]
path = lib/lwip
url = https://github.com/lwip-tcpip/lwip.git
[submodule "lib/berkeley-db-1.xx"]
path = lib/berkeley-db-1.xx
url = https://github.com/pfalcon/berkeley-db-1.xx
[submodule "lib/stm32lib"]
path = lib/stm32lib
url = https://github.com/micropython/stm32lib
branch = work-F4-1.13.1+F7-1.5.0+L4-1.3.0
[submodule "lib/nrfx"]
path = lib/nrfx
url = https://github.com/NordicSemiconductor/nrfx.git
[submodule "lib/mbedtls"]
path = lib/mbedtls
url = https://github.com/ARMmbed/mbedtls.git
[submodule "lib/asf4"]
path = lib/asf4
url = https://github.com/adafruit/asf4
[submodule "lib/uzlib"]
path = lib/uzlib
url = https://github.com/pfalcon/uzlib
[submodule "tools/uf2"]
path = tools/uf2
url = https://github.com/Microsoft/uf2.git
[submodule "atmel-samd/frozen/Adafruit_CircuitPython_NeoPixel"]
path = frozen/Adafruit_CircuitPython_NeoPixel
url = https://github.com/adafruit/Adafruit_CircuitPython_NeoPixel
[submodule "frozen/Adafruit_CircuitPython_Thermistor"]
path = frozen/Adafruit_CircuitPython_Thermistor
url = https://github.com/adafruit/Adafruit_CircuitPython_Thermistor.git
[submodule "frozen/Adafruit_CircuitPython_LIS3DH"]
path = frozen/Adafruit_CircuitPython_LIS3DH
url = https://github.com/adafruit/Adafruit_CircuitPython_LIS3DH.git
[submodule "frozen/Adafruit_CircuitPython_BusDevice"]
path = frozen/Adafruit_CircuitPython_BusDevice
url = https://github.com/adafruit/Adafruit_CircuitPython_BusDevice.git
[submodule "tools/python-semver"]
path = tools/python-semver
url = https://github.com/k-bx/python-semver.git
[submodule "atmel-samd/asf4"]
path = ports/atmel-samd/asf4
url = https://github.com/adafruit/asf4.git
branch = circuitpython
[submodule "tools/usb_descriptor"]
path = tools/usb_descriptor
url = https://github.com/adafruit/usb_descriptor.git
[submodule "lib/nrfutil"]
path = lib/nrfutil
url = https://github.com/adafruit/nRF52_nrfutil
[submodule "ports/atmel-samd/freetouch"]
path = ports/atmel-samd/freetouch
url = https://github.com/adafruit/Adafruit_FreeTouch.git
[submodule "frozen/Adafruit_CircuitPython_CircuitPlayground"]
path = frozen/Adafruit_CircuitPython_CircuitPlayground
url = https://github.com/adafruit/Adafruit_CircuitPython_CircuitPlayground.git
[submodule "frozen/Adafruit_CircuitPython_HID"]
path = frozen/Adafruit_CircuitPython_HID
url = https://github.com/adafruit/Adafruit_CircuitPython_HID.git
[submodule "ports/atmel-samd/Adafruit_CircuitPython_Motor"]
path = frozen/Adafruit_CircuitPython_Motor
url = https://github.com/adafruit/Adafruit_CircuitPython_Motor.git
[submodule "ports/atmel-samd/Adafruit_CircuitPython_seesaw"]
path = frozen/Adafruit_CircuitPython_seesaw
url = https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git
[submodule "frozen/Adafruit_CircuitPython_IRRemote"]
path = frozen/Adafruit_CircuitPython_IRRemote
url = https://github.com/adafruit/Adafruit_CircuitPython_IRRemote.git
[submodule "frozen/Adafruit_CircuitPython_DotStar"]
path = frozen/Adafruit_CircuitPython_DotStar
url = https://github.com/adafruit/Adafruit_CircuitPython_DotStar.git
[submodule "ports/atmel-samd/peripherals"]
path = ports/atmel-samd/peripherals
url = https://github.com/adafruit/samd-peripherals.git
[submodule "frozen/Adafruit_CircuitPython_Crickit"]
path = frozen/Adafruit_CircuitPython_Crickit
url = https://github.com/adafruit/Adafruit_CircuitPython_Crickit
[submodule "ports/nrf/nrfx"]
path = ports/nrf/nrfx
url = https://github.com/adafruit/nrfx.git
[submodule "lib/tinyusb"]
path = lib/tinyusb
url = https://github.com/hathach/tinyusb
[submodule "lib/mynewt-nimble"]
path = lib/mynewt-nimble
url = https://github.com/apache/mynewt-nimble.git
[submodule "lib/btstack"]
path = lib/btstack
url = https://github.com/bluekitchen/btstack.git
[submodule "lib/nxp_driver"]
path = lib/nxp_driver
url = https://github.com/hathach/nxp_driver.git
[submodule "lib/libhydrogen"]
path = lib/libhydrogen
url = https://github.com/jedisct1/libhydrogen.git
[submodule "lib/pico-sdk"]
path = lib/pico-sdk
url = https://github.com/hathach/tinyusb.git
branch = master
fetchRecurseSubmodules = false
[submodule "tools/huffman"]
path = tools/huffman
url = https://github.com/tannewt/huffman.git
[submodule "tools/adabot"]
path = tools/adabot
url = https://github.com/adafruit/adabot.git
[submodule "tools/bitmap_font"]
path = tools/bitmap_font
url = https://github.com/adafruit/Adafruit_CircuitPython_BitmapFont.git
[submodule "tools/Tecate-bitmap-fonts"]
path = tools/Tecate-bitmap-fonts
url = https://github.com/Tecate/bitmap-fonts.git
[submodule "frozen/pew-pewpew-standalone-10.x"]
path = frozen/pew-pewpew-standalone-10.x
url = https://github.com/pewpew-game/pew-pewpew-standalone-10.x.git
[submodule "frozen/circuitpython-stage"]
path = frozen/circuitpython-stage
url = https://github.com/python-ugame/circuitpython-stage.git
[submodule "ports/cxd56/spresense-exported-sdk"]
path = ports/cxd56/spresense-exported-sdk
url = https://github.com/sonydevworld/spresense-exported-sdk.git
[submodule "frozen/Adafruit_CircuitPython_SD"]
path = frozen/Adafruit_CircuitPython_SD
url = https://github.com/adafruit/Adafruit_CircuitPython_SD.git
[submodule "lib/mp3"]
path = lib/mp3
url = https://github.com/adafruit/Adafruit_MP3
[submodule "ports/mimxrt10xx/sdk"]
path = ports/mimxrt10xx/sdk
url = https://github.com/adafruit/MIMXRT10xx_SDK
[submodule "frozen/Adafruit_CircuitPython_Register"]
path = frozen/Adafruit_CircuitPython_Register
url = https://github.com/adafruit/Adafruit_CircuitPython_Register.git
[submodule "extmod/ulab"]
path = extmod/ulab
url = https://github.com/adafruit/circuitpython-ulab
[submodule "frozen/Adafruit_CircuitPython_ESP32SPI"]
path = frozen/Adafruit_CircuitPython_ESP32SPI
url = https://github.com/adafruit/Adafruit_CircuitPython_ESP32SPI
[submodule "frozen/Adafruit_CircuitPython_Requests"]
path = frozen/Adafruit_CircuitPython_Requests
url = https://github.com/adafruit/Adafruit_CircuitPython_Requests
[submodule "ports/stm/st_driver"]
path = ports/stm/st_driver
url = https://github.com/hathach/st_driver.git
[submodule "lib/protomatter"]
path = lib/protomatter
url = https://github.com/adafruit/Adafruit_Protomatter
[submodule "frozen/Adafruit_CircuitPython_LSM6DS"]
path = frozen/Adafruit_CircuitPython_LSM6DS
url = https://github.com/adafruit/Adafruit_CircuitPython_LSM6DS
[submodule "frozen/Adafruit_CircuitPython_FocalTouch"]
path = frozen/Adafruit_CircuitPython_FocalTouch
url = https://github.com/adafruit/Adafruit_CircuitPython_FocalTouch
[submodule "frozen/Adafruit_CircuitPython_DS3231"]
path = frozen/Adafruit_CircuitPython_DS3231
url = https://github.com/adafruit/Adafruit_CircuitPython_DS3231
[submodule "frozen/Adafruit_CircuitPython_DRV2605"]
path = frozen/Adafruit_CircuitPython_DRV2605
url = https://github.com/adafruit/Adafruit_CircuitPython_DRV2605
[submodule "frozen/Adafruit_CircuitPython_BLE"]
path = frozen/Adafruit_CircuitPython_BLE
url = https://github.com/adafruit/Adafruit_CircuitPython_BLE
[submodule "frozen/Adafruit_CircuitPython_BLE_Apple_Notification_Center"]
path = frozen/Adafruit_CircuitPython_BLE_Apple_Notification_Center
url = https://github.com/adafruit/Adafruit_CircuitPython_BLE_Apple_Notification_Center
[submodule "frozen/Adafruit_CircuitPython_RFM9x"]
path = frozen/Adafruit_CircuitPython_RFM9x
url = https://github.com/adafruit/Adafruit_CircuitPython_RFM9x.git
[submodule "frozen/Adafruit_CircuitPython_RFM69"]
path = frozen/Adafruit_CircuitPython_RFM69
url = https://github.com/adafruit/Adafruit_CircuitPython_RFM69.git
[submodule "ports/esp32s2/esp-idf"]
path = ports/esp32s2/esp-idf
url = https://github.com/adafruit/esp-idf.git
branch = circuitpython-v4.3
[submodule "ports/esp32s2/certificates/nina-fw"]
path = ports/esp32s2/certificates/nina-fw
url = https://github.com/adafruit/nina-fw.git
[submodule "frozen/Adafruit_CircuitPython_ST7789"]
path = frozen/Adafruit_CircuitPython_ST7789
url = https://github.com/adafruit/Adafruit_CircuitPython_ST7789
[submodule "frozen/Adafruit_CircuitPython_Display_Shapes"]
path = frozen/Adafruit_CircuitPython_Display_Shapes
url = https://github.com/adafruit/Adafruit_CircuitPython_Display_Shapes
[submodule "frozen/Adafruit_CircuitPython_Display_Text"]
path = frozen/Adafruit_CircuitPython_Display_Text
url = https://github.com/adafruit/Adafruit_CircuitPython_Display_Text
[submodule "frozen/Adafruit_CircuitPython_ProgressBar"]
path = frozen/Adafruit_CircuitPython_ProgressBar
url = https://github.com/adafruit/Adafruit_CircuitPython_ProgressBar
[submodule "frozen/Adafruit_CircuitPython_LC709203F"]
path = frozen/Adafruit_CircuitPython_LC709203F
url = https://github.com/adafruit/Adafruit_CircuitPython_LC709203F
[submodule "frozen/Adafruit_CircuitPython_SimpleMath"]
path = frozen/Adafruit_CircuitPython_SimpleMath
url = https://github.com/adafruit/Adafruit_CircuitPython_SimpleMath
[submodule "ports/raspberrypi/sdk"]
path = ports/raspberrypi/sdk
url = https://github.com/raspberrypi/pico-sdk.git
[submodule "data/nvm.toml"]
path = data/nvm.toml
url = https://github.com/adafruit/nvm.toml.git
branch = main
[submodule "frozen/Adafruit_CircuitPython_MIDI"]
path = frozen/Adafruit_CircuitPython_MIDI
url = https://github.com/adafruit/Adafruit_CircuitPython_MIDI
[submodule "frozen/Adafruit_CircuitPython_SimpleIO"]
path = frozen/Adafruit_CircuitPython_SimpleIO
url = https://github.com/adafruit/adafruit_circuitpython_simpleio
[submodule "lib/quirc"]
path = lib/quirc
url = https://github.com/adafruit/quirc.git

112
.mailmap Normal file
View File

@ -0,0 +1,112 @@
# SPDX-FileCopyrightText: 2020 Diego Elio Pettenò
#
# SPDX-License-Identifier: Unlicense
Alexander Steffen <devel.20.webmeister@spamgourmet.com>
Alexander Steffen <devel.20.webmeister@spamgourmet.com> <Alexander.Steffen@infineon.com>
Alexander Steffen <devel.20.webmeister@spamgourmet.com> <webmeister@users.noreply.github.com>
Benjamin Vernoux <bvernoux@gmail.com>
Brent Rubell <robots199@me.com>
Brent Rubell <robots199@me.com> <brent@xn.home>
Brent Rubell <robots199@me.com> <brentru@users.noreply.github.com>
Carlos <carlos.santiago.diaz@gmail.com>
Chris Packham <judge.packham@gmail.com>
Chris Packham <judge.packham@gmail.com> <chris.packham@alliedtelesis.co.nz>
Damiano Mazzella <damianomazzella@gmail.com>
Damien George <damien.p.george@gmail.com>
Dan Halbert <halbert@adafruit.com>
Dan Halbert <halbert@adafruit.com> <halbert@halwitz.org>
Daniel Pollard <daniel@learnweaver.com>
Daniel Pollard <daniel@learnweaver.com> <daniel.pollard@learnweaver.com>
Daniel Tralamazza <daniel@tralamazza.com>
Daniel Tralamazza <daniel@tralamazza.com> <tralamazza@users.noreply.github.com>
David Glaude <david.glaude@gmail.com>
David Glaude <david.glaude@gmail.com> <dglaude@users.noreply.github.com>
George Waters <gwatersdev@gmail.com>
George Waters <gwatersdev@gmail.com> <george@georgeh2os.com>
Ha Thach <thach@tinyusb.org>
Henrik Sölver <henrik.solver@gmail.com>
Ilya Dmitrichenko <errordeveloper@gmail.com>
Ilya Dmitrichenko <errordeveloper@gmail.com> <ilya@xively.com>
Jason Pecor <14111408+jpecor@users.noreply.github.com>
Jeff Epler <jepler@gmail.com>
Jeff Epler <jepler@gmail.com> <jeff@adafruit.com>
Jeff Epler <jepler@gmail.com> <jepler@de11.u>
Jeff Epler <jepler@gmail.com> <jepler@unpythonic.net>
Jerry Needell <jerryneedell@gmail.com>
Joe Bakalor <jmbakalor@gmail.com>
Josh Klar <josh@klar.sh>
Josh Klar <josh@klar.sh> <j@iv597.com>
Juan Biondi <juanernestobiondi@gmail.com>
Juan Biondi <juanernestobiondi@gmail.com> <juanernestobiondi@hotmail.com>
KalbeAbbas <kalbeabbas142@gmail.com>
KalbeAbbas <kalbeabbas142@gmail.com> <kalbeabbas@142@gmail.com>
Kamil Tomaszewski <kamil.tomaszewski@sony.com>
Kamil Tomaszewski <kamil.tomaszewski@sony.com> <46525824+kamtom480@users.noreply.github.com>
Kattni <kattni@adafruit.com> <kattni@kittyfish.org>
Kattni Rembor <kattni@adafruit.com>
Kenny <WarriorOfWire@users.noreply.github.com>
Kenny <WarriorOfWire@users.noreply.github.com> <3454741+WarriorOfWire@users.noreply.github.com>
Kevin Townsend <contact@microbuilder.eu>
Kevin Townsend <contact@microbuilder.eu> <microbuilder@users.noreply.github.com>
Krzysztof Blazewicz <blazewicz.krzysztof@gmail.com>
Krzysztof Blazewicz <blazewicz.krzysztof@gmail.com> <krzysztof.blazewicz@uxeon.com>
Li Weiwei <liweiwei@yeweitech.org>
Li Weiwei <liweiwei@yeweitech.org> <liweiwei@yeweitech.com>
Limor "Ladyada" Fried <limor@ladyada.net>
Limor "Ladyada" Fried <limor@ladyada.net> <ladyada>
Lucian Copeland <hierophect@gmail.com>
Lucian Copeland <hierophect@gmail.com> <hierophect@Lucians-MacBook-Air-2.local>
Mark Olsson <post@markolsson.se>
Mark Olsson <post@markolsson.se> <mark@markolsson.se>
Matt Land <matt-land@users.noreply.github.com>
Matt Land <matt-land@users.noreply.github.com> <mland@sparefoot.com>
Matt Wozniski <godlygeek+git@gmail.com>
Matt Wozniski <godlygeek+git@gmail.com> <mwozniski@bloomberg.net>
Melissa LeBlanc-Williams <melissa@adafruit.com>
Melissa LeBlanc-Williams <melissa@adafruit.com> <melissa@melissagirl.com>
Metallicow <metaliobovinus@gmail.com>
Metallicow <metaliobovinus@gmail.com> <edg62702@yahoo.com>
Peter Hinch <peter@hinch.me.uk>
Peter Hinch <peter@hinch.me.uk> <peterhinch@users.noreply.github.com>
Radomir Dopieralski <openstack@sheep.art.pl>
Radomir Dopieralski <openstack@sheep.art.pl> <deshipu@users.noreply.github.com>
Rafa Gould <rafagoulds@gmail.com>
Rafa Gould <rafagoulds@gmail.com> <50337143+rafa-gould@users.noreply.github.com>
Ryan Shaw <ryan.shaw@wisetechglobal.com>
Ryan Shaw <ryan.shaw@wisetechglobal.com> <ryannathans@hotmail.com>
Sabas <s@electroniccats.com>
Sabas <s@electroniccats.com> <s@theinventorhouse.org>
Sabas <s@electroniccats.com> <sabasjimenez@gmail.com>
Scott Shawcroft <scott@adafruit.com>
Scott Shawcroft <scott@adafruit.com> <devnull@unpythonic.net>
Scott Shawcroft <scott@adafruit.com> <scott.shawcroft@gmail.com>
Scott Shawcroft <scott@adafruit.com> <scott@chickadee.tech>
Scott Shawcroft <scott@adafruit.com> <scott@tannewt.org>
Sebastian Plamauer <oeplse@gmail.com>
Sebastian Plamauer <oeplse@gmail.com> <oepse@gmail.com>
Senuros <Senuros@users.noreply.github.com>
Senuros <Senuros@users.noreply.github.com> <senuros@noreply.github.com>
Stewart Colborne <tscolborne@outlook.com>
Stewart Colborne <tscolborne@outlook.com> <tscolborne@hotmail.com>
TG-Techie <TGTechie01@gmail.com>
TG-Techie <TGTechie01@gmail.com> <39284876+TG-Techie@users.noreply.github.com>
Thea Flowers <me@thea.codes>
Thea Flowers <me@thea.codes> <theaflowers@google.com>
Tobias Badertscher <badi@baerospace.ch>
Tobias Badertscher <badi@baerospace.ch> <python@baerospace.ch>
danicampora <danicampora@gmail.com>
danicampora <danicampora@gmail.com> <daniel@wipy.io>
dherrada <dylan.herrada@gmail.com>
dherrada <dylan.herrada@gmail.com> <33632497+dherrada@users.noreply.github.com>
dherrada <dylan.herrada@gmail.com> <=>
glennrub <glennbakke@gmail.com>
retoc <retoc@users.noreply.github.com>
retoc <retoc@users.noreply.github.com> <Retoc@noreply.github.com>
siddacious <nospam187+github@gmail.com>
siddacious <nospam187+github@gmail.com> <bsiepert@gmail.com>
siddacious <nospam187+github@gmail.com> <bsiepert@lbl.gov>
sommersoft <sommersoft@gmail.com>
sommersoft <sommersoft@gmail.com> <sommersoft@users.noreply.github.com>
stijn <stijn@ignitron.net>
stijn <stijn@ignitron.net> <stinos@zoho.com>

26
.pre-commit-config.yaml Normal file
View File

@ -0,0 +1,26 @@
# SPDX-FileCopyrightText: 2020 Diego Elio Pettenò
#
# SPDX-License-Identifier: Unlicense
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v2.3.0
hooks:
- id: check-yaml
- id: end-of-file-fixer
exclude: '^(tests/.*\.exp|tests/cmdline/.*|tests/.*/data/.*|ports/esp32s2/esp-idf-config/.*|ports/esp32s2/boards/.*/sdkconfig)'
- id: trailing-whitespace
exclude: '^(tests/.*\.exp|tests/cmdline/.*|tests/.*/data/.*)'
- repo: local
hooks:
- id: translations
name: Translations
entry: sh -c "if ! make check-translate; then make translate; fi"
types: [c]
pass_filenames: false
language: system
- id: formatting
name: Formatting
entry: python3 tools/codeformat.py
types_or: [c, python]
language: system

21
.readthedocs.yml Normal file
View File

@ -0,0 +1,21 @@
# SPDX-FileCopyrightText: 2014 MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)
#
# SPDX-License-Identifier: MIT
# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
version: 2
submodules:
include:
- extmod/ulab
formats:
- pdf
python:
version: 3
install:
- requirements: docs/requirements.txt

20
.rosie.yml Normal file
View File

@ -0,0 +1,20 @@
# SPDX-FileCopyrightText: 2014 MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)
#
# SPDX-License-Identifier: MIT
# This configuration file tells Rosie where to find prebuilt .bin files (Travis
# builds them) and where to find the tests.
binaries:
prebuilt_s3:
bucket: adafruit-circuit-python
file_pattern: bin/{board}/adafruit-circuitpython-{board}-*-{short_sha}.{extension}
rosie_upload:
file_pattern: adafruit-circuitpython-{board}-*{short_sha}.{extension}
circuitpython_tests:
test_directories:
- tests/basics
- tests/circuitpython
test_helper:
- tests/skip_if.py

3
ACKNOWLEDGEMENTS.license Normal file
View File

@ -0,0 +1,3 @@
SPDX-FileCopyrightText: 2014 MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)
SPDX-License-Identifier: MIT

107
BUILDING.md Normal file
View File

@ -0,0 +1,107 @@
<!--
SPDX-FileCopyrightText: 2014 MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)
SPDX-License-Identifier: MIT
-->
# Building CircuitPython
Welcome to CircuitPython!
This document is a quick-start guide only.
Detailed guides on how to build CircuitPython can be found in the Adafruit Learn system at
https://learn.adafruit.com/building-circuitpython/
## Setup
Please ensure you setup your build environment appropriately, as per the guide. You will need:
* Linux: https://learn.adafruit.com/building-circuitpython/linux
* MacOS: https://learn.adafruit.com/building-circuitpython/macos
* Windows Subsystem for Linux (WSL): https://learn.adafruit.com/building-circuitpython/windows-subsystem-for-linux
### Submodules
This project has a bunch of git submodules. You will need to update them regularly.
git submodule sync
git submodule update --init
### mpy-cross
As part of the build process, mpy-cross is needed to compile .py files into .mpy files.
To compile (or recompile) mpy-cross:
make -C mpy-cross
# Building
There a number of ports of CircuitPython! To build for your board, change to the appropriate ports directory and build.
Examples:
cd ports/atmel-samd
make BOARD=circuitplayground_express
cd ports/nrf
make BOARD=circuitplayground_bluefruit
If you aren't sure what boards exist, have a peek in the boards subdirectory of your port.
If you have a fast computer with many cores, consider adding `-j` to your build flags, such as `-j17` on
a 6-core 12-thread machine.
# Testing
If you are working on changes to the core language, you might find it useful to run the test suite.
The test suite in the top level `tests` directory. It needs the unix port to run.
cd ports/unix
make axtls
make micropython
Then you can run the test suite:
cd ../../tests
./run-tests
A successful run will say something like
676 tests performed (19129 individual testcases)
676 tests passed
30 tests skipped: buffered_writer builtin_help builtin_range_binop class_delattr_setattr cmd_parsetree extra_coverage framebuf1 framebuf16 framebuf2 framebuf4 framebuf8 framebuf_subclass mpy_invalid namedtuple_asdict non_compliant resource_stream schedule sys_getsizeof urandom_extra ure_groups ure_span ure_sub ure_sub_unmatched vfs_basic vfs_fat_fileio1 vfs_fat_fileio2 vfs_fat_more vfs_fat_oldproto vfs_fat_ramdisk vfs_userfs
# Debugging
The easiest way to debug CircuitPython on hardware is with a JLink device, JLinkGDBServer, and an appropriate GDB.
Instructions can be found at https://learn.adafruit.com/debugging-the-samd21-with-gdb
If using JLink, you'll need both the `JLinkGDBServer` and `arm-none-eabi-gdb` running.
Example:
JLinkGDBServer -if SWD -device ATSAMD51J19
arm-none-eabi-gdb build-metro_m4_express/firmware.elf -iex "target extended-remote :2331"
If your port/build includes `arm-none-eabi-gdb-py`, consider using it instead, as it can be used for better register
debugging with https://github.com/bnahill/PyCortexMDebug
# Code Quality Checks
We apply code quality checks using pre-commit. Install pre-commit once per system with
python3 -mpip install pre-commit
Activate it once per git clone with
pre-commit --install
Pre-commit also requires some additional programs to be installed through your package manager:
* Standard Unix tools such as make, find, etc
* The gettext package, any modern version
* uncrustify version 0.71 (0.72 is also tested)
Each time you create a git commit, the pre-commit quality checks will be run. You can also run them e.g., with `pre-commit run foo.c` or `pre-commit run --all` to run on all files whether modified or not.
Some pre-commit quality checks require your active attention to resolve, others (such as the formatting checks of uncrustify) are made automatically and must simply be incorporated into your code changes by committing them.

235
CODECONVENTIONS.md
View File

@ -1,235 +0,0 @@
Git commit conventions
======================
Each commit message should start with a directory or full file path
prefix, so it was clear which part of codebase a commit affects. If
a change affects one file, it's better to use path to a file. If it
affects few files in a subdirectory, using subdirectory as a prefix
is ok. For longish paths, it's acceptable to drop intermediate
components, which still should provide good context of a change.
It's also ok to drop file extensions.
Besides prefix, first line of a commit message should describe a
change clearly and to the point, and be a grammatical sentence with
final full stop. First line should fit within 72 characters. Examples
of good first line of commit messages:
py/objstr: Add splitlines() method.
py: Rename FOO to BAR.
docs/machine: Fix typo in reset() description.
ports: Switch to use lib/foo instead of duplicated code.
After the first line add an empty line and in the following lines describe
the change in a detail, if needed, with lines fitting within 75 characters
(with an exception for long items like URLs which cannot be broken). Any
change beyond 5 lines would likely require such detailed description.
To get good practical examples of good commits and their messages, browse
the `git log` of the project.
When committing you are encouraged to sign-off your commit by adding
"Signed-off-by" lines and similar, eg using "git commit -s". If you don't
explicitly sign-off in this way then the commit message, which includes your
name and email address in the "Author" line, implies your sign-off. In either
case, of explicit or implicit sign-off, you are certifying and signing off
against the following:
* That you wrote the change yourself, or took it from a project with
a compatible license (in the latter case the commit message, and possibly
source code should provide reference where the implementation was taken
from and give credit to the original author, as required by the license).
* That you are allowed to release these changes to an open-source project
(for example, changes done during paid work for a third party may require
explicit approval from that third party).
* That you (or your employer) agree to release the changes under
MicroPython's license, which is the MIT license. Note that you retain
copyright for your changes (for smaller changes, the commit message
conveys your copyright; if you make significant changes to a particular
source module, you're welcome to add your name to the file header).
* Your contribution including commit message will be publicly and
indefinitely available for anyone to access, including redistribution
under the terms of the project's license.
* Your signature for all of the above, which is the "Signed-off-by" line
or the "Author" line in the commit message, includes your full real name and
a valid and active email address by which you can be contacted in the
foreseeable future.
Code auto-formatting
====================
Both C and Python code are auto-formatted using the `tools/codeformat.py`
script. This uses [uncrustify](https://github.com/uncrustify/uncrustify) to
format C code and [black](https://github.com/psf/black) to format Python code.
After making changes, and before committing, run this tool to reformat your
changes to the correct style. Without arguments this tool will reformat all
source code (and may take some time to run). Otherwise pass as arguments to
the tool the files that changed and it will only reformat those.
Python code conventions
=======================
Python code follows [PEP 8](https://legacy.python.org/dev/peps/pep-0008/) and
is auto-formatted using [black](https://github.com/psf/black) with a line-length
of 99 characters.
Naming conventions:
- Module names are short and all lowercase; eg pyb, stm.
- Class names are CamelCase, with abbreviations all uppercase; eg I2C, not
I2c.
- Function and method names are all lowercase with words separated by
a single underscore as necessary to improve readability; eg mem_read.
- Constants are all uppercase with words separated by a single underscore;
eg GPIO_IDR.
C code conventions
==================
C code is auto-formatted using [uncrustify](https://github.com/uncrustify/uncrustify)
and the corresponding configuration file `tools/uncrustify.cfg`, with a few
minor fix-ups applied by `tools/codeformat.py`. When writing new C code please
adhere to the existing style and use `tools/codeformat.py` to check any changes.
The main conventions, and things not enforceable via the auto-formatter, are
described below.
White space:
- Expand tabs to 4 spaces.
- Don't leave trailing whitespace at the end of a line.
- For control blocks (if, for, while), put 1 space between the
keyword and the opening parenthesis.
- Put 1 space after a comma, and 1 space around operators.
Braces:
- Use braces for all blocks, even no-line and single-line pieces of
code.
- Put opening braces on the end of the line it belongs to, not on
a new line.
- For else-statements, put the else on the same line as the previous
closing brace.
Header files:
- Header files should be protected from multiple inclusion with #if
directives. See an existing header for naming convention.
Names:
- Use underscore_case, not camelCase for all names.
- Use CAPS_WITH_UNDERSCORE for enums and macros.
- When defining a type use underscore_case and put '_t' after it.
Integer types: MicroPython runs on 16, 32, and 64 bit machines, so it's
important to use the correctly-sized (and signed) integer types. The
general guidelines are:
- For most cases use mp_int_t for signed and mp_uint_t for unsigned
integer values. These are guaranteed to be machine-word sized and
therefore big enough to hold the value from a MicroPython small-int
object.
- Use size_t for things that count bytes / sizes of objects.
- You can use int/uint, but remember that they may be 16-bits wide.
- If in doubt, use mp_int_t/mp_uint_t.
Comments:
- Be concise and only write comments for things that are not obvious.
- Use `// ` prefix, NOT `/* ... */`. No extra fluff.
Memory allocation:
- Use m_new, m_renew, m_del (and friends) to allocate and free heap memory.
These macros are defined in py/misc.h.
Examples
--------
Braces, spaces, names and comments:
#define TO_ADD (123)
// This function will always recurse indefinitely and is only used to show
// coding style
int foo_function(int x, int some_value) {
if (x < some_value) {
foo(some_value, x);
} else {
foo(x + TO_ADD, some_value - 1);
}
for (int my_counter = 0; my_counter < x; ++my_counter) {
}
}
Type declarations:
typedef struct _my_struct_t {
int member;
void *data;
} my_struct_t;
Documentation conventions
=========================
MicroPython generally follows CPython in documentation process and
conventions. reStructuredText syntax is used for the documention.
Specific conventions/suggestions:
* Use `*` markup to refer to arguments of a function, e.g.:
```
.. method:: poll.unregister(obj)
Unregister *obj* from polling.
```
* Use following syntax for cross-references/cross-links:
```
:func:`foo` - function foo in current module
:func:`module1.foo` - function foo in module "module1"
(similarly for other referent types)
:class:`Foo` - class Foo
:meth:`Class.method1` - method1 in Class
:meth:`~Class.method1` - method1 in Class, but rendered just as "method1()",
not "Class.method1()"
:meth:`title <method1>` - reference method1, but render as "title" (use only
if really needed)
:mod:`module1` - module module1
`symbol` - generic xref syntax which can replace any of the above in case
the xref is unambiguous. If there's ambiguity, there will be a warning
during docs generation, which need to be fixed using one of the syntaxes
above
```
* Cross-referencing arbitrary locations
~~~
.. _xref_target:
Normal non-indented text.
This is :ref:`reference <xref_target>`.
(If xref target is followed by section title, can be just
:ref:`xref_target`).
~~~
* Linking to external URL:
```
`link text <http://foo.com/...>`_
```
* Referencing builtin singleton objects:
```
``None``, ``True``, ``False``
```
* Use following syntax to create common description for more than one element:
~~~
.. function:: foo(x)
bar(y)
Description common to foo() and bar().
~~~
More detailed guides and quickrefs:
* http://www.sphinx-doc.org/en/stable/rest.html
* http://www.sphinx-doc.org/en/stable/markup/inline.html
* http://docutils.sourceforge.net/docs/user/rst/quickref.html

53
CODEOFCONDUCT.md
View File

@ -1,53 +0,0 @@
MicroPython Code of Conduct
===========================
The MicroPython community is made up of members from around the globe with a
diverse set of skills, personalities, and experiences. It is through these
differences that our community experiences great successes and continued growth.
When you're working with members of the community, this Code of Conduct will
help steer your interactions and keep MicroPython a positive, successful, and
growing community.
Members of the MicroPython community are open, considerate, and respectful.
Behaviours that reinforce these values contribute to a positive environment, and
include: acknowledging time and effort, being respectful of differing viewpoints
and experiences, gracefully accepting constructive criticism, and using
welcoming and inclusive language.
Every member of our community has the right to have their identity respected.
The MicroPython community is dedicated to providing a positive experience for
everyone, regardless of age, gender identity and expression, sexual orientation,
disability, physical appearance, body size, ethnicity, nationality, race, or
religion (or lack thereof), education, or socio-economic status.
Unacceptable behaviour includes: harassment, trolling, deliberate intimidation,
violent threats or language directed against another person; insults, put downs,
or jokes that are based upon stereotypes, that are exclusionary, or that hold
others up for ridicule; unwelcome sexual attention or advances; sustained
disruption of community discussions; publishing others' private information
without explicit permission; and other conduct that is inappropriate for a
professional audience including people of many different backgrounds.
This code of conduct covers all online and offline presence related to the
MicroPython project, including GitHub and the forum. If a participant engages
in behaviour that violates this code of conduct, the MicroPython team may take
action as they deem appropriate, including warning the offender or expulsion
from the community. Community members asked to stop any inappropriate behaviour
are expected to comply immediately.
Thank you for helping make this a welcoming, friendly community for everyone.
If you believe that someone is violating the code of conduct, or have any other
concerns, please contact a member of the MicroPython team by emailing
contact@micropython.org.
License
-------
This Code of Conduct is licensed under the Creative Commons
Attribution-ShareAlike 3.0 Unported License.
Attributions
------------
Based on the Python code of conduct found at https://www.python.org/psf/conduct/

135
CODE_OF_CONDUCT.md Normal file
View File

@ -0,0 +1,135 @@
<!--
SPDX-FileCopyrightText: 2014 Coraline Ada Ehmke
SPDX-FileCopyrightText: 2019 Kattni Rembor for Adafruit Industries
SPDX-License-Identifier: CC-BY-4.0
-->
# Adafruit Community Code of Conduct
## Our Pledge
In the interest of fostering an open and welcoming environment, we as
contributors and leaders pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, gender identity and expression, level or type of
experience, education, socio-economic status, nationality, personal appearance,
race, religion, or sexual identity and orientation.
## Our Standards
We are committed to providing a friendly, safe and welcoming environment for
all.
Examples of behavior that contributes to creating a positive environment
include:
* Be kind and courteous to others
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Collaborating with other community members
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and sexual attention or advances
* The use of inappropriate images, including in a community member's avatar
* The use of inappropriate language, including in a community member's nickname
* Any spamming, flaming, baiting or other attention-stealing behavior
* Excessive or unwelcome helping; answering outside the scope of the question
asked
* Trolling, insulting/derogatory comments, and personal or political attacks
* Promoting or spreading disinformation, lies, or conspiracy theories against
a person, group, organisation, project, or community
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate
The goal of the standards and moderation guidelines outlined here is to build
and maintain a respectful community. We ask that you don’t just aim to be
"technically unimpeachable", but rather try to be your best self.
We value many things beyond technical expertise, including collaboration and
supporting others within our community. Providing a positive experience for
other community members can have a much more significant impact than simply
providing the correct answer.
## Our Responsibilities
Project leaders are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
Project leaders have the right and responsibility to remove, edit, or
reject messages, comments, commits, code, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any community member for other behaviors that they deem
inappropriate, threatening, offensive, or harmful.
## Moderation
Instances of behaviors that violate the Adafruit Community Code of Conduct
may be reported by any member of the community. Community members are
encouraged to report these situations, including situations they witness
involving other community members.
You may report in the following ways:
In any situation, you may send an email to <support@adafruit.com>.
On the Adafruit Discord, you may send an open message from any channel
to all Community Moderators by tagging @community moderators. You may
also send an open message from any channel, or a direct message to
@kattni#1507, @tannewt#4653, @danh#1614, @cater#2442,
@sommersoft#0222, @Mr. Certainly#0472 or @Andon#8175.
Email and direct message reports will be kept confidential.
In situations on Discord where the issue is particularly egregious, possibly
illegal, requires immediate action, or violates the Discord terms of service,
you should also report the message directly to Discord.
These are the steps for upholding our community’s standards of conduct.
1. Any member of the community may report any situation that violates the
Adafruit Community Code of Conduct. All reports will be reviewed and
investigated.
2. If the behavior is an egregious violation, the community member who
committed the violation may be banned immediately, without warning.
3. Otherwise, moderators will first respond to such behavior with a warning.
4. Moderators follow a soft "three strikes" policy - the community member may
be given another chance, if they are receptive to the warning and change their
behavior.
5. If the community member is unreceptive or unreasonable when warned by a
moderator, or the warning goes unheeded, they may be banned for a first or
second offense. Repeated offenses will result in the community member being
banned.
## Scope
This Code of Conduct and the enforcement policies listed above apply to all
Adafruit Community venues. This includes but is not limited to any community
spaces (both public and private), the entire Adafruit Discord server, and
Adafruit GitHub repositories. Examples of Adafruit Community spaces include
but are not limited to meet-ups, audio chats on the Adafruit Discord, or
interaction at a conference.
This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. As a community
member, you are representing our community, and are expected to behave
accordingly.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 1.4, available at
<https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>,
and the [Rust Code of Conduct](https://www.rust-lang.org/en-US/conduct.html).
For other projects adopting the Adafruit Community Code of
Conduct, please contact the maintainers of those projects for enforcement.
If you wish to use this code of conduct for your own project, consider
explicitly mentioning your moderation policy or making a copy with your
own moderation policy so as to avoid confusion.

59
CONTRIBUTING.md
View File

@ -1,8 +1,57 @@
When reporting an issue and especially submitting a pull request, please
make sure that you are acquainted with Contributor Guidelines:
<!--
SPDX-FileCopyrightText: 2014 MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)
https://github.com/micropython/micropython/wiki/ContributorGuidelines
SPDX-License-Identifier: MIT
-->
as well as the Code Conventions, which includes details of how to commit:
# Contributing
Please note that this project is released with a
[Contributor Code of Conduct](CODE_OF_CONDUCT.md).
By participating in this project you agree to abide by its terms. Participation
covers any forum used to converse about CircuitPython including unofficial and official spaces. Failure to do
so will result in corrective actions such as time out or ban from the project.
https://github.com/micropython/micropython/blob/master/CODECONVENTIONS.md
## Licensing
By contributing to this repository you are certifying that you have all necessary
permissions to license the code under an MIT License. You still retain the
copyright but are granting many permissions under the MIT License.
If you have an employment contract with your employer please make sure that they
don't automatically own your work product. Make sure to get any necessary approvals
before contributing. Another term for this contribution off-hours is moonlighting.
## Ways to contribute
As CircuitPython grows, there are more and more ways to contribute. Here are some ideas:
* Build a project with CircuitPython and share how to do it online.
* Test the latest libraries and CircuitPython versions with your projects and file issues for any bugs you find.
* Contribute Python code to CircuitPython libraries that support new devices or features of an existing device.
* Contribute C code to CircuitPython which fixes an open issue or adds a new feature.
## Getting started with C
CircuitPython developer Dan Halbert (@dhalbert) has written up build instructions using native build
tools [here](https://learn.adafruit.com/building-circuitpython).
For SAMD21 debugging workflow tips check out [this learn guide](https://learn.adafruit.com/debugging-the-samd21-with-gdb) from Scott (@tannewt).
## Developer contacts
Scott Shawcroft ([@tannewt](https://github.com/tannewt)) is the lead developer of CircuitPython
and is sponsored by [Adafruit Industries LLC](https://adafruit.com). Scott is usually available
during US West Coast working hours. Dan Halbert ([@dhalbert](https://github.com/dhalbert)) and
Kattni Rembor ([@kattni](https://github.com/kattni)) are also sponsored by [Adafruit Industries
LLC](https://adafruit.com) and are usually available during US East Coast daytime hours including
some weekends.
They are all reachable on [Discord](https://adafru.it/discord), GitHub issues and the [Adafruit
support forum](https://forums.adafruit.com/viewforum.php?f=60).
## Code guidelines
We aim to keep our code and commit style compatible with MicroPython upstream.
Please review their
[code conventions](https://github.com/micropython/micropython/blob/master/CODECONVENTIONS.md) to do so.
Familiarity with their [design philosophy](https://github.com/micropython/micropython/wiki/ContributorGuidelines)
is also useful though not always applicable to CircuitPython.
Furthermore, CircuitPython has a
[design guide](https://circuitpython.readthedocs.io/en/latest/docs/design_guide.html)
that covers a variety of different topics. Please read it as well.

26
LICENSES/BSD-3-Clause.txt Normal file
View File

@ -0,0 +1,26 @@
Copyright (c) <year> <owner>. All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its contributors
may be used to endorse or promote products derived from this software without
specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

324
LICENSES/CC-BY-4.0.txt Normal file
View File

@ -0,0 +1,324 @@
Creative Commons Attribution 4.0 International Creative Commons Corporation
("Creative Commons") is not a law firm and does not provide legal services
or legal advice. Distribution of Creative Commons public licenses does not
create a lawyer-client or other relationship. Creative Commons makes its licenses
and related information available on an "as-is" basis. Creative Commons gives
no warranties regarding its licenses, any material licensed under their terms
and conditions, or any related information. Creative Commons disclaims all
liability for damages resulting from their use to the fullest extent possible.
Using Creative Commons Public Licenses
Creative Commons public licenses provide a standard set of terms and conditions
that creators and other rights holders may use to share original works of
authorship and other material subject to copyright and certain other rights
specified in the public license below. The following considerations are for
informational purposes only, are not exhaustive, and do not form part of our
licenses.
Considerations for licensors: Our public licenses are intended for use by
those authorized to give the public permission to use material in ways otherwise
restricted by copyright and certain other rights. Our licenses are irrevocable.
Licensors should read and understand the terms and conditions of the license
they choose before applying it. Licensors should also secure all rights necessary
before applying our licenses so that the public can reuse the material as
expected. Licensors should clearly mark any material not subject to the license.
This includes other CC-licensed material, or material used under an exception
or limitation to copyright. More considerations for licensors : wiki.creativecommons.org/Considerations_for_licensors
Considerations for the public: By using one of our public licenses, a licensor
grants the public permission to use the licensed material under specified
terms and conditions. If the licensor's permission is not necessary for any
reason–for example, because of any applicable exception or limitation to copyright–then
that use is not regulated by the license. Our licenses grant only permissions
under copyright and certain other rights that a licensor has authority to
grant. Use of the licensed material may still be restricted for other reasons,
including because others have copyright or other rights in the material. A
licensor may make special requests, such as asking that all changes be marked
or described. Although not required by our licenses, you are encouraged to
respect those requests where reasonable. More considerations for the public
: wiki.creativecommons.org/Considerations_for_licensees Creative Commons Attribution
4.0 International Public License
By exercising the Licensed Rights (defined below), You accept and agree to
be bound by the terms and conditions of this Creative Commons Attribution
4.0 International Public License ("Public License"). To the extent this Public
License may be interpreted as a contract, You are granted the Licensed Rights
in consideration of Your acceptance of these terms and conditions, and the
Licensor grants You such rights in consideration of benefits the Licensor
receives from making the Licensed Material available under these terms and
conditions.
Section 1 – Definitions.
a. Adapted Material means material subject to Copyright and Similar Rights
that is derived from or based upon the Licensed Material and in which the
Licensed Material is translated, altered, arranged, transformed, or otherwise
modified in a manner requiring permission under the Copyright and Similar
Rights held by the Licensor. For purposes of this Public License, where the
Licensed Material is a musical work, performance, or sound recording, Adapted
Material is always produced where the Licensed Material is synched in timed
relation with a moving image.
b. Adapter's License means the license You apply to Your Copyright and Similar
Rights in Your contributions to Adapted Material in accordance with the terms
and conditions of this Public License.
c. Copyright and Similar Rights means copyright and/or similar rights closely
related to copyright including, without limitation, performance, broadcast,
sound recording, and Sui Generis Database Rights, without regard to how the
rights are labeled or categorized. For purposes of this Public License, the
rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights.
d. Effective Technological Measures means those measures that, in the absence
of proper authority, may not be circumvented under laws fulfilling obligations
under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996,
and/or similar international agreements.
e. Exceptions and Limitations means fair use, fair dealing, and/or any other
exception or limitation to Copyright and Similar Rights that applies to Your
use of the Licensed Material.
f. Licensed Material means the artistic or literary work, database, or other
material to which the Licensor applied this Public License.
g. Licensed Rights means the rights granted to You subject to the terms and
conditions of this Public License, which are limited to all Copyright and
Similar Rights that apply to Your use of the Licensed Material and that the
Licensor has authority to license.
h. Licensor means the individual(s) or entity(ies) granting rights under this
Public License.
i. Share means to provide material to the public by any means or process that
requires permission under the Licensed Rights, such as reproduction, public
display, public performance, distribution, dissemination, communication, or
importation, and to make material available to the public including in ways
that members of the public may access the material from a place and at a time
individually chosen by them.
j. Sui Generis Database Rights means rights other than copyright resulting
from Directive 96/9/EC of the European Parliament and of the Council of 11
March 1996 on the legal protection of databases, as amended and/or succeeded,
as well as other essentially equivalent rights anywhere in the world.
k. You means the individual or entity exercising the Licensed Rights under
this Public License. Your has a corresponding meaning.
Section 2 – Scope.
a. License grant.
1. Subject to the terms and conditions of this Public License, the Licensor
hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive,
irrevocable license to exercise the Licensed Rights in the Licensed Material
to:
A. reproduce and Share the Licensed Material, in whole or in part; and
B. produce, reproduce, and Share Adapted Material.
2. Exceptions and Limitations. For the avoidance of doubt, where Exceptions
and Limitations apply to Your use, this Public License does not apply, and
You do not need to comply with its terms and conditions.
3. Term. The term of this Public License is specified in Section 6(a).
4. Media and formats; technical modifications allowed. The Licensor authorizes
You to exercise the Licensed Rights in all media and formats whether now known
or hereafter created, and to make technical modifications necessary to do
so. The Licensor waives and/or agrees not to assert any right or authority
to forbid You from making technical modifications necessary to exercise the
Licensed Rights, including technical modifications necessary to circumvent
Effective Technological Measures. For purposes of this Public License, simply
making modifications authorized by this Section 2(a)(4) never produces Adapted
Material.
5. Downstream recipients.
A. Offer from the Licensor – Licensed Material. Every recipient of the Licensed
Material automatically receives an offer from the Licensor to exercise the
Licensed Rights under the terms and conditions of this Public License.
B. No downstream restrictions. You may not offer or impose any additional
or different terms or conditions on, or apply any Effective Technological
Measures to, the Licensed Material if doing so restricts exercise of the Licensed
Rights by any recipient of the Licensed Material.
6. No endorsement. Nothing in this Public License constitutes or may be construed
as permission to assert or imply that You are, or that Your use of the Licensed
Material is, connected with, or sponsored, endorsed, or granted official status
by, the Licensor or others designated to receive attribution as provided in
Section 3(a)(1)(A)(i).
b. Other rights.
1. Moral rights, such as the right of integrity, are not licensed under this
Public License, nor are publicity, privacy, and/or other similar personality
rights; however, to the extent possible, the Licensor waives and/or agrees
not to assert any such rights held by the Licensor to the limited extent necessary
to allow You to exercise the Licensed Rights, but not otherwise.
2. Patent and trademark rights are not licensed under this Public License.
3. To the extent possible, the Licensor waives any right to collect royalties
from You for the exercise of the Licensed Rights, whether directly or through
a collecting society under any voluntary or waivable statutory or compulsory
licensing scheme. In all other cases the Licensor expressly reserves any right
to collect such royalties.
Section 3 – License Conditions.
Your exercise of the Licensed Rights is expressly made subject to the following
conditions.
a. Attribution.
1. If You Share the Licensed Material (including in modified form), You must:
A. retain the following if it is supplied by the Licensor with the Licensed
Material:
i. identification of the creator(s) of the Licensed Material and any others
designated to receive attribution, in any reasonable manner requested by the
Licensor (including by pseudonym if designated);
ii. a copyright notice;
iii. a notice that refers to this Public License;
iv. a notice that refers to the disclaimer of warranties;
v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable;
B. indicate if You modified the Licensed Material and retain an indication
of any previous modifications; and
C. indicate the Licensed Material is licensed under this Public License, and
include the text of, or the URI or hyperlink to, this Public License.
2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner
based on the medium, means, and context in which You Share the Licensed Material.
For example, it may be reasonable to satisfy the conditions by providing a
URI or hyperlink to a resource that includes the required information.
3. If requested by the Licensor, You must remove any of the information required
by Section 3(a)(1)(A) to the extent reasonably practicable.
4. If You Share Adapted Material You produce, the Adapter's License You apply
must not prevent recipients of the Adapted Material from complying with this
Public License.
Section 4 – Sui Generis Database Rights.
Where the Licensed Rights include Sui Generis Database Rights that apply to
Your use of the Licensed Material:
a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract,
reuse, reproduce, and Share all or a substantial portion of the contents of
the database;
b. if You include all or a substantial portion of the database contents in
a database in which You have Sui Generis Database Rights, then the database
in which You have Sui Generis Database Rights (but not its individual contents)
is Adapted Material; and
c. You must comply with the conditions in Section 3(a) if You Share all or
a substantial portion of the contents of the database.
For the avoidance of doubt, this Section 4 supplements and does not replace
Your obligations under this Public License where the Licensed Rights include
other Copyright and Similar Rights.
Section 5 – Disclaimer of Warranties and Limitation of Liability.
a. Unless otherwise separately undertaken by the Licensor, to the extent possible,
the Licensor offers the Licensed Material as-is and as-available, and makes
no representations or warranties of any kind concerning the Licensed Material,
whether express, implied, statutory, or other. This includes, without limitation,
warranties of title, merchantability, fitness for a particular purpose, non-infringement,
absence of latent or other defects, accuracy, or the presence or absence of
errors, whether or not known or discoverable. Where disclaimers of warranties
are not allowed in full or in part, this disclaimer may not apply to You.
b. To the extent possible, in no event will the Licensor be liable to You
on any legal theory (including, without limitation, negligence) or otherwise
for any direct, special, indirect, incidental, consequential, punitive, exemplary,
or other losses, costs, expenses, or damages arising out of this Public License
or use of the Licensed Material, even if the Licensor has been advised of
the possibility of such losses, costs, expenses, or damages. Where a limitation
of liability is not allowed in full or in part, this limitation may not apply
to You.
c. The disclaimer of warranties and limitation of liability provided above
shall be interpreted in a manner that, to the extent possible, most closely
approximates an absolute disclaimer and waiver of all liability.
Section 6 – Term and Termination.
a. This Public License applies for the term of the Copyright and Similar Rights
licensed here. However, if You fail to comply with this Public License, then
Your rights under this Public License terminate automatically.
b. Where Your right to use the Licensed Material has terminated under Section
6(a), it reinstates:
1. automatically as of the date the violation is cured, provided it is cured
within 30 days of Your discovery of the violation; or
2. upon express reinstatement by the Licensor.
c. For the avoidance of doubt, this Section 6(b) does not affect any right
the Licensor may have to seek remedies for Your violations of this Public
License.
d. For the avoidance of doubt, the Licensor may also offer the Licensed Material
under separate terms or conditions or stop distributing the Licensed Material
at any time; however, doing so will not terminate this Public License.
e. Sections 1, 5, 6, 7, and 8 survive termination of this Public License.
Section 7 – Other Terms and Conditions.
a. The Licensor shall not be bound by any additional or different terms or
conditions communicated by You unless expressly agreed.
b. Any arrangements, understandings, or agreements regarding the Licensed
Material not stated herein are separate from and independent of the terms
and conditions of this Public License.
Section 8 – Interpretation.
a. For the avoidance of doubt, this Public License does not, and shall not
be interpreted to, reduce, limit, restrict, or impose conditions on any use
of the Licensed Material that could lawfully be made without permission under
this Public License.
b. To the extent possible, if any provision of this Public License is deemed
unenforceable, it shall be automatically reformed to the minimum extent necessary
to make it enforceable. If the provision cannot be reformed, it shall be severed
from this Public License without affecting the enforceability of the remaining
terms and conditions.
c. No term or condition of this Public License will be waived and no failure
to comply consented to unless expressly agreed to by the Licensor.
d. Nothing in this Public License constitutes or may be interpreted as a limitation
upon, or waiver of, any privileges and immunities that apply to the Licensor
or You, including from the legal processes of any jurisdiction or authority.
Creative Commons is not a party to its public licenses. Notwithstanding, Creative
Commons may elect to apply one of its public licenses to material it publishes
and in those instances will be considered the "Licensor." The text of the
Creative Commons public licenses is dedicated to the public domain under the
CC0 Public Domain Dedication. Except for the limited purpose of indicating
that material is shared under a Creative Commons public license or as otherwise
permitted by the Creative Commons policies published at creativecommons.org/policies,
Creative Commons does not authorize the use of the trademark "Creative Commons"
or any other trademark or logo of Creative Commons without its prior written
consent including, without limitation, in connection with any unauthorized
modifications to any of its public licenses or any other arrangements, understandings,
or agreements concerning use of licensed material. For the avoidance of doubt,
this paragraph does not form part of the public licenses.
Creative Commons may be contacted at creativecommons.org.

19
LICENSES/MIT.txt Normal file
View File

@ -0,0 +1,19 @@
MIT License Copyright (c) <year> <copyright holders>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next
paragraph) shall be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

90
LICENSES/OFL-1.1.txt Normal file
View File

@ -0,0 +1,90 @@
Copyright (c) <dates>, <Copyright Holder> (<URL|email>),
with Reserved Font Name <Reserved Font Name>. This Font Software is licensed
under the SIL Open Font License, Version 1.1.
This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL
SIL OPEN FONT LICENSE
Version 1.1 - 26 February 2007
PREAMBLE
The goals of the Open Font License (OFL) are to stimulate worldwide development
of collaborative font projects, to support the font creation efforts of academic
and linguistic communities, and to provide a free and open framework in which
fonts may be shared and improved in partnership with others.
The OFL allows the licensed fonts to be used, studied, modified and redistributed
freely as long as they are not sold by themselves. The fonts, including any
derivative works, can be bundled, embedded, redistributed and/or sold with
any software provided that any reserved names are not used by derivative works.
The fonts and derivatives, however, cannot be released under any other type
of license. The requirement for fonts to remain under this license does not
apply to any document created using the fonts or their derivatives.
DEFINITIONS
"Font Software" refers to the set of files released by the Copyright Holder(s)
under this license and clearly marked as such. This may include source files,
build scripts and documentation.
"Reserved Font Name" refers to any names specified as such after the copyright
statement(s).
"Original Version" refers to the collection of Font Software components as
distributed by the Copyright Holder(s).
"Modified Version" refers to any derivative made by adding to, deleting, or
substituting — in part or in whole — any of the components of the Original
Version, by changing formats or by porting the Font Software to a new environment.
"Author" refers to any designer, engineer, programmer, technical writer or
other person who contributed to the Font Software.
PERMISSION & CONDITIONS
Permission is hereby granted, free of charge, to any person obtaining a copy
of the Font Software, to use, study, copy, merge, embed, modify, redistribute,
and sell modified and unmodified copies of the Font Software, subject to the
following conditions:
1) Neither the Font Software nor any of its individual components, in Original
or Modified Versions, may be sold by itself.
2) Original or Modified Versions of the Font Software may be bundled, redistributed
and/or sold with any software, provided that each copy contains the above
copyright notice and this license. These can be included either as stand-alone
text files, human-readable headers or in the appropriate machine-readable
metadata fields within text or binary files as long as those fields can be
easily viewed by the user.
3) No Modified Version of the Font Software may use the Reserved Font Name(s)
unless explicit written permission is granted by the corresponding Copyright
Holder. This restriction only applies to the primary font name as presented
to the users.
4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font Software
shall not be used to promote, endorse or advertise any Modified Version, except
to acknowledge the contribution(s) of the Copyright Holder(s) and the Author(s)
or with their explicit written permission.
5) The Font Software, modified or unmodified, in part or in whole, must be
distributed entirely under this license, and must not be distributed under
any other license. The requirement for fonts to remain under this license
does not apply to any document created using the Font Software.
TERMINATION
This license becomes null and void if any of the above conditions are not met.
DISCLAIMER
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL, SPECIAL,
INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR INABILITY TO USE THE FONT
SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.

20
LICENSES/Unlicense.txt Normal file
View File

@ -0,0 +1,20 @@
This is free and unencumbered software released into the public domain.
Anyone is free to copy, modify, publish, use, compile, sell, or distribute
this software, either in source code form or as a compiled binary, for any
purpose, commercial or non-commercial, and by any means.
In jurisdictions that recognize copyright laws, the author or authors of this
software dedicate any and all copyright interest in the software to the public
domain. We make this dedication for the benefit of the public at large and
to the detriment of our heirs and successors. We intend this dedication to
be an overt act of relinquishment in perpetuity of all present and future
rights to this software under copyright law.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH
THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. For more information,
please refer to <https://unlicense.org/>

1
MANIFEST.in-stubs Normal file
View File

@ -0,0 +1 @@
recursive-include . *.pyi

322
Makefile Normal file
View File

@ -0,0 +1,322 @@
# SPDX-FileCopyrightText: 2014 MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)
#
# SPDX-License-Identifier: MIT
# Top-level Makefile for documentation builds and miscellaneous tasks.
#
# You can set these variables from the command line.
PYTHON = python3
SPHINXOPTS = -W --keep-going
SPHINXBUILD = sphinx-build
PAPER =
# path to build the generated docs
BUILDDIR = _build
# path to source files to process
SOURCEDIR = .
# path to conf.py
CONFDIR = .
# Run "make FORCE= ..." to avoid rebuilding from scratch (and risk
# producing incorrect docs).
FORCE = -E
VERBOSE = -v
# path to generated type stubs
STUBDIR = circuitpython-stubs
# Run "make VALIDATE= stubs" to avoid validating generated stub files
VALIDATE = -v
# path to pypi source distributions
DISTDIR = dist
# Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the
# full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the
# executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
BASEOPTS = -c $(CONFDIR) $(PAPEROPT_$(PAPER)) $(FORCE) $(VERBOSE) $(SPHINXOPTS) $(SOURCEDIR)
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(BASEOPTS)
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(BASEOPTS)
TRANSLATE_SOURCES = extmod lib main.c ports/atmel-samd ports/cxd56 ports/esp32s2 ports/mimxrt10xx ports/nrf ports/raspberrypi ports/stm py shared-bindings shared-module supervisor
# Paths to exclude from TRANSLATE_SOURCES
# Each must be preceded by "-path"; if any wildcards, enclose in quotes.
# Separate by "-o" (Find's "or" operand)
TRANSLATE_SOURCES_EXC = -path "ports/*/build-*" \
-o -path "ports/*/build" \
-o -path ports/atmel-samd/asf4 \
-o -path ports/cxd56/spresense-exported-sdk \
-o -path ports/esp32s2/esp-idf \
-o -path ports/mimxrt10xx/sdk \
-o -path ports/raspberrypi/sdk \
-o -path ports/stm/st_driver \
-o -path lib/tinyusb \
-o -path lib/lwip \
-o -path extmod/ulab/circuitpython \
-o -path extmod/ulab/micropython \
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext stubs
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
rm -rf autoapi
rm -rf $(STUBDIR) $(DISTDIR) *.egg-info
html: stubs
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/MicroPython.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MicroPython.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/MicroPython"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/MicroPython"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
# seems to be malfunctioning
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
# seems to be malfunctioning
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
# seems to be malfunctioning
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
# seems to be malfunctioning
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
# phony target so we always run
.PHONY: all-source
all-source:
locale/circuitpython.pot: all-source
find $(TRANSLATE_SOURCES) -type d \( $(TRANSLATE_SOURCES_EXC) \) -prune -o -type f \( -iname "*.c" -o -iname "*.h" \) -print | (LC_ALL=C sort) | xgettext -f- -L C -s --add-location=file --keyword=translate --keyword=MP_ERROR_TEXT -o - | sed -e '/"POT-Creation-Date: /d' > $@
# Historically, `make translate` updated the .pot file and ran msgmerge.
# However, this was a frequent source of merge conflicts. Weblate can perform
# msgmerge, so make translate merely update the translation template file.
.PHONY: translate
translate: locale/circuitpython.pot
# Note that normally we rely on weblate to perform msgmerge. This reduces the
# chance of a merge conflict between developer changes (that only add and
# remove source strings) and weblate changes (that only add and remove
# translated strings from po files). However, in case this is legitimately
# needed we preserve a rule to do it.
.PHONY: msgmerge
msgmerge:
for po in $(shell ls locale/*.po); do msgmerge -U $$po -s --no-fuzzy-matching --add-location=file locale/circuitpython.pot; done
merge-translate:
git merge HEAD 1>&2 2> /dev/null; test $$? -eq 128
rm locale/*~ || true
git checkout --theirs -- locale/*
make translate
.PHONY: check-translate
check-translate:
find $(TRANSLATE_SOURCES) -type d \( $(TRANSLATE_SOURCES_EXC) \) -prune -o -type f \( -iname "*.c" -o -iname "*.h" \) -print | (LC_ALL=C sort) | xgettext -f- -L C -s --add-location=file --keyword=translate --keyword=MP_ERROR_TEXT -o circuitpython.pot.tmp -p locale
$(PYTHON) tools/check_translations.py locale/circuitpython.pot.tmp locale/circuitpython.pot; status=$$?; rm -f locale/circuitpython.pot.tmp; exit $$status
.PHONY: stubs
stubs:
@rm -rf circuitpython-stubs
@mkdir circuitpython-stubs
@$(PYTHON) tools/extract_pyi.py shared-bindings/ $(STUBDIR)
@$(PYTHON) tools/extract_pyi.py extmod/ulab/code/ $(STUBDIR)/ulab
@$(PYTHON) tools/extract_pyi.py ports/atmel-samd/bindings $(STUBDIR)
@$(PYTHON) tools/extract_pyi.py ports/raspberrypi/bindings $(STUBDIR)
@cp setup.py-stubs circuitpython-stubs/setup.py
@cp README.rst-stubs circuitpython-stubs/README.rst
@cp MANIFEST.in-stubs circuitpython-stubs/MANIFEST.in
@(cd circuitpython-stubs && $(PYTHON) setup.py -q sdist)
.PHONY: check-stubs
check-stubs: stubs
@(cd $(STUBDIR) && set -- */__init__.pyi && mypy --strict "$${@%/*}")
@tools/test-stubs.sh
update-frozen-libraries:
@echo "Updating all frozen libraries to latest tagged version."
cd frozen; for library in *; do cd $$library; ../../tools/git-checkout-latest-tag.sh; cd ..; done
one-of-each: samd21 litex mimxrt10xx nrf stm
samd21:
$(MAKE) -C ports/atmel-samd BOARD=trinket_m0
samd51:
$(MAKE) -C ports/atmel-samd BOARD=feather_m4_express
esp32s2:
$(MAKE) -C ports/esp32s2 BOARD=espressif_saola_1_wroom
litex:
$(MAKE) -C ports/litex BOARD=fomu
mimxrt10xx:
$(MAKE) -C ports/mimxrt10xx BOARD=feather_mimxrt1011
nrf:
$(MAKE) -C ports/nrf BOARD=feather_nrf52840_express
stm:
$(MAKE) -C ports/stm BOARD=feather_stm32f405_express
clean-one-of-each: clean-samd21 clean-samd51 clean-esp32s2 clean-litex clean-mimxrt10xx clean-nrf clean-stm
clean-samd21:
$(MAKE) -C ports/atmel-samd BOARD=trinket_m0 clean
clean-samd51:
$(MAKE) -C ports/atmel-samd BOARD=feather_m4_express clean
clean-esp32s2:
$(MAKE) -C ports/esp32s2 BOARD=espressif_saola_1_wroom clean
clean-litex:
$(MAKE) -C ports/litex BOARD=fomu clean
clean-mimxrt10xx:
$(MAKE) -C ports/mimxrt10xx BOARD=feather_mimxrt1011 clean
clean-nrf:
$(MAKE) -C ports/nrf BOARD=feather_nrf52840_express clean
clean-stm:
$(MAKE) -C ports/stm BOARD=feather_stm32f405_express clean

188
README.md
View File

@ -1,188 +0,0 @@
[![CI badge](https://github.com/micropython/micropython/workflows/unix%20port/badge.svg)](https://github.com/micropython/micropython/actions?query=branch%3Amaster+event%3Apush) [![Coverage badge](https://coveralls.io/repos/micropython/micropython/badge.png?branch=master)](https://coveralls.io/r/micropython/micropython?branch=master)
The MicroPython project
=======================
<p align="center">
<img src="https://raw.githubusercontent.com/micropython/micropython/master/logo/upython-with-micro.jpg" alt="MicroPython Logo"/>
</p>
This is the MicroPython project, which aims to put an implementation
of Python 3.x on microcontrollers and small embedded systems.
You can find the official website at [micropython.org](http://www.micropython.org).
WARNING: this project is in beta stage and is subject to changes of the
code-base, including project-wide name changes and API changes.
MicroPython implements the entire Python 3.4 syntax (including exceptions,
`with`, `yield from`, etc., and additionally `async`/`await` keywords from
Python 3.5). The following core datatypes are provided: `str` (including
basic Unicode support), `bytes`, `bytearray`, `tuple`, `list`, `dict`, `set`,
`frozenset`, `array.array`, `collections.namedtuple`, classes and instances.
Builtin modules include `sys`, `time`, and `struct`, etc. Select ports have
support for `_thread` module (multithreading). Note that only a subset of
Python 3 functionality is implemented for the data types and modules.
MicroPython can execute scripts in textual source form or from precompiled
bytecode, in both cases either from an on-device filesystem or "frozen" into
the MicroPython executable.
See the repository http://github.com/micropython/pyboard for the MicroPython
board (PyBoard), the officially supported reference electronic circuit board.
Major components in this repository:
- py/ -- the core Python implementation, including compiler, runtime, and
core library.
- mpy-cross/ -- the MicroPython cross-compiler which is used to turn scripts
into precompiled bytecode.
- ports/unix/ -- a version of MicroPython that runs on Unix.
- ports/stm32/ -- a version of MicroPython that runs on the PyBoard and similar
STM32 boards (using ST's Cube HAL drivers).
- ports/minimal/ -- a minimal MicroPython port. Start with this if you want
to port MicroPython to another microcontroller.
- tests/ -- test framework and test scripts.
- docs/ -- user documentation in Sphinx reStructuredText format. Rendered
HTML documentation is available at http://docs.micropython.org.
Additional components:
- ports/bare-arm/ -- a bare minimum version of MicroPython for ARM MCUs. Used
mostly to control code size.
- ports/teensy/ -- a version of MicroPython that runs on the Teensy 3.1
(preliminary but functional).
- ports/pic16bit/ -- a version of MicroPython for 16-bit PIC microcontrollers.
- ports/cc3200/ -- a version of MicroPython that runs on the CC3200 from TI.
- ports/esp8266/ -- a version of MicroPython that runs on Espressif's ESP8266 SoC.
- ports/esp32/ -- a version of MicroPython that runs on Espressif's ESP32 SoC.
- ports/nrf/ -- a version of MicroPython that runs on Nordic's nRF51 and nRF52 MCUs.
- extmod/ -- additional (non-core) modules implemented in C.
- tools/ -- various tools, including the pyboard.py module.
- examples/ -- a few example Python scripts.
The subdirectories above may include READMEs with additional info.
"make" is used to build the components, or "gmake" on BSD-based systems.
You will also need bash, gcc, and Python 3.3+ available as the command `python3`
(if your system only has Python 2.7 then invoke make with the additional option
`PYTHON=python2`).
The MicroPython cross-compiler, mpy-cross
-----------------------------------------
Most ports require the MicroPython cross-compiler to be built first. This
program, called mpy-cross, is used to pre-compile Python scripts to .mpy
files which can then be included (frozen) into the firmware/executable for
a port. To build mpy-cross use:
$ cd mpy-cross
$ make
The Unix version
----------------
The "unix" port requires a standard Unix environment with gcc and GNU make.
x86 and x64 architectures are supported (i.e. x86 32- and 64-bit), as well
as ARM and MIPS. Making full-featured port to another architecture requires
writing some assembly code for the exception handling and garbage collection.
Alternatively, fallback implementation based on setjmp/longjmp can be used.
To build (see section below for required dependencies):
$ cd ports/unix
$ make submodules
$ make
Then to give it a try:
$ ./micropython
>>> list(5 * x + y for x in range(10) for y in [4, 2, 1])
Use `CTRL-D` (i.e. EOF) to exit the shell.
Learn about command-line options (in particular, how to increase heap size
which may be needed for larger applications):
$ ./micropython -h
Run complete testsuite:
$ make test
Unix version comes with a builtin package manager called upip, e.g.:
$ ./micropython -m upip install micropython-pystone
$ ./micropython -m pystone
Browse available modules on
[PyPI](https://pypi.python.org/pypi?%3Aaction=search&term=micropython).
Standard library modules come from
[micropython-lib](https://github.com/micropython/micropython-lib) project.
External dependencies
---------------------
Building MicroPython ports may require some dependencies installed.
For Unix port, `libffi` library and `pkg-config` tool are required. On
Debian/Ubuntu/Mint derivative Linux distros, install `build-essential`
(includes toolchain and make), `libffi-dev`, and `pkg-config` packages.
Other dependencies can be built together with MicroPython. This may
be required to enable extra features or capabilities, and in recent
versions of MicroPython, these may be enabled by default. To build
these additional dependencies, in the port directory you're
interested in (e.g. `ports/unix/`) first execute:
$ make submodules
This will fetch all the relevant git submodules (sub repositories) that
the port needs. Use the same command to get the latest versions of
submodules as they are updated from time to time. After that execute:
$ make deplibs
This will build all available dependencies (regardless whether they
are used or not). If you intend to build MicroPython with additional
options (like cross-compiling), the same set of options should be passed
to `make deplibs`. To actually enable/disable use of dependencies, edit
`ports/unix/mpconfigport.mk` file, which has inline descriptions of the options.
For example, to build SSL module (required for `upip` tool described above,
and so enabled by default), `MICROPY_PY_USSL` should be set to 1.
For some ports, building required dependences is transparent, and happens
automatically. But they still need to be fetched with the `make submodules`
command.
The STM32 version
-----------------
The "stm32" port requires an ARM compiler, arm-none-eabi-gcc, and associated
bin-utils. For those using Arch Linux, you need arm-none-eabi-binutils,
arm-none-eabi-gcc and arm-none-eabi-newlib packages. Otherwise, try here:
https://launchpad.net/gcc-arm-embedded
To build:
$ cd ports/stm32
$ make submodules
$ make
You then need to get your board into DFU mode. On the pyboard, connect the
3V3 pin to the P1/DFU pin with a wire (on PYBv1.0 they are next to each other
on the bottom left of the board, second row from the bottom).
Then to flash the code via USB DFU to your device:
$ make deploy
This will use the included `tools/pydfu.py` script. If flashing the firmware
does not work it may be because you don't have the correct permissions, and
need to use `sudo make deploy`.
See the README.md file in the ports/stm32/ directory for further details.
Contributing
------------
MicroPython is an open-source project and welcomes contributions. To be
productive, please be sure to follow the
[Contributors' Guidelines](https://github.com/micropython/micropython/wiki/ContributorGuidelines)
and the [Code Conventions](https://github.com/micropython/micropython/blob/master/CODECONVENTIONS.md).
Note that MicroPython is licenced under the MIT license, and all contributions
should follow this license.

248
README.rst Normal file
View File

@ -0,0 +1,248 @@
CircuitPython
=============
.. image:: https://s3.amazonaws.com/adafruit-circuit-python/CircuitPython_Repo_header_logo.png
|Build Status| |Doc Status| |License| |Discord| |Weblate|
`circuitpython.org <https://circuitpython.org>`__ \| `Get CircuitPython <#get-circuitpython>`__ \|
`Documentation <#documentation>`__ \| `Contributing <#contributing>`__ \|
`Branding <#branding>`__ \| `Differences from Micropython <#differences-from-micropython>`__ \|
`Project Structure <#project-structure>`__
**CircuitPython** is a *beginner friendly*, open source version of Python for tiny, inexpensive
computers called microcontrollers. Microcontrollers are the brains of many electronics including a
wide variety of development boards used to build hobby projects and prototypes. CircuitPython in
electronics is one of the best ways to learn to code because it connects code to reality. Simply
install CircuitPython on a supported USB board usually via drag and drop and then edit a ``code.py``
file on the CIRCUITPY drive. The code will automatically reload. No software installs are needed
besides a text editor (we recommend `Mu <https://codewith.mu/>`_ for beginners.)
Starting with CircuitPython 7.0.0, some boards may only be connectable over Bluetooth Low Energy
(BLE). Those boards provide serial and file access over BLE instead of USB using open protocols.
(Some boards may use both USB and BLE.) BLE access can be done from a variety of apps including
`code.circuitpython.org <https://code.circuitpython.org>`_.
CircuitPython features unified Python core APIs and a growing list of 300+ device libraries and
drivers that work with it. These libraries also work on single board computers with regular
Python via the `Adafruit Blinka Library <https://github.com/adafruit/Adafruit_Blinka>`_.
CircuitPython is based on `MicroPython <https://micropython.org>`_. See
`below <#differences-from-micropython>`_ for differences. Most, but not all, CircuitPython
development is sponsored by `Adafruit <https://adafruit.com>`_ and is available on their educational
development boards. Please support both MicroPython and Adafruit.
Get CircuitPython
------------------
Official binaries for all supported boards are available through
`circuitpython.org/downloads <https://circuitpython.org/downloads>`_. The site includes stable, unstable and
continuous builds. Full release notes are available through
`GitHub releases <https://github.com/adafruit/circuitpython/releases>`_ as well.
Documentation
-------------
Guides and videos are available through the `Adafruit Learning
System <https://learn.adafruit.com/>`__ under the `CircuitPython
category <https://learn.adafruit.com/category/circuitpython>`__. An API
reference is also available on `Read the Docs
<http://circuitpython.readthedocs.io/en/latest/?>`__. A collection of awesome
resources can be found at `Awesome CircuitPython <https://github.com/adafruit/awesome-circuitpython>`__.
Specifically useful documentation when starting out:
- `Welcome to CircuitPython <https://learn.adafruit.com/welcome-to-circuitpython>`__
- `CircuitPython Essentials <https://learn.adafruit.com/circuitpython-essentials>`__
- `Example Code <https://github.com/adafruit/Adafruit_Learning_System_Guides/tree/master/CircuitPython_Essentials>`__
Code Search
------------
GitHub doesn't currently support code search on forks. Therefore, CircuitPython doesn't have code search through GitHub because it is a fork of MicroPython. Luckily, `SourceGraph <https://sourcegraph.com/github.com/adafruit/circuitpython>`_ has free code search for public repos like CircuitPython. So, visit `sourcegraph.com/github.com/adafruit/circuitpython <https://sourcegraph.com/github.com/adafruit/circuitpython>`_ to search the CircuitPython codebase online.
Contributing
------------
See
`CONTRIBUTING.md <https://github.com/adafruit/circuitpython/blob/main/CONTRIBUTING.md>`__
for full guidelines but please be aware that by contributing to this
project you are agreeing to the `Code of
Conduct <https://github.com/adafruit/circuitpython/blob/main/CODE_OF_CONDUCT.md>`__.
Contributors who follow the `Code of
Conduct <https://github.com/adafruit/circuitpython/blob/main/CODE_OF_CONDUCT.md>`__
are welcome to submit pull requests and they will be promptly reviewed
by project admins. Please join the
`Discord <https://adafru.it/discord>`__ too.
Branding
------------
While we are happy to see CircuitPython forked and modified, we'd appreciate it if forked releases
not use the name "CircuitPython" or the Blinka logo. "CircuitPython" means something special to
us and those who learn about it. As a result, we'd like to make sure products referring to it meet a
common set of requirements.
If you'd like to use the term "CircuitPython" and Blinka for your product here is what we ask:
* Your product is supported by the primary
`"adafruit/circuitpython" <https://github.com/adafruit/circuitpython>`_ repo. This way we can
update any custom code as we update the CircuitPython internals.
* Your product is listed on `circuitpython.org <https://circuitpython.org>`__ (source
`here <https://github.com/adafruit/circuitpython-org/>`_). This is to ensure that a user of your
product can always download the latest version of CircuitPython from the standard place.
* Your product has a user accessible USB plug which appears as a CIRCUITPY drive when plugged in
AND/OR provides file and serial access over Bluetooth Low Energy. Boards that do not support USB
should be clearly marked as BLE-only CircuitPython.
If you choose not to meet these requirements, then we ask you call your version of CircuitPython
something else (for example, SuperDuperPython) and not use the Blinka logo. You can say it is
"CircuitPython-compatible" if most CircuitPython drivers will work with it.
--------------
Differences from `MicroPython <https://github.com/micropython/micropython>`__
-----------------------------------------------------------------------------
CircuitPython:
- Supports native USB on most boards and BLE otherwise, allowing file editing without special tools.
- Floats (aka decimals) are enabled for all builds.
- Error messages are translated into 10+ languages.
- Concurrenncy within Python is not well supported. Interrupts and threading are disabled.
async/await keywords are available on some boards for cooperative multitasking. Some concurrency
is achieved with native modules for tasks that require it such as audio file playback.
Behavior
~~~~~~~~
- The order that files are run and the state that is shared between
them. CircuitPython's goal is to clarify the role of each file and
make each file independent from each other.
- ``boot.py`` (or ``settings.py``) runs only once on start up before
USB is initialized. This lays the ground work for configuring USB at
startup rather than it being fixed. Since serial is not available,
output is written to ``boot_out.txt``.
- ``code.py`` (or ``main.py``) is run after every reload until it
finishes or is interrupted. After it is done running, the vm and
hardware is reinitialized. **This means you cannot read state from**
``code.py`` **in the REPL anymore, as the REPL is a fresh vm.** CircuitPython's goal for this
change includes reducing confusion about pins and memory being used.
- After the main code is finished the REPL can be entered by pressing any key.
- Autoreload state will be maintained across reload.
- Adds a safe mode that does not run user code after a hard crash or brown out. This makes it
possible to fix code that causes nasty crashes by making it available through mass storage after
the crash. A reset (the button) is needed after it's fixed to get back into normal mode.
- RGB status LED indicating CircuitPython state.
- Re-runs ``code.py`` or other main file after file system writes over USB mass storage. (Disable with
``supervisor.disable_autoreload()``)
- Autoreload is disabled while the REPL is active.
- Main is one of these: ``code.txt``, ``code.py``, ``main.py``,
``main.txt``
- Boot is one of these: ``boot.py``, ``boot.txt``
API
~~~
- Unified hardware APIs. Documented on
`ReadTheDocs <https://circuitpython.readthedocs.io/en/latest/shared-bindings/index.html>`_.
- API docs are Python stubs within the C files in ``shared-bindings``.
- No ``machine`` API.
Modules
~~~~~~~
- No module aliasing. (``uos`` and ``utime`` are not available as
``os`` and ``time`` respectively.) Instead ``os``, ``time``, and
``random`` are CPython compatible.
- New ``storage`` module which manages file system mounts.
(Functionality from ``uos`` in MicroPython.)
- Modules with a CPython counterpart, such as ``time``, ``os`` and
``random``, are strict
`subsets <https://circuitpython.readthedocs.io/en/latest/shared-bindings/time/__init__.html>`__
of their `CPython
version <https://docs.python.org/3.4/library/time.html?highlight=time#module-time>`__.
Therefore, code from CircuitPython is runnable on CPython but not
necessarily the reverse.
- tick count is available as
`time.monotonic() <https://circuitpython.readthedocs.io/en/latest/shared-bindings/time/__init__.html#time.monotonic>`__
--------------
Project Structure
-----------------
Here is an overview of the top-level source code directories.
Core
~~~~
The core code of
`MicroPython <https://github.com/micropython/micropython>`__ is shared
amongst ports including CircuitPython:
- ``docs`` High level user documentation in Sphinx reStructuredText
format.
- ``drivers`` External device drivers written in Python.
- ``examples`` A few example Python scripts.
- ``extmod`` Shared C code used in multiple ports' modules.
- ``lib`` Shared core C code including externally developed libraries
such as FATFS.
- ``logo`` The CircuitPython logo.
- ``mpy-cross`` A cross compiler that converts Python files to byte
code prior to being run in MicroPython. Useful for reducing library
size.
- ``py`` Core Python implementation, including compiler, runtime, and
core library.
- ``shared-bindings`` Shared definition of Python modules, their docs
and backing C APIs. Ports must implement the C API to support the
corresponding module.
- ``shared-module`` Shared implementation of Python modules that may be
based on ``common-hal``.
- ``tests`` Test framework and test scripts.
- ``tools`` Various tools, including the pyboard.py module.
Ports
~~~~~
Ports include the code unique to a microcontroller line.
================ ============================================================
Supported Support status
================ ============================================================
atmel-samd ``SAMD21`` stable | ``SAMD51`` stable
cxd56 stable
esp32s2 stable
litex alpha
mimxrt10xx alpha
nrf stable
raspberrypi stable
stm ``F4`` stable | ``others`` beta
unix alpha
================ ============================================================
- ``stable`` Highly unlikely to have bugs or missing functionality.
- ``beta`` Being actively improved but may be missing functionality and have bugs.
- ``alpha`` Will have bugs and missing functionality.
Boards
~~~~~~
- Each ``port`` has a ``boards`` directory containing variations of boards
which belong to a specific microcontroller line.
- A list of native modules supported by a particular board can be found
`here <https://circuitpython.readthedocs.io/en/latest/shared-bindings/support_matrix.html>`__.
`Back to Top <#circuitpython>`__
.. |Build Status| image:: https://github.com/adafruit/circuitpython/workflows/Build%20CI/badge.svg
:target: https://github.com/adafruit/circuitpython/actions?query=branch%3Amain
.. |Doc Status| image:: https://readthedocs.org/projects/circuitpython/badge/?version=latest
:target: http://circuitpython.readthedocs.io/
.. |Discord| image:: https://img.shields.io/discord/327254708534116352.svg
:target: https://adafru.it/discord
.. |License| image:: https://img.shields.io/badge/License-MIT-brightgreen.svg
:target: https://choosealicense.com/licenses/mit/
.. |Weblate| image:: https://hosted.weblate.org/widgets/circuitpython/-/svg-badge.svg
:target: https://hosted.weblate.org/engage/circuitpython/?utm_source=widget

29
README.rst-stubs Normal file
View File

@ -0,0 +1,29 @@
CircuitPython
=============
.. image:: https://s3.amazonaws.com/adafruit-circuit-python/CircuitPython_Repo_header_logo.png
|Build Status| |Doc Status| |License| |Discord| |Weblate|
`circuitpython.org <https://circuitpython.org>`__ \| `Get CircuitPython <#get-circuitpython>`__ \|
`Documentation <#documentation>`__ \| `Contributing <#contributing>`__ \|
`Branding <#branding>`__ \| `Differences from Micropython <#differences-from-micropython>`__ \|
`Project Structure <#project-structure>`__
**CircuitPython** is a *beginner friendly*, open source version of Python for tiny, inexpensive
computers called microcontrollers.
This package contains the "stubs", or type definitions for CircuitPython. With some advanced
editors and other tools, this information can be identify TypeErrors, AttributeErrors, and other
problems before you deploy your code to a device and can even help autocomplete your code.
.. |Build Status| image:: https://github.com/adafruit/circuitpython/workflows/Build%20CI/badge.svg
:target: https://github.com/adafruit/circuitpython/actions?query=branch%3Amain
.. |Doc Status| image:: https://readthedocs.org/projects/circuitpython/badge/?version=latest
:target: http://circuitpython.readthedocs.io/
.. |Discord| image:: https://img.shields.io/discord/327254708534116352.svg
:target: https://adafru.it/discord
.. |License| image:: https://img.shields.io/badge/License-MIT-brightgreen.svg
:target: https://choosealicense.com/licenses/mit/
.. |Weblate| image:: https://hosted.weblate.org/widgets/circuitpython/-/svg-badge.svg
:target: https://hosted.weblate.org/engage/circuitpython/?utm_source=widget

65
WEBUSB_README.md Normal file
View File

@ -0,0 +1,65 @@
<!--
SPDX-FileCopyrightText: 2014 MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)
SPDX-License-Identifier: MIT
-->
# WebUSB Serial Support
To date, this has only been tested on one port (esp32s2), on one board (espressif_kaluga_1).
## What it does
If you have ever used CircuitPython on a platform with a graphical LCD display, you have probably
already seen multiple "consoles" in use (although the LCD console is "output only").
New compile-time option CIRCUITPY_USB_VENDOR enables an additional "console" that can be used in
parallel with the original (CDC) serial console.
Web pages that support the WebUSB standard can connect to the "vendor" interface and activate
this WebUSB serial console at any time.
You can type into either console, and CircuitPython output is sent to all active consoles.
One example of a web page you can use to test drive this feature can be found at:
https://adafruit.github.io/Adafruit_TinyUSB_Arduino/examples/webusb-serial/index.html
## How to enable
Update your platform's mpconfigboard.mk file to enable and disable specific types of USB interfaces.
CIRCUITPY_USB_HID = xxx
CIRCUITPY_USB_MIDI = xxx
CIRCUITPY_USB_VENDOR = xxx
On at least some of the hardware platforms, the maximum number of USB endpoints is fixed.
For example, on the ESP32S2, you must pick only one of the above 3 interfaces to be enabled.
Original espressif_kaluga_1 mpconfigboard.mk settings:
CIRCUITPY_USB_HID = 1
CIRCUITPY_USB_MIDI = 0
CIRCUITPY_USB_VENDOR = 0
Settings to enable WebUSB instead:
CIRCUITPY_USB_HID = 0
CIRCUITPY_USB_MIDI = 0
CIRCUITPY_USB_VENDOR = 1
Notice that to enable VENDOR on ESP32-S2, we had to give up HID. There may be platforms that can have both, or even all three.
## Implementation Notes
CircuitPython uses the tinyusb library.
The tinyusb library already has support for WebUSB serial.
The tinyusb examples already include a "WebUSB serial" example.
Sidenote - The use of the term "vendor" instead of "WebUSB" was done to match tinyusb.
Basically, this feature was ported into CircuitPython by pulling code snippets out of the
tinyusb example, and putting them where they best belonged in the CircuitPython codebase.
### TODO: This needs to be reworked for dynamic USB descriptors.

507
conf.py Normal file
View File

@ -0,0 +1,507 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# MicroPython documentation build configuration file, created by
# sphinx-quickstart on Sun Sep 21 11:42:03 2014.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# SPDX-FileCopyrightText: 2014 MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)
#
# SPDX-License-Identifier: MIT
import logging
import os
import re
import subprocess
import sys
import urllib.parse
import time
from collections import defaultdict
from sphinx.transforms import SphinxTransform
from docutils import nodes
from sphinx import addnodes
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('docs'))
sys.path.insert(0, os.path.abspath('.'))
import shared_bindings_matrix
master_doc = 'docs/index'
# Grab the JSON values to use while building the module support matrix
# in 'shared-bindings/index.rst'
# The stubs must be built before we calculate the shared bindings matrix
subprocess.check_output(["make", "stubs"])
#modules_support_matrix = shared_bindings_matrix.support_matrix_excluded_boards()
modules_support_matrix = shared_bindings_matrix.support_matrix_by_board()
modules_support_matrix_reverse = defaultdict(list)
for board, modules in modules_support_matrix.items():
for module in modules:
modules_support_matrix_reverse[module].append(board)
modules_support_matrix_reverse = dict((module, sorted(boards)) for module, boards in modules_support_matrix_reverse.items())
html_context = {
'support_matrix': modules_support_matrix,
'support_matrix_reverse': modules_support_matrix_reverse
}
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = '1.3'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinxcontrib.rsvgconverter',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx_search.extension',
'rstjinja',
'myst_parser',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['templates']
# The suffix of source filenames.
source_suffix = {
'.rst': 'restructuredtext',
'.md': 'markdown',
}
extensions.append('autoapi.extension')
autoapi_type = 'python'
# Uncomment this if debugging autoapi
autoapi_keep_files = True
autoapi_dirs = [os.path.join('circuitpython-stubs', x) for x in os.listdir('circuitpython-stubs') if os.path.exists(os.path.join("circuitpython-stubs", x, "__init__.pyi"))]
print("autoapi_dirs", autoapi_dirs)
autoapi_add_toctree_entry = False
autoapi_options = ['members', 'undoc-members', 'private-members', 'show-inheritance', 'special-members', 'show-module-summary']
autoapi_template_dir = 'docs/autoapi/templates'
autoapi_python_class_content = "both"
autoapi_python_use_implicit_namespaces = True
autoapi_root = "shared-bindings"
def autoapi_prepare_jinja_env(jinja_env):
jinja_env.globals['support_matrix_reverse'] = modules_support_matrix_reverse
redirects_file = 'docs/redirects.txt'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
#master_doc = 'index'
# Get current date (execution) for copyright year
current_date = time.localtime()
# General information about the project.
project = 'Adafruit CircuitPython'
copyright = f'2014-{current_date.tm_year}, MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)'
# These are overwritten on ReadTheDocs.
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# We don't follow "The short X.Y version" vs "The full version, including alpha/beta/rc tags"
# breakdown, so use the same version identifier for both to avoid confusion.
final_version = ""
git_describe = subprocess.run(
["git", "describe", "--dirty", "--tags"],
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT,
encoding="utf-8"
)
if git_describe.returncode == 0:
git_version = re.search(
r"^\d(?:\.\d){0,2}(?:\-(?:alpha|beta|rc)\.\d+){0,1}",
str(git_describe.stdout)
)
if git_version:
final_version = git_version[0]
else:
print("Failed to retrieve git version:", git_describe.stdout)
version = release = final_version
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ["**/build*",
".git",
".github",
".env",
".venv",
".direnv",
"data",
"docs/autoapi",
"docs/README.md",
"drivers",
"examples",
"extmod",
"frozen",
"lib",
"main.c",
"mpy-cross",
"ports/*/*.c",
"ports/*/*.h",
"ports/*/boards",
"ports/*/common-hal",
"ports/*/supervisor",
"ports/atmel-samd/asf4",
"ports/atmel-samd/asf4_conf",
"ports/atmel-samd/external_flash",
"ports/atmel-samd/freetouch",
"ports/atmel-samd/peripherals",
"ports/atmel-samd/QTouch",
"ports/atmel-samd/tools",
"ports/cxd56/mkspk",
"ports/cxd56/spresense-exported-sdk",
"ports/esp32s2/certificates",
"ports/esp32s2/esp-idf",
"ports/esp32s2/.idf_tools",
"ports/esp32s2/peripherals",
"ports/litex/hw",
"ports/minimal",
"ports/mimxrt10xx/peripherals",
"ports/mimxrt10xx/sdk",
"ports/nrf/device",
"ports/nrf/bluetooth",
"ports/nrf/modules",
"ports/nrf/nrfx",
"ports/nrf/peripherals",
"ports/nrf/usb",
"ports/raspberrypi/sdk",
"ports/stm/st_driver",
"ports/stm/packages",
"ports/stm/peripherals",
"ports/stm/ref",
"ports/unix",
"py",
"shared-bindings/util.*",
"shared-module",
"supervisor",
"tests",
"test-stubs",
"tools",
"circuitpython-stubs/README.rst"]
# The reST default role (used for this markup: `text`) to use for all
# documents.
default_role = 'any'
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# Global include files. Sphinx docs suggest using rst_epilog in preference
# of rst_prolog, so we follow. Absolute paths below mean "from the base
# of the doctree".
rst_epilog = """
.. include:: /docs/templates/replace.inc
"""
# -- Options for HTML output ----------------------------------------------
# on_rtd is whether we are on readthedocs.org
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if not on_rtd: # only import and set the theme if we're building docs locally
try:
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), '.']
except:
html_theme = 'default'
html_theme_path = ['.']
else:
html_theme_path = ['.']
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = ['.']
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = '../../logo/trans-logo.png'
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
html_favicon = 'docs/static/favicon.ico'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['docs/static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
html_last_updated_fmt = '%d %b %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {"index": "topindex.html"}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'CircuitPythondoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
# Include 3 levels of headers in PDF ToC
'preamble': '\setcounter{tocdepth}{2}',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'CircuitPython.tex', 'CircuitPython Documentation',
'CircuitPython Contributors', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'CircuitPython', 'CircuitPython Documentation',
['CircuitPython contributors'], 1),
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'CircuitPython', 'CircuitPython Documentation',
'CircuitPython contributors', 'CircuitPython', 'Python for Microcontrollers.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {"cpython": ('https://docs.python.org/3/', None),
"register": ('https://circuitpython.readthedocs.io/projects/register/en/latest/', None)}
# Adapted from sphinxcontrib-redirects
from sphinx.builders import html as builders
TEMPLATE = """<html>
<head><meta http-equiv="refresh" content="0; url=%s"/></head>
</html>
"""
def generate_redirects(app):
path = os.path.join(app.srcdir, app.config.redirects_file)
if not os.path.exists(path):
logging.error("Could not find redirects file at '%s'" % path)
return
if not isinstance(app.builder, builders.StandaloneHTMLBuilder):
logging.warn("The 'sphinxcontib-redirects' plugin is only supported "
"by the 'html' builder and subclasses. Skipping...")
logging.warn(f"Builder is {app.builder.name} ({type(app.builder)})")
return
with open(path) as redirects:
for line in redirects.readlines():
from_path, to_path = line.rstrip().split(' ')
logging.debug("Redirecting '%s' to '%s'" % (from_path, to_path))
from_path = os.path.splitext(from_path)[0] + ".html"
to_path_prefix = '..%s' % os.path.sep * (
len(from_path.split(os.path.sep)) - 1)
to_path = to_path_prefix + to_path
redirected_filename = os.path.join(app.builder.outdir, from_path)
redirected_directory = os.path.dirname(redirected_filename)
if not os.path.exists(redirected_directory):
os.makedirs(redirected_directory)
with open(redirected_filename, 'w') as f:
f.write(TEMPLATE % urllib.parse.quote(to_path, '#/'))
class CoreModuleTransform(SphinxTransform):
default_priority = 870
def _convert_first_paragraph_into_title(self):
title = self.document.next_node(nodes.title)
paragraph = self.document.next_node(nodes.paragraph)
if not title or not paragraph:
return
if isinstance(paragraph[0], nodes.paragraph):
paragraph = paragraph[0]
if all(isinstance(child, nodes.Text) for child in paragraph.children):
for child in paragraph.children:
title.append(nodes.Text(" \u2013 "))
title.append(child)
paragraph.parent.remove(paragraph)
def _enable_linking_to_nonclass_targets(self):
for desc in self.document.traverse(addnodes.desc):
for xref in desc.traverse(addnodes.pending_xref):
if xref.attributes.get("reftype") == "class":
xref.attributes.pop("refspecific", None)
def apply(self, **kwargs):
docname = self.env.docname
if docname.startswith(autoapi_root) and docname.endswith("/index"):
self._convert_first_paragraph_into_title()
self._enable_linking_to_nonclass_targets()
def setup(app):
app.add_css_file("customstyle.css")
app.add_css_file("filter.css")
app.add_js_file("filter.js")
app.add_config_value('redirects_file', 'redirects', 'env')
app.connect('builder-inited', generate_redirects)
app.add_transform(CoreModuleTransform)

1
data/nvm.toml Submodule

@ -0,0 +1 @@
Subproject commit e5b149599d14a8841167fe552846ca36925b87a0

973
devices/ble_hci/common-hal/_bleio/Adapter.c Normal file
View File

@ -0,0 +1,973 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2020 Dan Halbert for Adafruit Industries
* Copyright (c) 2016 Glenn Ruben Bakke
* Copyright (c) 2018 Artur Pacholec
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#include <math.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>
#include "hci.h"
#include "py/gc.h"
#include "py/mphal.h"
#include "py/objstr.h"
#include "py/runtime.h"
#include "supervisor/shared/safe_mode.h"
#include "supervisor/shared/tick.h"
#include "supervisor/usb.h"
#include "shared-bindings/_bleio/__init__.h"
#include "shared-bindings/_bleio/Adapter.h"
#include "shared-bindings/_bleio/Address.h"
#include "shared-bindings/_bleio/Characteristic.h"
#include "shared-bindings/_bleio/Service.h"
#include "shared-bindings/_bleio/Connection.h"
#include "shared-bindings/_bleio/ScanEntry.h"
#include "shared-bindings/time/__init__.h"
#define MSEC_TO_UNITS(TIME, RESOLUTION) (((TIME) * 1000) / (RESOLUTION))
#define SEC_TO_UNITS(TIME, RESOLUTION) (((TIME) * 1000000) / (RESOLUTION))
#define UNITS_TO_SEC(TIME, RESOLUTION) (((TIME)*(RESOLUTION)) / 1000000)
// 0.625 msecs (625 usecs)
#define ADV_INTERVAL_UNIT_FLOAT_SECS (0.000625)
// Microseconds is the base unit. The macros above know that.
#define UNIT_0_625_MS (625)
#define UNIT_1_25_MS (1250)
#define UNIT_10_MS (10000)
#define MAX_ADVERTISEMENT_SIZE (31)
// TODO make this settable from Python.
#define DEFAULT_TX_POWER 0 // 0 dBm
#define MAX_ANONYMOUS_ADV_TIMEOUT_SECS (60 * 15)
#define MAX_LIMITED_DISCOVERABLE_ADV_TIMEOUT_SECS (180)
#define BLE_MIN_CONN_INTERVAL MSEC_TO_UNITS(15, UNIT_0_625_MS)
#define BLE_MAX_CONN_INTERVAL MSEC_TO_UNITS(15, UNIT_0_625_MS)
#define BLE_SLAVE_LATENCY 0
#define BLE_CONN_SUP_TIMEOUT MSEC_TO_UNITS(4000, UNIT_10_MS)
bleio_connection_internal_t bleio_connections[BLEIO_TOTAL_CONNECTION_COUNT];
STATIC void add_generic_services(bleio_adapter_obj_t *adapter) {
// Create Generic Access UUID, Service, and Characteristics.
// Generic Access Service setup.
bleio_uuid_obj_t *generic_access_service_uuid = m_new_obj(bleio_uuid_obj_t);
generic_access_service_uuid->base.type = &bleio_uuid_type;
common_hal_bleio_uuid_construct(generic_access_service_uuid, 0x1800, NULL);
bleio_uuid_obj_t *device_name_characteristic_uuid = m_new_obj(bleio_uuid_obj_t);
device_name_characteristic_uuid->base.type = &bleio_uuid_type;
common_hal_bleio_uuid_construct(device_name_characteristic_uuid, 0x2A00, NULL);
bleio_uuid_obj_t *appearance_characteristic_uuid = m_new_obj(bleio_uuid_obj_t);
appearance_characteristic_uuid->base.type = &bleio_uuid_type;
common_hal_bleio_uuid_construct(appearance_characteristic_uuid, 0x2A01, NULL);
// Not implemented:
// Peripheral Preferred Connection Parameters
// Central Address Resolution
bleio_service_obj_t *generic_access_service = m_new_obj(bleio_service_obj_t);
generic_access_service->base.type = &bleio_service_type;
common_hal_bleio_service_construct(generic_access_service, generic_access_service_uuid, false);
adapter->device_name_characteristic = m_new_obj(bleio_characteristic_obj_t);
adapter->device_name_characteristic->base.type = &bleio_characteristic_type;
char generic_name[] = { 'C', 'I', 'R', 'C', 'U', 'I', 'T', 'P', 'Y', 'n', 'n', 'n', 'n' };
mp_buffer_info_t generic_name_bufinfo = {
.buf = generic_name,
.len = sizeof(generic_name),
};
// Will be added to service by constructor.
common_hal_bleio_characteristic_construct(
adapter->device_name_characteristic,
generic_access_service,
BLE_GATT_HANDLE_INVALID,
device_name_characteristic_uuid,
CHAR_PROP_READ,
SECURITY_MODE_OPEN,
SECURITY_MODE_NO_ACCESS,
248, // max length, from Bluetooth spec
false, // not fixed length
&generic_name_bufinfo,
NULL
);
uint16_t zero_16 = 0;
mp_buffer_info_t zero_16_value = {
.buf = &zero_16,
.len = sizeof(zero_16),
};
adapter->appearance_characteristic = m_new_obj(bleio_characteristic_obj_t);
adapter->appearance_characteristic->base.type = &bleio_characteristic_type;
common_hal_bleio_characteristic_construct(
adapter->appearance_characteristic,
generic_access_service,
BLE_GATT_HANDLE_INVALID,
appearance_characteristic_uuid,
CHAR_PROP_READ,
SECURITY_MODE_OPEN,
SECURITY_MODE_NO_ACCESS,
2, // max length, from Bluetooth spec
true, // fixed length
&zero_16_value,
NULL
);
// Generic Attribute Service setup.
bleio_uuid_obj_t *generic_attribute_service_uuid = m_new_obj(bleio_uuid_obj_t);
generic_attribute_service_uuid->base.type = &bleio_uuid_type;
common_hal_bleio_uuid_construct(generic_attribute_service_uuid, 0x1801, NULL);
bleio_uuid_obj_t *service_changed_characteristic_uuid = m_new_obj(bleio_uuid_obj_t);
service_changed_characteristic_uuid->base.type = &bleio_uuid_type;
common_hal_bleio_uuid_construct(service_changed_characteristic_uuid, 0x2A05, NULL);
bleio_service_obj_t *generic_attribute_service = m_new_obj(bleio_service_obj_t);
generic_attribute_service->base.type = &bleio_service_type;
common_hal_bleio_service_construct(generic_attribute_service, generic_attribute_service_uuid, false);
adapter->service_changed_characteristic = m_new_obj(bleio_characteristic_obj_t);
adapter->service_changed_characteristic->base.type = &bleio_characteristic_type;
uint32_t zero_32 = 0;
mp_buffer_info_t zero_32_value = {
.buf = &zero_32,
.len = sizeof(zero_32),
};
common_hal_bleio_characteristic_construct(
adapter->service_changed_characteristic,
generic_attribute_service,
BLE_GATT_HANDLE_INVALID,
service_changed_characteristic_uuid,
CHAR_PROP_INDICATE,
SECURITY_MODE_OPEN,
SECURITY_MODE_NO_ACCESS,
4, // max length, from Bluetooth spec
true, // fixed length
&zero_32_value,
NULL
);
}
STATIC void check_enabled(bleio_adapter_obj_t *adapter) {
if (!common_hal_bleio_adapter_get_enabled(adapter)) {
mp_raise_bleio_BluetoothError(translate("Adapter not enabled"));
}
}
// STATIC bool adapter_on_ble_evt(ble_evt_t *ble_evt, void *self_in) {
// bleio_adapter_obj_t *self = (bleio_adapter_obj_t*)self_in;
// // For debugging.
// // mp_printf(&mp_plat_print, "Adapter event: 0x%04x\n", ble_evt->header.evt_id);
// switch (ble_evt->header.evt_id) {
// case BLE_GAP_EVT_CONNECTED: {
// // Find an empty connection. One must always be available because the SD has the same
// // total connection limit.
// bleio_connection_internal_t *connection;
// for (size_t i = 0; i < BLEIO_TOTAL_CONNECTION_COUNT; i++) {
// connection = &bleio_connections[i];
// if (connection->conn_handle == BLE_CONN_HANDLE_INVALID) {
// break;
// }
// }
// // Central has connected.
// ble_gap_evt_connected_t* connected = &ble_evt->evt.gap_evt.params.connected;
// connection->conn_handle = ble_evt->evt.gap_evt.conn_handle;
// connection->connection_obj = mp_const_none;
// connection->pair_status = PAIR_NOT_PAIRED;
// connection->mtu = 0;
// ble_drv_add_event_handler_entry(&connection->handler_entry, connection_on_ble_evt, connection);
// self->connection_objs = NULL;
// // Save the current connection parameters.
// memcpy(&connection->conn_params, &connected->conn_params, sizeof(ble_gap_conn_params_t));
// #if CIRCUITPY_VERBOSE_BLE
// ble_gap_conn_params_t *cp = &connected->conn_params;
// mp_printf(&mp_plat_print, "conn params: min_ci %d max_ci %d s_l %d sup_timeout %d\n", cp->min_conn_interval, cp->max_conn_interval, cp->slave_latency, cp->conn_sup_timeout);
// #endif
// // See if connection interval set by Central is out of range.
// // If so, negotiate our preferred range.
// ble_gap_conn_params_t conn_params;
// sd_ble_gap_ppcp_get(&conn_params);
// if (conn_params.min_conn_interval < connected->conn_params.min_conn_interval ||
// conn_params.min_conn_interval > connected->conn_params.max_conn_interval) {
// sd_ble_gap_conn_param_update(ble_evt->evt.gap_evt.conn_handle, &conn_params);
// }
// self->current_advertising_data = NULL;
// break;
// }
// case BLE_GAP_EVT_DISCONNECTED: {
// // Find the connection that was disconnected.
// bleio_connection_internal_t *connection;
// for (size_t i = 0; i < BLEIO_TOTAL_CONNECTION_COUNT; i++) {
// connection = &bleio_connections[i];
// if (connection->conn_handle == ble_evt->evt.gap_evt.conn_handle) {
// break;
// }
// }
// ble_drv_remove_event_handler(connection_on_ble_evt, connection);
// connection->conn_handle = BLE_CONN_HANDLE_INVALID;
// connection->pair_status = PAIR_NOT_PAIRED;
// if (connection->connection_obj != mp_const_none) {
// bleio_connection_obj_t* obj = connection->connection_obj;
// obj->connection = NULL;
// obj->disconnect_reason = ble_evt->evt.gap_evt.params.disconnected.reason;
// }
// self->connection_objs = NULL;
// break;
// }
// case BLE_GAP_EVT_ADV_SET_TERMINATED:
// self->current_advertising_data = NULL;
// break;
// default:
// // For debugging.
// // mp_printf(&mp_plat_print, "Unhandled adapter event: 0x%04x\n", ble_evt->header.evt_id);
// return false;
// break;
// }
// return true;
// }
char default_ble_name[] = { 'C', 'I', 'R', 'C', 'U', 'I', 'T', 'P', 'Y', 0, 0, 0, 0};
// Get various values and limits set by the adapter.
// Set event mask.
STATIC void bleio_adapter_hci_init(bleio_adapter_obj_t *self) {
const size_t len = sizeof(default_ble_name);
bt_addr_t addr;
hci_check_error(hci_read_bd_addr(&addr));
default_ble_name[len - 4] = nibble_to_hex_lower[addr.val[1] >> 4 & 0xf];
default_ble_name[len - 3] = nibble_to_hex_lower[addr.val[1] & 0xf];
default_ble_name[len - 2] = nibble_to_hex_lower[addr.val[0] >> 4 & 0xf];
default_ble_name[len - 1] = nibble_to_hex_lower[addr.val[0] & 0xf];
self->name = mp_obj_new_str(default_ble_name, len);
// Get version information.
if (hci_read_local_version(&self->hci_version, &self->hci_revision, &self->lmp_version,
&self->manufacturer, &self->lmp_subversion) != HCI_OK) {
mp_raise_bleio_BluetoothError(translate("Could not read HCI version"));
}
// Get supported features.
if (hci_le_read_local_supported_features(self->features) != HCI_OK) {
mp_raise_bleio_BluetoothError(translate("Could not read BLE features"));
}
// Enabled desired events.
// Most importantly, includes:
// BT_EVT_MASK_LE_META_EVENT BT_EVT_BIT(61)
if (hci_set_event_mask(0x3FFFFFFFFFFFFFFF) != HCI_OK) {
mp_raise_bleio_BluetoothError(translate("Could not set event mask"));
}
// The default events for LE are:
// BT_EVT_MASK_LE_CONN_COMPLETE, BT_EVT_MASK_LE_ADVERTISING_REPORT,
// BT_EVT_MASK_LE_CONN_UPDATE_COMPLETE, BT_EVT_MASK_LE_REMOTE_FEAT_COMPLETE
// BT_EVT_MASK_LE_LTK_REQUEST.
// That's all we need right now, so we don't bother to set the LE event mask.
// Get ACL buffer info.
uint16_t le_max_len;
uint8_t le_max_num;
if (hci_le_read_buffer_size(&le_max_len, &le_max_num) == HCI_OK) {
self->max_acl_buffer_len = le_max_len;
self->max_acl_num_buffers = le_max_num;
} else {
// LE Read Buffer Size not available; use the general Read Buffer Size.
uint16_t acl_max_len;
uint8_t sco_max_len;
uint16_t acl_max_num;
uint16_t sco_max_num;
if (hci_read_buffer_size(&acl_max_len, &sco_max_len, &acl_max_num, &sco_max_num) != HCI_OK) {
mp_raise_bleio_BluetoothError(translate("Could not read BLE buffer info"));
}
self->max_acl_buffer_len = acl_max_len;
self->max_acl_num_buffers = acl_max_num;
}
// Get max advertising length if extended advertising is supported.
if (BT_FEAT_LE_EXT_ADV(self->features)) {
uint16_t max_adv_data_len;
if (hci_le_read_maximum_advertising_data_length(&max_adv_data_len) != HCI_OK) {
mp_raise_bleio_BluetoothError(translate("Could not get max advertising length"));
}
self->max_adv_data_len = max_adv_data_len;
} else {
self->max_adv_data_len = MAX_ADVERTISEMENT_SIZE;
}
}
void common_hal_bleio_adapter_construct_hci_uart(bleio_adapter_obj_t *self, busio_uart_obj_t *uart, digitalio_digitalinout_obj_t *rts, digitalio_digitalinout_obj_t *cts) {
self->allocated = true;
self->hci_uart = uart;
self->rts_digitalinout = rts;
self->cts_digitalinout = cts;
// Advertising-related fields are initialized by common_hal_bleio_adapter_set_enabled().
self->enabled = false;
common_hal_bleio_adapter_set_enabled(self, true);
bleio_adapter_hci_init(self);
common_hal_bleio_adapter_set_name(self, default_ble_name);
}
void common_hal_bleio_adapter_set_enabled(bleio_adapter_obj_t *self, bool enabled) {
const bool is_enabled = common_hal_bleio_adapter_get_enabled(self);
// Don't enable or disable twice
if (is_enabled == enabled) {
return;
}
self->enabled = enabled;
// We must poll for input from the HCI adapter.
// TODO Can we instead trigger an interrupt on UART input traffic?
if (enabled) {
supervisor_enable_tick();
} else {
supervisor_disable_tick();
}
// Enabling or disabling: stop any current activity; reset to known state.
hci_reset();
self->now_advertising = false;
self->extended_advertising = false;
self->circuitpython_advertising = false;
self->advertising_timeout_msecs = 0;
if (enabled) {
// Reset list of known attributes.
// Indices into the list are handles. Handle 0x0000 designates an invalid handle,
// so store None there to skip it.
self->attributes = mp_obj_new_list(0, NULL);
bleio_adapter_add_attribute(self, mp_const_none);
add_generic_services(self);
}
}
bool common_hal_bleio_adapter_get_enabled(bleio_adapter_obj_t *self) {
return self->enabled;
}
bleio_address_obj_t *common_hal_bleio_adapter_get_address(bleio_adapter_obj_t *self) {
check_enabled(self);
bt_addr_t addr;
hci_check_error(hci_read_bd_addr(&addr));
bleio_address_obj_t *address = m_new_obj(bleio_address_obj_t);
address->base.type = &bleio_address_type;
common_hal_bleio_address_construct(address, addr.val, BT_ADDR_LE_PUBLIC);
return address;
}
bool common_hal_bleio_adapter_set_address(bleio_adapter_obj_t *self, bleio_address_obj_t *address) {
mp_buffer_info_t bufinfo;
if (!mp_get_buffer(address->bytes, &bufinfo, MP_BUFFER_READ)) {
return false;
}
return hci_le_set_random_address(bufinfo.buf) == HCI_OK;
}
mp_obj_str_t *common_hal_bleio_adapter_get_name(bleio_adapter_obj_t *self) {
return self->name;
}
void common_hal_bleio_adapter_set_name(bleio_adapter_obj_t *self, const char *name) {
self->name = mp_obj_new_str(name, strlen(name));
mp_buffer_info_t bufinfo;
mp_get_buffer_raise(self->name, &bufinfo, MP_BUFFER_READ);
bleio_characteristic_set_local_value(self->device_name_characteristic, &bufinfo);
}
// STATIC bool scan_on_ble_evt(ble_evt_t *ble_evt, void *scan_results_in) {
// bleio_scanresults_obj_t *scan_results = (bleio_scanresults_obj_t*)scan_results_in;
// if (ble_evt->header.evt_id == BLE_GAP_EVT_TIMEOUT &&
// ble_evt->evt.gap_evt.params.timeout.src == BLE_GAP_TIMEOUT_SRC_SCAN) {
// shared_module_bleio_scanresults_set_done(scan_results, true);
// ble_drv_remove_event_handler(scan_on_ble_evt, scan_results);
// return true;
// }
// if (ble_evt->header.evt_id != BLE_GAP_EVT_ADV_REPORT) {
// return false;
// }
// ble_gap_evt_adv_report_t *report = &ble_evt->evt.gap_evt.params.adv_report;
// shared_module_bleio_scanresults_append(scan_results,
// supervisor_ticks_ms64(),
// report->type.connectable,
// report->type.scan_response,
// report->rssi,
// report->peer_addr.addr,
// report->peer_addr.addr_type,
// report->data.p_data,
// report->data.len);
// const uint32_t err_code = sd_ble_gap_scan_start(NULL, scan_results->common_hal_data);
// if (err_code != NRF_SUCCESS) {
// // TODO: Pass the error into the scan results so it can throw an exception.
// scan_results->done = true;
// }
// return true;
// }
mp_obj_t common_hal_bleio_adapter_start_scan(bleio_adapter_obj_t *self, uint8_t *prefixes, size_t prefix_length, bool extended, mp_int_t buffer_size, mp_float_t timeout, mp_float_t interval, mp_float_t window, mp_int_t minimum_rssi, bool active) {
// TODO
mp_raise_NotImplementedError(NULL);
check_enabled(self);
if (self->scan_results != NULL) {
if (!shared_module_bleio_scanresults_get_done(self->scan_results)) {
mp_raise_bleio_BluetoothError(translate("Scan already in progess. Stop with stop_scan."));
}
self->scan_results = NULL;
}
self->scan_results = shared_module_bleio_new_scanresults(buffer_size, prefixes, prefix_length, minimum_rssi);
// size_t max_packet_size = extended ? BLE_GAP_SCAN_BUFFER_EXTENDED_MAX_SUPPORTED : BLE_GAP_SCAN_BUFFER_MAX;
// uint8_t *raw_data = m_malloc(sizeof(ble_data_t) + max_packet_size, false);
// ble_data_t * sd_data = (ble_data_t *) raw_data;
// self->scan_results->common_hal_data = sd_data;
// sd_data->len = max_packet_size;
// sd_data->p_data = raw_data + sizeof(ble_data_t);
// ble_drv_add_event_handler(scan_on_ble_evt, self->scan_results);
// uint32_t nrf_timeout = SEC_TO_UNITS(timeout, UNIT_10_MS);
// if (timeout <= 0.0001) {
// nrf_timeout = BLE_GAP_SCAN_TIMEOUT_UNLIMITED;
// }
// ble_gap_scan_params_t scan_params = {
// .extended = extended,
// .interval = SEC_TO_UNITS(interval, UNIT_0_625_MS),
// .timeout = nrf_timeout,
// .window = SEC_TO_UNITS(window, UNIT_0_625_MS),
// .scan_phys = BLE_GAP_PHY_1MBPS,
// .active = active
// };
// uint32_t err_code;
// vm_used_ble = true;
// err_code = sd_ble_gap_scan_start(&scan_params, sd_data);
// if (err_code != NRF_SUCCESS) {
// self->scan_results = NULL;
// ble_drv_remove_event_handler(scan_on_ble_evt, self->scan_results);
// check_nrf_error(err_code);
// }
return MP_OBJ_FROM_PTR(self->scan_results);
}
void common_hal_bleio_adapter_stop_scan(bleio_adapter_obj_t *self) {
// TODO
mp_raise_NotImplementedError(NULL);
check_enabled(self);
// If not already scanning, no problem.
if (hci_le_set_scan_enable(BT_HCI_LE_SCAN_DISABLE, BT_HCI_LE_SCAN_FILTER_DUP_DISABLE) == HCI_OK) {
shared_module_bleio_scanresults_set_done(self->scan_results, true);
self->scan_results = NULL;
}
}
// typedef struct {
// uint16_t conn_handle;
// volatile bool done;
// } connect_info_t;
// STATIC bool connect_on_ble_evt(ble_evt_t *ble_evt, void *info_in) {
// connect_info_t *info = (connect_info_t*)info_in;
// switch (ble_evt->header.evt_id) {
// case BLE_GAP_EVT_CONNECTED:
// info->conn_handle = ble_evt->evt.gap_evt.conn_handle;
// info->done = true;
// break;
// case BLE_GAP_EVT_TIMEOUT:
// // Handle will be invalid.
// info->done = true;
// break;
// default:
// // For debugging.
// // mp_printf(&mp_plat_print, "Unhandled central event: 0x%04x\n", ble_evt->header.evt_id);
// return false;
// break;
// }
// return true;
// }
mp_obj_t common_hal_bleio_adapter_connect(bleio_adapter_obj_t *self, bleio_address_obj_t *address, mp_float_t timeout) {
// TODO
mp_raise_NotImplementedError(NULL);
check_enabled(self);
// ble_gap_addr_t addr;
// addr.addr_type = address->type;
// mp_buffer_info_t address_buf_info;
// mp_get_buffer_raise(address->bytes, &address_buf_info, MP_BUFFER_READ);
// memcpy(addr.addr, (uint8_t *) address_buf_info.buf, NUM_BLEIO_ADDRESS_BYTES);
// ble_gap_scan_params_t scan_params = {
// .interval = MSEC_TO_UNITS(100, UNIT_0_625_MS),
// .window = MSEC_TO_UNITS(100, UNIT_0_625_MS),
// .scan_phys = BLE_GAP_PHY_1MBPS,
// // timeout of 0 means no timeout
// .timeout = SEC_TO_UNITS(timeout, UNIT_10_MS),
// };
// ble_gap_conn_params_t conn_params = {
// .conn_sup_timeout = MSEC_TO_UNITS(4000, UNIT_10_MS),
// .min_conn_interval = MSEC_TO_UNITS(15, UNIT_1_25_MS),
// .max_conn_interval = MSEC_TO_UNITS(300, UNIT_1_25_MS),
// .slave_latency = 0, // number of conn events
// };
// connect_info_t event_info;
// ble_drv_add_event_handler(connect_on_ble_evt, &event_info);
// event_info.done = false;
vm_used_ble = true;
// uint32_t err_code = sd_ble_gap_connect(&addr, &scan_params, &conn_params, BLE_CONN_CFG_TAG_CUSTOM);
// if (err_code != NRF_SUCCESS) {
// ble_drv_remove_event_handler(connect_on_ble_evt, &event_info);
// check_nrf_error(err_code);
// }
// while (!event_info.done) {
// RUN_BACKGROUND_TASKS;
// }
// ble_drv_remove_event_handler(connect_on_ble_evt, &event_info);
// uint16_t conn_handle = event_info.conn_handle;
// if (conn_handle == BLE_CONN_HANDLE_INVALID) {
// mp_raise_bleio_BluetoothError(translate("Failed to connect: timeout"));
// }
// // Negotiate for better PHY, larger MTU and data lengths since we are the central. These are
// // nice-to-haves so ignore any errors.
// ble_gap_phys_t const phys = {
// .rx_phys = BLE_GAP_PHY_AUTO,
// .tx_phys = BLE_GAP_PHY_AUTO,
// };
// sd_ble_gap_phy_update(conn_handle, &phys);
// sd_ble_gattc_exchange_mtu_request(conn_handle, BLE_GATTS_VAR_ATTR_LEN_MAX);
// sd_ble_gap_data_length_update(conn_handle, NULL, NULL);
// Make the connection object and return it.
// for (size_t i = 0; i < BLEIO_TOTAL_CONNECTION_COUNT; i++) {
// bleio_connection_internal_t *connection = &bleio_connections[i];
// if (connection->conn_handle == conn_handle) {
// return bleio_connection_new_from_internal(connection);
// }
// }
mp_raise_bleio_BluetoothError(translate("Failed to connect: internal error"));
return mp_const_none;
}
STATIC void check_data_fit(size_t data_len, bool connectable) {
if (data_len > MAX_ADVERTISEMENT_SIZE) {
mp_raise_ValueError(translate("Data too large for advertisement packet"));
}
}
// STATIC bool advertising_on_ble_evt(ble_evt_t *ble_evt, void *self_in) {
// bleio_adapter_obj_t *self = (bleio_adapter_obj_t*)self_in;
// switch (ble_evt->header.evt_id) {
// case BLE_GAP_EVT_ADV_SET_TERMINATED:
// common_hal_bleio_adapter_stop_advertising(self);
// ble_drv_remove_event_handler(advertising_on_ble_evt, self_in);
// break;
// default:
// // For debugging.
// // mp_printf(&mp_plat_print, "Unhandled advertising event: 0x%04x\n", ble_evt->header.evt_id);
// return false;
// break;
// }
// return true;
// }
uint32_t _common_hal_bleio_adapter_start_advertising(bleio_adapter_obj_t *self,
bool connectable, bool anonymous, uint32_t timeout, float interval,
const uint8_t *advertising_data, uint16_t advertising_data_len,
const uint8_t *scan_response_data, uint16_t scan_response_data_len,
mp_int_t tx_power, const bleio_address_obj_t *directed_to) {
check_enabled(self);
if (self->now_advertising) {
if (self->circuitpython_advertising) {
common_hal_bleio_adapter_stop_advertising(self);
} else {
// User-requested advertising.
// TODO allow multiple advertisements.
// Already advertising. Can't advertise twice.
return 1;
}
}
// Peer address, which we don't use (no directed advertising).
bt_addr_le_t empty_addr = { 0 };
bool extended =
advertising_data_len > self->max_adv_data_len || scan_response_data_len > self->max_adv_data_len;
if (extended) {
if (!BT_FEAT_LE_EXT_ADV(self->features)) {
mp_raise_bleio_BluetoothError(translate("Data length needs extended advertising, but this adapter does not support it"));
}
uint16_t props = 0;
if (connectable) {
props |= BT_HCI_LE_ADV_PROP_CONN;
}
if (scan_response_data_len > 0) {
props |= BT_HCI_LE_ADV_PROP_SCAN;
}
// Advertising interval.
uint32_t interval_units = SEC_TO_UNITS(interval, UNIT_0_625_MS);
hci_check_error(
hci_le_set_extended_advertising_parameters(
0, // handle
props, // adv properties
interval_units, // min interval
interval_units, // max interval
0b111, // channel map: channels 37, 38, 39
anonymous ? BT_ADDR_LE_RANDOM : BT_ADDR_LE_PUBLIC,
&empty_addr, // peer_addr,
0x00, // filter policy: no filter
DEFAULT_TX_POWER,
BT_HCI_LE_EXT_SCAN_PHY_1M, // Secondary PHY to use
0x00, // AUX_ADV_IND shall be sent prior to next adv event
BT_HCI_LE_EXT_SCAN_PHY_1M, // Secondary PHY to use
0x00, // Advertising SID
0x00 // Scan req notify disable
));
// We can use the duration mechanism provided, instead of our own.
self->advertising_timeout_msecs = 0;
uint8_t handle[1] = { 0 };
uint16_t duration_10msec[1] = { timeout * 100 };
uint8_t max_ext_adv_evts[1] = { 0 };
hci_check_error(
hci_le_set_extended_advertising_enable(
BT_HCI_LE_ADV_ENABLE,
1, // one advertising set.
handle,
duration_10msec,
max_ext_adv_evts
));
self->extended_advertising = true;
} else {
// Legacy advertising (not extended).
uint8_t adv_type;
if (connectable) {
// Connectable, scannable, undirected.
adv_type = BT_HCI_ADV_IND;
} else if (scan_response_data_len > 0) {
// Unconnectable, scannable, undirected.
adv_type = BT_HCI_ADV_SCAN_IND;
} else {
// Unconnectable, unscannable, undirected.
adv_type = BT_HCI_ADV_NONCONN_IND;
}
// Advertising interval.
uint16_t interval_units = SEC_TO_UNITS(interval, UNIT_0_625_MS);
hci_check_error(
hci_le_set_advertising_parameters(
interval_units, // min interval
interval_units, // max interval
adv_type,
anonymous ? BT_ADDR_LE_RANDOM : BT_ADDR_LE_PUBLIC,
&empty_addr,
0b111, // channel map: channels 37, 38, 39
0x00 // filter policy: no filter
));
// The HCI commands expect MAX_ADVERTISEMENT_SIZE (31)octets,
// even though the actual data length may be shorter.
uint8_t full_data[MAX_ADVERTISEMENT_SIZE] = { 0 };
memcpy(full_data, advertising_data, MIN(sizeof(full_data), advertising_data_len));
hci_check_error(hci_le_set_advertising_data(advertising_data_len, full_data));
memset(full_data, 0, sizeof(full_data));
if (scan_response_data_len > 0) {
memcpy(full_data, scan_response_data, MIN(sizeof(full_data), scan_response_data_len));
hci_check_error(hci_le_set_scan_response_data(scan_response_data_len, full_data));
}
// No duration mechanism is provided for legacy advertising, so we need to do our own.
self->advertising_timeout_msecs = timeout * 1000;
self->advertising_start_ticks = supervisor_ticks_ms64();
// Start advertising.
hci_check_error(hci_le_set_advertising_enable(BT_HCI_LE_ADV_ENABLE));
self->extended_advertising = false;
} // end legacy advertising setup
vm_used_ble = true;
self->now_advertising = true;
return 0;
}
void common_hal_bleio_adapter_start_advertising(bleio_adapter_obj_t *self,
bool connectable, bool anonymous, uint32_t timeout, mp_float_t interval,
mp_buffer_info_t *advertising_data_bufinfo,
mp_buffer_info_t *scan_response_data_bufinfo,
mp_int_t tx_power, const bleio_address_obj_t *directed_to) {
check_enabled(self);
// interval value has already been validated.
check_data_fit(advertising_data_bufinfo->len, connectable);
check_data_fit(scan_response_data_bufinfo->len, connectable);
if (advertising_data_bufinfo->len > MAX_ADVERTISEMENT_SIZE && scan_response_data_bufinfo->len > 0) {
mp_raise_bleio_BluetoothError(translate("Extended advertisements with scan response not supported."));
}
// Anonymous mode requires a timeout so that we don't continue to broadcast
// the same data while cycling the MAC address -- otherwise, what's the
// point of randomizing the MAC address?
if (timeout == 0 && anonymous) {
timeout = MAX_ANONYMOUS_ADV_TIMEOUT_SECS;
} else {
if (timeout > MAX_LIMITED_DISCOVERABLE_ADV_TIMEOUT_SECS) {
mp_raise_bleio_BluetoothError(translate("Timeout is too long: Maximum timeout length is %d seconds"),
MAX_LIMITED_DISCOVERABLE_ADV_TIMEOUT_SECS);
}
}
if (tx_power != 0) {
mp_raise_NotImplementedError(translate("Only tx_power=0 supported"));
}
const uint32_t result = _common_hal_bleio_adapter_start_advertising(
self, connectable, anonymous, timeout, interval,
advertising_data_bufinfo->buf,
advertising_data_bufinfo->len,
scan_response_data_bufinfo->buf,
scan_response_data_bufinfo->len,
tx_power, directed_to);
if (result) {
mp_raise_bleio_BluetoothError(translate("Already advertising"));
}
self->circuitpython_advertising = false;
}
void common_hal_bleio_adapter_stop_advertising(bleio_adapter_obj_t *self) {
check_enabled(self);
self->now_advertising = false;
self->extended_advertising = false;
self->circuitpython_advertising = false;
int result = hci_le_set_advertising_enable(BT_HCI_LE_ADV_DISABLE);
// OK if we're already stopped. There seems to be an ESP32 HCI bug:
// If advertising is already off, then LE_SET_ADV_ENABLE does not return a response.
if (result != HCI_RESPONSE_TIMEOUT) {
hci_check_error(result);
}
// TODO startup CircuitPython advertising again.
}
// Note that something stopped advertising, such as a connection happening.
// Don't ask the adapter to stop.
void bleio_adapter_advertising_was_stopped(bleio_adapter_obj_t *self) {
self->now_advertising = false;
self->extended_advertising = false;
self->circuitpython_advertising = false;
}
bool common_hal_bleio_adapter_get_advertising(bleio_adapter_obj_t *self) {
check_enabled(self);
return self->now_advertising;
}
bool common_hal_bleio_adapter_get_connected(bleio_adapter_obj_t *self) {
check_enabled(self);
for (size_t i = 0; i < BLEIO_TOTAL_CONNECTION_COUNT; i++) {
bleio_connection_internal_t *connection = &bleio_connections[i];
if (connection->conn_handle != BLE_CONN_HANDLE_INVALID) {
return true;
}
}
return false;
}
mp_obj_t common_hal_bleio_adapter_get_connections(bleio_adapter_obj_t *self) {
check_enabled(self);
if (self->connection_objs != NULL) {
return self->connection_objs;
}
size_t total_connected = 0;
mp_obj_t items[BLEIO_TOTAL_CONNECTION_COUNT];
for (size_t i = 0; i < BLEIO_TOTAL_CONNECTION_COUNT; i++) {
bleio_connection_internal_t *connection = &bleio_connections[i];
if (connection->conn_handle != BLE_CONN_HANDLE_INVALID) {
if (connection->connection_obj == mp_const_none) {
connection->connection_obj = bleio_connection_new_from_internal(connection);
}
items[total_connected] = connection->connection_obj;
total_connected++;
}
}
self->connection_objs = mp_obj_new_tuple(total_connected, items);
return self->connection_objs;
}
void common_hal_bleio_adapter_erase_bonding(bleio_adapter_obj_t *self) {
// TODO
mp_raise_NotImplementedError(NULL);
check_enabled(self);
// FIX bonding_erase_storage();
}
uint16_t bleio_adapter_add_attribute(bleio_adapter_obj_t *adapter, mp_obj_t *attribute) {
check_enabled(adapter);
// The handle is the index of this attribute in the attributes list.
uint16_t handle = (uint16_t)adapter->attributes->len;
mp_obj_list_append(adapter->attributes, attribute);
if (mp_obj_is_type(attribute, &bleio_service_type)) {
adapter->last_added_service_handle = handle;
}
if (mp_obj_is_type(attribute, &bleio_characteristic_type)) {
adapter->last_added_characteristic_handle = handle;
}
return handle;
}
mp_obj_t *bleio_adapter_get_attribute(bleio_adapter_obj_t *adapter, uint16_t handle) {
check_enabled(adapter);
if (handle == 0 || handle >= adapter->attributes->len) {
return mp_const_none;
}
return adapter->attributes->items[handle];
}
uint16_t bleio_adapter_max_attribute_handle(bleio_adapter_obj_t *adapter) {
check_enabled(adapter);
return adapter->attributes->len - 1;
}
void bleio_adapter_gc_collect(bleio_adapter_obj_t *adapter) {
gc_collect_root((void **)adapter, sizeof(bleio_adapter_obj_t) / sizeof(size_t));
gc_collect_root((void **)bleio_connections, sizeof(bleio_connections) / sizeof(size_t));
}
void bleio_adapter_reset(bleio_adapter_obj_t *adapter) {
if (!common_hal_bleio_adapter_get_enabled(adapter)) {
return;
}
// Adapter will be reset.
common_hal_bleio_adapter_set_enabled(adapter, false);
adapter->connection_objs = NULL;
for (size_t i = 0; i < BLEIO_TOTAL_CONNECTION_COUNT; i++) {
bleio_connection_internal_t *connection = &bleio_connections[i];
// Disconnect all connections with Python state cleanly. Keep any supervisor-only connections.
if (connection->connection_obj != mp_const_none &&
connection->conn_handle != BLE_CONN_HANDLE_INVALID) {
common_hal_bleio_connection_disconnect(connection);
}
connection->connection_obj = mp_const_none;
}
}
void bleio_adapter_background(bleio_adapter_obj_t *adapter) {
if (!common_hal_bleio_adapter_get_enabled(adapter)) {
return;
}
if (adapter->advertising_timeout_msecs > 0 &&
supervisor_ticks_ms64() - adapter->advertising_start_ticks > adapter->advertising_timeout_msecs) {
adapter->advertising_timeout_msecs = 0;
common_hal_bleio_adapter_stop_advertising(adapter);
}
hci_result_t result = hci_poll_for_incoming_pkt();
if (result != HCI_OK) {
mp_printf(&mp_plat_print, "bad hci_poll_for_incoming_pkt() result in background: %d\n", result);
}
}

99
devices/ble_hci/common-hal/_bleio/Adapter.h Normal file
View File

@ -0,0 +1,99 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2018 Dan Halbert for Adafruit Industries
* Copyright (c) 2018 Artur Pacholec
* Copyright (c) 2016 Glenn Ruben Bakke
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#ifndef MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_ADAPTER_H
#define MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_ADAPTER_H
#include "py/obj.h"
#include "py/objtuple.h"
#include "shared-bindings/_bleio/Characteristic.h"
#include "shared-bindings/_bleio/Connection.h"
#include "shared-bindings/_bleio/ScanResults.h"
#include "shared-bindings/busio/UART.h"
#include "shared-bindings/digitalio/DigitalInOut.h"
#ifndef BLEIO_TOTAL_CONNECTION_COUNT
#define BLEIO_TOTAL_CONNECTION_COUNT 5
#endif
extern bleio_connection_internal_t bleio_connections[BLEIO_TOTAL_CONNECTION_COUNT];
typedef struct _bleio_adapter_obj_t {
mp_obj_base_t base;
bleio_scanresults_obj_t *scan_results;
mp_obj_t name;
mp_obj_tuple_t *connection_objs;
busio_uart_obj_t *hci_uart;
digitalio_digitalinout_obj_t *rts_digitalinout;
digitalio_digitalinout_obj_t *cts_digitalinout;
bool allocated; // True when in use.
bool now_advertising;
bool extended_advertising;
bool circuitpython_advertising;
bool enabled;
// HCI adapter version info.
uint8_t hci_version;
uint8_t lmp_version;
uint16_t hci_revision;
uint16_t manufacturer;
uint16_t lmp_subversion;
// Used to monitor advertising timeout for legacy avertising.
uint64_t advertising_start_ticks;
uint64_t advertising_timeout_msecs; // If zero, do not check.
// Generic services characteristics.
bleio_characteristic_obj_t *device_name_characteristic;
bleio_characteristic_obj_t *appearance_characteristic;
bleio_characteristic_obj_t *service_changed_characteristic;
uint16_t max_acl_buffer_len;
uint16_t max_acl_num_buffers;
uint16_t max_adv_data_len;
uint8_t features[8]; // Supported BLE features.
// All the local attributes for this device. The index into the list
// corresponds to the handle.
mp_obj_list_t *attributes;
// Handle for last added service. Characteristics can only be added immediately after
// the service they belong to. This vets that.
uint16_t last_added_service_handle;
uint16_t last_added_characteristic_handle;
} bleio_adapter_obj_t;
uint16_t bleio_adapter_add_attribute(bleio_adapter_obj_t *adapter, mp_obj_t *attribute);
void bleio_adapter_advertising_was_stopped(bleio_adapter_obj_t *self);
mp_obj_t *bleio_adapter_get_attribute(bleio_adapter_obj_t *adapter, uint16_t handle);
uint16_t bleio_adapter_max_attribute_handle(bleio_adapter_obj_t *adapter);
void bleio_adapter_background(bleio_adapter_obj_t *adapter);
void bleio_adapter_gc_collect(bleio_adapter_obj_t *adapter);
void bleio_adapter_reset(bleio_adapter_obj_t *adapter);
#endif // MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_ADAPTER_H

49
devices/ble_hci/common-hal/_bleio/Attribute.c Normal file
View File

@ -0,0 +1,49 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2019 Dan Halbert for Adafruit Industries
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#include "py/runtime.h"
#include "shared-bindings/_bleio/Attribute.h"
#include "shared-bindings/_bleio/Characteristic.h"
#include "shared-bindings/_bleio/Descriptor.h"
#include "shared-bindings/_bleio/Service.h"
bleio_uuid_obj_t *bleio_attribute_get_uuid(mp_obj_t *attribute) {
if (mp_obj_is_type(attribute, &bleio_characteristic_type)) {
bleio_characteristic_obj_t *characteristic = MP_OBJ_TO_PTR(attribute);
return characteristic->uuid;
}
if (mp_obj_is_type(attribute, &bleio_descriptor_type)) {
bleio_descriptor_obj_t *descriptor = MP_OBJ_TO_PTR(attribute);
return descriptor->uuid;
}
if (mp_obj_is_type(attribute, &bleio_service_type)) {
bleio_service_obj_t *service = MP_OBJ_TO_PTR(attribute);
return service->uuid;
}
mp_raise_RuntimeError(translate("Invalid BLE attribute"));
}

35
devices/ble_hci/common-hal/_bleio/Attribute.h Normal file
View File

@ -0,0 +1,35 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2020 Dan Halbert for Adafruit Industries
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#ifndef MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_ATTRIBUTE_H
#define MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_ATTRIBUTE_H
#include "shared-module/_bleio/Attribute.h"
#include "shared-bindings/_bleio/UUID.h"
bleio_uuid_obj_t *bleio_attribute_get_uuid(mp_obj_t *attribute);
#endif // MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_ATTRIBUTE_H

232
devices/ble_hci/common-hal/_bleio/Characteristic.c Normal file
View File

@ -0,0 +1,232 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) Dan Halbert for Adafruit Industries
* Copyright (c) 2018 Artur Pacholec
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#include "py/runtime.h"
#include "shared-bindings/_bleio/__init__.h"
#include "shared-bindings/_bleio/Characteristic.h"
#include "shared-bindings/_bleio/CharacteristicBuffer.h"
#include "shared-bindings/_bleio/Descriptor.h"
#include "shared-bindings/_bleio/PacketBuffer.h"
#include "shared-bindings/_bleio/Service.h"
#include "common-hal/_bleio/Adapter.h"
#include "common-hal/_bleio/att.h"
#define CCCD_NOTIFY 0x1
#define CCCD_INDICATE 0x2
void common_hal_bleio_characteristic_construct(bleio_characteristic_obj_t *self, bleio_service_obj_t *service, uint16_t handle, bleio_uuid_obj_t *uuid, bleio_characteristic_properties_t props, bleio_attribute_security_mode_t read_perm, bleio_attribute_security_mode_t write_perm, mp_int_t max_length, bool fixed_length, mp_buffer_info_t *initial_value_bufinfo, const char *user_description) {
self->service = service;
self->uuid = uuid;
self->decl_handle = BLE_GATT_HANDLE_INVALID;
self->handle = BLE_GATT_HANDLE_INVALID;
self->props = props;
self->read_perm = read_perm;
self->write_perm = write_perm;
self->descriptor_list = mp_obj_new_list(0, NULL);
self->observer = mp_const_none;
self->user_desc = NULL;
self->cccd = NULL;
self->sccd = NULL;
self->value = mp_obj_new_bytes(initial_value_bufinfo->buf, initial_value_bufinfo->len);
const mp_int_t max_length_max = 512;
if (max_length < 0 || max_length > max_length_max) {
mp_raise_ValueError(translate("max_length must be <= 512"));
}
self->max_length = max_length;
self->fixed_length = fixed_length;
if (service->is_remote) {
self->handle = handle;
} else {
common_hal_bleio_service_add_characteristic(self->service, self, initial_value_bufinfo, user_description);
}
}
mp_obj_tuple_t *common_hal_bleio_characteristic_get_descriptors(bleio_characteristic_obj_t *self) {
return mp_obj_new_tuple(self->descriptor_list->len, self->descriptor_list->items);
}
bleio_service_obj_t *common_hal_bleio_characteristic_get_service(bleio_characteristic_obj_t *self) {
return self->service;
}
size_t common_hal_bleio_characteristic_get_max_length(bleio_characteristic_obj_t *self) {
return self->max_length;
}
size_t common_hal_bleio_characteristic_get_value(bleio_characteristic_obj_t *self, uint8_t *buf, size_t len) {
// Do GATT operations only if this characteristic has been added to a registered service.
if (self->handle != BLE_GATT_HANDLE_INVALID) {
// FIX uint16_t conn_handle = bleio_connection_get_conn_handle(self->service->connection);
if (common_hal_bleio_service_get_is_remote(self->service)) {
// FIX read remote chars
// uint8_t rsp[MAX(len, 512)];
// FIX improve att_read_req to write into our requested buffer.
// return att_read_req(conn_handle, self->handle, rsp);
return 0; // FIX
} else {
mp_buffer_info_t bufinfo;
if (!mp_get_buffer(self->value, &bufinfo, MP_BUFFER_READ)) {
return 0;
}
const size_t actual_length = MIN(len, bufinfo.len);
memcpy(buf, bufinfo.buf, actual_length);
return actual_length;
}
}
return 0;
}
void common_hal_bleio_characteristic_set_value(bleio_characteristic_obj_t *self, mp_buffer_info_t *bufinfo) {
if (self->fixed_length && bufinfo->len != self->max_length) {
mp_raise_ValueError(translate("Value length != required fixed length"));
}
if (bufinfo->len > self->max_length) {
mp_raise_ValueError(translate("Value length > max_length"));
}
// Do GATT operations only if this characteristic has been added to a registered service.
if (self->handle != BLE_GATT_HANDLE_INVALID) {
if (common_hal_bleio_service_get_is_remote(self->service)) {
// FIX uint16_t conn_handle = bleio_connection_get_conn_handle(self->service->connection);
if (self->props & CHAR_PROP_WRITE) {
// FIX writing remote chars
// uint8_t rsp[sizeof(bt_att_error_rsp)];
// att_write_req(conn_handle, self->handle, bufinfo->buf, bufinfo->len, rsp);
} else if (self->props & CHAR_PROP_WRITE_NO_RESPONSE) {
// att_write_cmd(conn_handle, self->handle, bufinfo->buff, bufinfo->len);
} else {
mp_raise_bleio_BluetoothError(translate("Characteristic not writable"));
}
} else {
// Always write the value locally even if no connections are active.
bleio_characteristic_set_local_value(self, bufinfo);
// Notify or indicate all active connections.
uint16_t cccd_value = 0;
mp_buffer_info_t cccd_bufinfo = {
.buf = &cccd_value,
.len = sizeof(cccd_value),
};
const bool notify = self->props & CHAR_PROP_NOTIFY;
const bool indicate = self->props & CHAR_PROP_INDICATE;
// Read the CCCD value, if there is one.
if ((notify | indicate) && self->cccd != NULL) {
common_hal_bleio_descriptor_get_value(self->cccd, cccd_bufinfo.buf, cccd_bufinfo.len);
}
// It's possible that both notify and indicate are set.
if (notify && (cccd_value & CCCD_NOTIFY)) {
att_notify(self->handle, bufinfo->buf, MIN(bufinfo->len, self->max_length));
}
if (indicate && (cccd_value & CCCD_INDICATE)) {
att_indicate(self->handle, bufinfo->buf, MIN(bufinfo->len, self->max_length));
}
}
}
}
bleio_uuid_obj_t *common_hal_bleio_characteristic_get_uuid(bleio_characteristic_obj_t *self) {
return self->uuid;
}
bleio_characteristic_properties_t common_hal_bleio_characteristic_get_properties(bleio_characteristic_obj_t *self) {
return self->props;
}
void common_hal_bleio_characteristic_add_descriptor(bleio_characteristic_obj_t *self, bleio_descriptor_obj_t *descriptor) {
if (self->handle != common_hal_bleio_adapter_obj.last_added_characteristic_handle) {
mp_raise_bleio_BluetoothError(
translate("Descriptor can only be added to most recently added characteristic"));
}
descriptor->handle = bleio_adapter_add_attribute(&common_hal_bleio_adapter_obj, MP_OBJ_TO_PTR(descriptor));
// Include this descriptor in the service handle's range.
self->service->end_handle = descriptor->handle;
mp_obj_list_append(MP_OBJ_FROM_PTR(self->descriptor_list),
MP_OBJ_FROM_PTR(descriptor));
}
void common_hal_bleio_characteristic_set_cccd(bleio_characteristic_obj_t *self, bool notify, bool indicate) {
if (self->cccd == NULL) {
mp_raise_bleio_BluetoothError(translate("No CCCD for this Characteristic"));
}
if (!common_hal_bleio_service_get_is_remote(self->service)) {
mp_raise_bleio_RoleError(translate("Can't set CCCD on local Characteristic"));
}
const uint16_t conn_handle = bleio_connection_get_conn_handle(self->service->connection);
common_hal_bleio_check_connected(conn_handle);
uint16_t cccd_value =
(notify ? CCCD_NOTIFY : 0) |
(indicate ? CCCD_INDICATE : 0);
// FIX do remote
(void)cccd_value;
// uint8_t rsp[sizeof(bt_att_error_rsp)];
// if (att_write_req(conn_handle, self->cccd->handle, &cccd_value, sizeof(cccd_value)) == 0) {
// mp_raise_bleio_BluetoothError(translate("Could not write CCCD"));
// }
}
bool bleio_characteristic_set_local_value(bleio_characteristic_obj_t *self, mp_buffer_info_t *bufinfo) {
if (self->fixed_length && bufinfo->len != self->max_length) {
return false;
}
if (bufinfo->len > self->max_length) {
return false;
}
self->value = mp_obj_new_bytes(bufinfo->buf, bufinfo->len);
if (mp_obj_is_type(self->observer, &bleio_characteristic_buffer_type)) {
bleio_characteristic_buffer_update(MP_OBJ_FROM_PTR(self->observer), bufinfo);
} else if (mp_obj_is_type(self->observer, &bleio_packet_buffer_type)) {
bleio_packet_buffer_update(MP_OBJ_FROM_PTR(self->observer), bufinfo);
} else {
return false;
}
return true;
}
void bleio_characteristic_set_observer(bleio_characteristic_obj_t *self, mp_obj_t observer) {
self->observer = observer;
}
void bleio_characteristic_clear_observer(bleio_characteristic_obj_t *self) {
self->observer = mp_const_none;
}

63
devices/ble_hci/common-hal/_bleio/Characteristic.h Normal file
View File

@ -0,0 +1,63 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2019 Dan Halbert for Adafruit Industries
* Copyright (c) 2018 Artur Pacholec
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#ifndef MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_CHARACTERISTIC_H
#define MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_CHARACTERISTIC_H
#include "shared-bindings/_bleio/Attribute.h"
#include "common-hal/_bleio/Descriptor.h"
#include "shared-module/_bleio/Characteristic.h"
#include "common-hal/_bleio/Service.h"
#include "common-hal/_bleio/UUID.h"
typedef struct _bleio_characteristic_obj {
mp_obj_base_t base;
// Will be MP_OBJ_NULL before being assigned to a Service.
bleio_service_obj_t *service;
bleio_uuid_obj_t *uuid;
mp_obj_t value;
mp_obj_t observer;
mp_obj_list_t *descriptor_list;
uint16_t max_length;
bool fixed_length;
uint16_t decl_handle;
uint16_t handle; // Should be decl_handle+1.
bleio_characteristic_properties_t props;
bleio_attribute_security_mode_t read_perm;
bleio_attribute_security_mode_t write_perm;
bleio_descriptor_obj_t *descriptor_linked_list;
bleio_descriptor_obj_t *user_desc;
bleio_descriptor_obj_t *cccd;
bleio_descriptor_obj_t *sccd;
} bleio_characteristic_obj_t;
bool bleio_characteristic_set_local_value(bleio_characteristic_obj_t *self, mp_buffer_info_t *bufinfo);
void bleio_characteristic_set_observer(bleio_characteristic_obj_t *self, mp_obj_t observer);
void bleio_characteristic_clear_observer(bleio_characteristic_obj_t *self);
#endif // MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_CHARACTERISTIC_H

104
devices/ble_hci/common-hal/_bleio/CharacteristicBuffer.c Normal file
View File

@ -0,0 +1,104 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2019 Dan Halbert for Adafruit Industries
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#include <string.h>
#include <stdio.h>
#include "lib/utils/interrupt_char.h"
#include "py/runtime.h"
#include "py/stream.h"
#include "shared-bindings/_bleio/__init__.h"
#include "shared-bindings/_bleio/Connection.h"
#include "supervisor/shared/tick.h"
#include "common-hal/_bleio/CharacteristicBuffer.h"
// Push all the data onto the ring buffer. When the buffer is full, new bytes will be dropped.
STATIC void write_to_ringbuf(bleio_characteristic_buffer_obj_t *self, uint8_t *data, uint16_t len) {
ringbuf_put_n(&self->ringbuf, data, len);
}
void bleio_characteristic_buffer_update(bleio_characteristic_buffer_obj_t *self, mp_buffer_info_t *bufinfo) {
write_to_ringbuf(self, bufinfo->buf, bufinfo->len);
}
// Assumes that timeout and buffer_size have been validated before call.
void common_hal_bleio_characteristic_buffer_construct(bleio_characteristic_buffer_obj_t *self,
bleio_characteristic_obj_t *characteristic,
mp_float_t timeout,
size_t buffer_size) {
self->characteristic = characteristic;
self->timeout_ms = timeout * 1000;
// This is a macro.
// true means long-lived, so it won't be moved.
ringbuf_alloc(&self->ringbuf, buffer_size, true);
bleio_characteristic_set_observer(characteristic, self);
}
uint32_t common_hal_bleio_characteristic_buffer_read(bleio_characteristic_buffer_obj_t *self, uint8_t *data, size_t len, int *errcode) {
uint64_t start_ticks = supervisor_ticks_ms64();
// Wait for all bytes received or timeout
while ((ringbuf_num_filled(&self->ringbuf) < len) && (supervisor_ticks_ms64() - start_ticks < self->timeout_ms)) {
RUN_BACKGROUND_TASKS;
// Allow user to break out of a timeout with a KeyboardInterrupt.
if (mp_hal_is_interrupted()) {
return 0;
}
}
uint32_t num_bytes_read = ringbuf_get_n(&self->ringbuf, data, len);
return num_bytes_read;
}
uint32_t common_hal_bleio_characteristic_buffer_rx_characters_available(bleio_characteristic_buffer_obj_t *self) {
uint16_t count = ringbuf_num_filled(&self->ringbuf);
return count;
}
void common_hal_bleio_characteristic_buffer_clear_rx_buffer(bleio_characteristic_buffer_obj_t *self) {
ringbuf_clear(&self->ringbuf);
}
bool common_hal_bleio_characteristic_buffer_deinited(bleio_characteristic_buffer_obj_t *self) {
return self->characteristic == NULL;
}
void common_hal_bleio_characteristic_buffer_deinit(bleio_characteristic_buffer_obj_t *self) {
if (!common_hal_bleio_characteristic_buffer_deinited(self)) {
bleio_characteristic_clear_observer(self->characteristic);
}
}
bool common_hal_bleio_characteristic_buffer_connected(bleio_characteristic_buffer_obj_t *self) {
return self->characteristic != NULL &&
self->characteristic->service != NULL &&
(!self->characteristic->service->is_remote ||
(self->characteristic->service->connection != MP_OBJ_NULL &&
common_hal_bleio_connection_get_connected(self->characteristic->service->connection)));
}

43
devices/ble_hci/common-hal/_bleio/CharacteristicBuffer.h Normal file
View File

@ -0,0 +1,43 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2019 Dan Halbert for Adafruit Industries
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#ifndef MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_CHARACTERISTICBUFFER_H
#define MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_CHARACTERISTICBUFFER_H
#include "py/ringbuf.h"
#include "shared-bindings/_bleio/Characteristic.h"
typedef struct {
mp_obj_base_t base;
bleio_characteristic_obj_t *characteristic;
uint32_t timeout_ms;
// Ring buffer storing consecutive incoming values.
ringbuf_t ringbuf;
} bleio_characteristic_buffer_obj_t;
void bleio_characteristic_buffer_update(bleio_characteristic_buffer_obj_t *self, mp_buffer_info_t *bufinfo);
#endif // MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_CHARACTERISTICBUFFER_H

772
devices/ble_hci/common-hal/_bleio/Connection.c Normal file
View File

@ -0,0 +1,772 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2018 Dan Halbert for Adafruit Industries
* Copyright (c) 2018 Artur Pacholec
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#include "shared-bindings/_bleio/Connection.h"
#include "att.h"
#include <string.h>
#include <stdio.h>
#include "lib/utils/interrupt_char.h"
#include "py/gc.h"
#include "py/objlist.h"
#include "py/objstr.h"
#include "py/qstr.h"
#include "py/runtime.h"
#include "shared-bindings/_bleio/__init__.h"
#include "shared-bindings/_bleio/Adapter.h"
#include "shared-bindings/_bleio/Attribute.h"
#include "shared-bindings/_bleio/Characteristic.h"
#include "shared-bindings/_bleio/Service.h"
#include "shared-bindings/_bleio/UUID.h"
#include "supervisor/shared/tick.h"
#define BLE_ADV_LENGTH_FIELD_SIZE 1
#define BLE_ADV_AD_TYPE_FIELD_SIZE 1
#define BLE_AD_TYPE_FLAGS_DATA_SIZE 1
// static const ble_gap_sec_params_t pairing_sec_params = {
// .bond = 1,
// .mitm = 0,
// .lesc = 0,
// .keypress = 0,
// .oob = 0,
// .io_caps = BLE_GAP_IO_CAPS_NONE,
// .min_key_size = 7,
// .max_key_size = 16,
// .kdist_own = { .enc = 1, .id = 1},
// .kdist_peer = { .enc = 1, .id = 1},
// };
#define CONNECTION_DEBUG (1)
#if CONNECTION_DEBUG
#define CONNECTION_DEBUG_PRINTF(...) printf(__VA_ARGS__)
#else
#define CONNECTION_DEBUG_PRINTF(...)
#endif
static volatile bool m_discovery_in_process;
static volatile bool m_discovery_successful;
// FIX static bleio_service_obj_t *m_char_discovery_service;
// FIX static bleio_characteristic_obj_t *m_desc_discovery_characteristic;
// bool connection_on_ble_evt(ble_evt_t *ble_evt, void *self_in) {
// bleio_connection_internal_t *self = (bleio_connection_internal_t*)self_in;
// if (BLE_GAP_EVT_BASE <= ble_evt->header.evt_id && ble_evt->header.evt_id <= BLE_GAP_EVT_LAST &&
// ble_evt->evt.gap_evt.conn_handle != self->conn_handle) {
// return false;
// }
// if (BLE_GATTS_EVT_BASE <= ble_evt->header.evt_id && ble_evt->header.evt_id <= BLE_GATTS_EVT_LAST &&
// ble_evt->evt.gatts_evt.conn_handle != self->conn_handle) {
// return false;
// }
// switch (ble_evt->header.evt_id) {
// case BLE_GAP_EVT_DISCONNECTED:
// // Adapter.c does the work for this event.
// break;
// case BLE_GAP_EVT_PHY_UPDATE_REQUEST: {
// ble_gap_phys_t const phys = {
// .rx_phys = BLE_GAP_PHY_AUTO,
// .tx_phys = BLE_GAP_PHY_AUTO,
// };
// sd_ble_gap_phy_update(ble_evt->evt.gap_evt.conn_handle, &phys);
// break;
// }
// case BLE_GAP_EVT_PHY_UPDATE: { // 0x22
// break;
// }
// case BLE_GAP_EVT_DATA_LENGTH_UPDATE_REQUEST:
// // SoftDevice will respond to a length update request.
// sd_ble_gap_data_length_update(self->conn_handle, NULL, NULL);
// break;
// case BLE_GAP_EVT_DATA_LENGTH_UPDATE: { // 0x24
// break;
// }
// case BLE_GATTS_EVT_EXCHANGE_MTU_REQUEST: {
// ble_gatts_evt_exchange_mtu_request_t *request =
// &ble_evt->evt.gatts_evt.params.exchange_mtu_request;
// uint16_t new_mtu = BLE_GATTS_VAR_ATTR_LEN_MAX;
// if (request->client_rx_mtu < new_mtu) {
// new_mtu = request->client_rx_mtu;
// }
// if (new_mtu < BLE_GATT_ATT_MTU_DEFAULT) {
// new_mtu = BLE_GATT_ATT_MTU_DEFAULT;
// }
// if (self->mtu > 0) {
// new_mtu = self->mtu;
// }
// self->mtu = new_mtu;
// sd_ble_gatts_exchange_mtu_reply(self->conn_handle, new_mtu);
// break;
// }
// case BLE_GATTC_EVT_EXCHANGE_MTU_RSP: {
// ble_gattc_evt_exchange_mtu_rsp_t *response =
// &ble_evt->evt.gattc_evt.params.exchange_mtu_rsp;
// self->mtu = response->server_rx_mtu;
// break;
// }
// case BLE_GATTS_EVT_WRITE:
// // A client wrote a value.
// // If we are bonded and it's a CCCD (UUID 0x2902), store the CCCD value.
// if (self->conn_handle != BLE_CONN_HANDLE_INVALID &&
// self->pair_status == PAIR_PAIRED &&
// ble_evt->evt.gatts_evt.params.write.uuid.type == BLE_UUID_TYPE_BLE &&
// ble_evt->evt.gatts_evt.params.write.uuid.uuid == 0x2902) {
// //
// // Save sys_attr data (CCCD state) in bonding area at
// // next opportunity, but also remember time of this
// // request, so we can consolidate closely-spaced requests.
// self->do_bond_cccds = true;
// self->do_bond_cccds_request_time = supervisor_ticks_ms64();
// }
// // Return false so other handlers get this event as well.
// return false;
// case BLE_GATTS_EVT_SYS_ATTR_MISSING:
// sd_ble_gatts_sys_attr_set(self->conn_handle, NULL, 0, 0);
// break;
// #if CIRCUITPY_VERBOSE_BLE
// // Use read authorization to snoop on all reads when doing verbose debugging.
// case BLE_GATTS_EVT_RW_AUTHORIZE_REQUEST: {
// ble_gatts_evt_rw_authorize_request_t *request =
// &ble_evt->evt.gatts_evt.params.authorize_request;
// mp_printf(&mp_plat_print, "Read %x offset %d ", request->request.read.handle, request->request.read.offset);
// uint8_t value_bytes[22];
// ble_gatts_value_t value;
// value.offset = request->request.read.offset;
// value.len = 22;
// value.p_value = value_bytes;
// sd_ble_gatts_value_get(self->conn_handle, request->request.read.handle, &value);
// size_t len = value.len;
// if (len > 22) {
// len = 22;
// }
// for (uint8_t i = 0; i < len; i++) {
// mp_printf(&mp_plat_print, " %02x", value_bytes[i]);
// }
// mp_printf(&mp_plat_print, "\n");
// ble_gatts_rw_authorize_reply_params_t reply;
// reply.type = request->type;
// reply.params.read.gatt_status = BLE_GATT_STATUS_SUCCESS;
// reply.params.read.update = false;
// reply.params.read.offset = request->request.read.offset;
// sd_ble_gatts_rw_authorize_reply(self->conn_handle, &reply);
// break;
// }
// #endif
// case BLE_GATTS_EVT_HVN_TX_COMPLETE: // Capture this for now. 0x55
// break;
// case BLE_GAP_EVT_CONN_PARAM_UPDATE_REQUEST: {
// self->conn_params_updating = true;
// ble_gap_evt_conn_param_update_request_t *request =
// &ble_evt->evt.gap_evt.params.conn_param_update_request;
// sd_ble_gap_conn_param_update(self->conn_handle, &request->conn_params);
// break;
// }
// case BLE_GAP_EVT_CONN_PARAM_UPDATE: { // 0x12
// ble_gap_evt_conn_param_update_t *result =
// &ble_evt->evt.gap_evt.params.conn_param_update;
// #if CIRCUITPY_VERBOSE_BLE
// ble_gap_conn_params_t *cp = &ble_evt->evt.gap_evt.params.conn_param_update.conn_params;
// mp_printf(&mp_plat_print, "conn params updated: min_ci %d max_ci %d s_l %d sup_timeout %d\n", cp->min_conn_interval, cp->max_conn_interval, cp->slave_latency, cp->conn_sup_timeout);
// #endif
// memcpy(&self->conn_params, &result->conn_params, sizeof(ble_gap_conn_params_t));
// self->conn_params_updating = false;
// break;
// }
// case BLE_GAP_EVT_SEC_PARAMS_REQUEST: {
// // First time pairing.
// // 1. Either we or peer initiate the process
// // 2. Peer asks for security parameters using BLE_GAP_EVT_SEC_PARAMS_REQUEST.
// // 3. Pair Key exchange ("just works" implemented now; TODO: out-of-band key pairing)
// // 4. Connection is secured: BLE_GAP_EVT_CONN_SEC_UPDATE
// // 5. Long-term Keys exchanged: BLE_GAP_EVT_AUTH_STATUS
// bonding_clear_keys(&self->bonding_keys);
// self->ediv = EDIV_INVALID;
// ble_gap_sec_keyset_t keyset = {
// .keys_own = {
// .p_enc_key = &self->bonding_keys.own_enc,
// .p_id_key = NULL,
// .p_sign_key = NULL,
// .p_pk = NULL
// },
// .keys_peer = {
// .p_enc_key = &self->bonding_keys.peer_enc,
// .p_id_key = &self->bonding_keys.peer_id,
// .p_sign_key = NULL,
// .p_pk = NULL
// }
// };
// sd_ble_gap_sec_params_reply(self->conn_handle, BLE_GAP_SEC_STATUS_SUCCESS,
// self->is_central ? NULL : &pairing_sec_params,
// &keyset);
// break;
// }
// case BLE_GAP_EVT_LESC_DHKEY_REQUEST:
// // TODO for LESC pairing:
// // sd_ble_gap_lesc_dhkey_reply(...);
// break;
// case BLE_GAP_EVT_AUTH_STATUS: { // 0x19
// // Key exchange completed.
// ble_gap_evt_auth_status_t* status = &ble_evt->evt.gap_evt.params.auth_status;
// self->sec_status = status->auth_status;
// if (status->auth_status == BLE_GAP_SEC_STATUS_SUCCESS) {
// self->ediv = self->bonding_keys.own_enc.master_id.ediv;
// self->pair_status = PAIR_PAIRED;
// // Save keys in bonding area at next opportunity.
// self->do_bond_keys = true;
// } else {
// // Inform busy-waiter pairing has failed.
// self->pair_status = PAIR_NOT_PAIRED;
// }
// break;
// }
// case BLE_GAP_EVT_SEC_INFO_REQUEST: { // 0x14
// // Peer asks for the stored keys.
// // - load key and return if bonded previously.
// // - Else return NULL --> Initiate key exchange
// ble_gap_evt_sec_info_request_t* sec_info_request = &ble_evt->evt.gap_evt.params.sec_info_request;
// (void) sec_info_request;
// if ( bonding_load_keys(self->is_central, sec_info_request->master_id.ediv, &self->bonding_keys) ) {
// sd_ble_gap_sec_info_reply(
// self->conn_handle,
// &self->bonding_keys.own_enc.enc_info,
// &self->bonding_keys.peer_id.id_info,
// NULL);
// self->ediv = self->bonding_keys.own_enc.master_id.ediv;
// } else {
// // We don't have stored keys. Ask for keys.
// sd_ble_gap_sec_info_reply(self->conn_handle, NULL, NULL, NULL);
// }
// break;
// }
// case BLE_GAP_EVT_CONN_SEC_UPDATE: { // 0x1a
// // We get this both on first-time pairing and on subsequent pairings using stored keys.
// ble_gap_conn_sec_t* conn_sec = &ble_evt->evt.gap_evt.params.conn_sec_update.conn_sec;
// if (conn_sec->sec_mode.sm <= 1 && conn_sec->sec_mode.lv <= 1) {
// // Security setup did not succeed:
// // mode 0, level 0 means no access
// // mode 1, level 1 means open link
// // mode >=1 and/or level >=1 means encryption is set up
// self->pair_status = PAIR_NOT_PAIRED;
// } else {
// if (bonding_load_cccd_info(self->is_central, self->conn_handle, self->ediv)) {
// // Did an sd_ble_gatts_sys_attr_set() with the stored sys_attr values.
// } else {
// // No matching bonding found, so use fresh system attributes.
// sd_ble_gatts_sys_attr_set(self->conn_handle, NULL, 0, 0);
// }
// self->pair_status = PAIR_PAIRED;
// }
// break;
// }
// default:
// return false;
// }
// return true;
// }
void bleio_connection_clear(bleio_connection_internal_t *self) {
mp_obj_list_clear(MP_OBJ_FROM_PTR(self->remote_service_list));
self->conn_handle = BLE_CONN_HANDLE_INVALID;
self->pair_status = PAIR_NOT_PAIRED;
self->is_central = false;
// FIX bonding_clear_keys(&self->bonding_keys);
}
bool common_hal_bleio_connection_get_paired(bleio_connection_obj_t *self) {
if (self->connection == NULL) {
return false;
}
return self->connection->pair_status == PAIR_PAIRED;
}
bool common_hal_bleio_connection_get_connected(bleio_connection_obj_t *self) {
if (self->connection == NULL) {
return false;
}
return self->connection->conn_handle != BLE_CONN_HANDLE_INVALID;
}
void common_hal_bleio_connection_disconnect(bleio_connection_internal_t *self) {
hci_disconnect(self->conn_handle);
}
void common_hal_bleio_connection_pair(bleio_connection_internal_t *self, bool bond) {
self->pair_status = PAIR_WAITING;
// FIX check_nrf_error(sd_ble_gap_authenticate(self->conn_handle, &pairing_sec_params));
while (self->pair_status == PAIR_WAITING && !mp_hal_is_interrupted()) {
RUN_BACKGROUND_TASKS;
}
if (mp_hal_is_interrupted()) {
return;
}
// FIX check_sec_status(self->sec_status);
}
mp_float_t common_hal_bleio_connection_get_connection_interval(bleio_connection_internal_t *self) {
while (self->conn_params_updating && !mp_hal_is_interrupted()) {
RUN_BACKGROUND_TASKS;
}
// FIX return 1.25f * self->conn_params.min_conn_interval;
return 0.0f;
}
// Return the current negotiated MTU length, minus overhead.
mp_int_t common_hal_bleio_connection_get_max_packet_length(bleio_connection_internal_t *self) {
return (self->mtu == 0 ? BT_ATT_DEFAULT_LE_MTU : self->mtu) - 3;
}
void common_hal_bleio_connection_set_connection_interval(bleio_connection_internal_t *self, mp_float_t new_interval) {
// self->conn_params_updating = true;
// uint16_t interval = new_interval / 1.25f;
// self->conn_params.min_conn_interval = interval;
// self->conn_params.max_conn_interval = interval;
// uint32_t status = NRF_ERROR_BUSY;
// while (status == NRF_ERROR_BUSY) {
// status = sd_ble_gap_conn_param_update(self->conn_handle, &self->conn_params);
// RUN_BACKGROUND_TASKS;
// }
// check_nrf_error(status);
}
// service_uuid may be NULL, to discover all services.
// STATIC bool discover_next_services(bleio_connection_internal_t* connection, uint16_t start_handle, ble_uuid_t *service_uuid) {
// m_discovery_successful = false;
// m_discovery_in_process = true;
// uint32_t nrf_err = NRF_ERROR_BUSY;
// while (nrf_err == NRF_ERROR_BUSY) {
// nrf_err = sd_ble_gattc_primary_services_discover(connection->conn_handle, start_handle, service_uuid);
// }
// check_nrf_error(nrf_err);
// // Wait for a discovery event.
// while (m_discovery_in_process) {
// MICROPY_VM_HOOK_LOOP;
// }
// return m_discovery_successful;
// }
// STATIC bool discover_next_characteristics(bleio_connection_internal_t* connection, bleio_service_obj_t *service, uint16_t start_handle) {
// m_char_discovery_service = service;
// ble_gattc_handle_range_t handle_range;
// handle_range.start_handle = start_handle;
// handle_range.end_handle = service->end_handle;
// m_discovery_successful = false;
// m_discovery_in_process = true;
// uint32_t err_code = sd_ble_gattc_characteristics_discover(connection->conn_handle, &handle_range);
// if (err_code != NRF_SUCCESS) {
// return false;
// }
// // Wait for a discovery event.
// while (m_discovery_in_process) {
// MICROPY_VM_HOOK_LOOP;
// }
// return m_discovery_successful;
// }
// STATIC bool discover_next_descriptors(bleio_connection_internal_t* connection, bleio_characteristic_obj_t *characteristic, uint16_t start_handle, uint16_t end_handle) {
// m_desc_discovery_characteristic = characteristic;
// ble_gattc_handle_range_t handle_range;
// handle_range.start_handle = start_handle;
// handle_range.end_handle = end_handle;
// m_discovery_successful = false;
// m_discovery_in_process = true;
// uint32_t err_code = sd_ble_gattc_descriptors_discover(connection->conn_handle, &handle_range);
// if (err_code != NRF_SUCCESS) {
// return false;
// }
// // Wait for a discovery event.
// while (m_discovery_in_process) {
// MICROPY_VM_HOOK_LOOP;
// }
// return m_discovery_successful;
// }
// STATIC void on_primary_srv_discovery_rsp(ble_gattc_evt_prim_srvc_disc_rsp_t *response, bleio_connection_internal_t* connection) {
// for (size_t i = 0; i < response->count; ++i) {
// ble_gattc_service_t *gattc_service = &response->services[i];
// bleio_service_obj_t *service = m_new_obj(bleio_service_obj_t);
// service->base.type = &bleio_service_type;
// // Initialize several fields at once.
// bleio_service_from_connection(service, bleio_connection_new_from_internal(connection));
// service->is_remote = true;
// service->start_handle = gattc_service->handle_range.start_handle;
// service->end_handle = gattc_service->handle_range.end_handle;
// service->handle = gattc_service->handle_range.start_handle;
// if (gattc_service->uuid.type != BLE_UUID_TYPE_UNKNOWN) {
// // Known service UUID.
// bleio_uuid_obj_t *uuid = m_new_obj(bleio_uuid_obj_t);
// uuid->base.type = &bleio_uuid_type;
// bleio_uuid_construct_from_nrf_ble_uuid(uuid, &gattc_service->uuid);
// service->uuid = uuid;
// } else {
// // The discovery response contained a 128-bit UUID that has not yet been registered with the
// // softdevice via sd_ble_uuid_vs_add(). We need to fetch the 128-bit value and register it.
// // For now, just set the UUID to NULL.
// service->uuid = NULL;
// }
//
// mp_obj_list_append(MP_OBJ_FROM_PTR(connection->remote_service_list),
// MP_OBJ_FROM_PTR(service));
// }
//
// if (response->count > 0) {
// m_discovery_successful = true;
// }
// m_discovery_in_process = false;
// }
// STATIC void on_char_discovery_rsp(ble_gattc_evt_char_disc_rsp_t *response, bleio_connection_internal_t* connection) {
// for (size_t i = 0; i < response->count; ++i) {
// ble_gattc_char_t *gattc_char = &response->chars[i];
// bleio_characteristic_obj_t *characteristic = m_new_obj(bleio_characteristic_obj_t);
// characteristic->base.type = &bleio_characteristic_type;
// bleio_uuid_obj_t *uuid = NULL;
// if (gattc_char->uuid.type != BLE_UUID_TYPE_UNKNOWN) {
// // Known characteristic UUID.
// uuid = m_new_obj(bleio_uuid_obj_t);
// uuid->base.type = &bleio_uuid_type;
// bleio_uuid_construct_from_nrf_ble_uuid(uuid, &gattc_char->uuid);
// } else {
// // The discovery response contained a 128-bit UUID that has not yet been registered with the
// // softdevice via sd_ble_uuid_vs_add(). We need to fetch the 128-bit value and register it.
// // For now, just leave the UUID as NULL.
// }
// bleio_characteristic_properties_t props =
// (gattc_char->char_props.broadcast ? CHAR_PROP_BROADCAST : 0) |
// (gattc_char->char_props.indicate ? CHAR_PROP_INDICATE : 0) |
// (gattc_char->char_props.notify ? CHAR_PROP_NOTIFY : 0) |
// (gattc_char->char_props.read ? CHAR_PROP_READ : 0) |
// (gattc_char->char_props.write ? CHAR_PROP_WRITE : 0) |
// (gattc_char->char_props.write_wo_resp ? CHAR_PROP_WRITE_NO_RESPONSE : 0);
// // Call common_hal_bleio_characteristic_construct() to initalize some fields and set up evt handler.
// common_hal_bleio_characteristic_construct(
// characteristic, m_char_discovery_service, gattc_char->handle_value, uuid,
// props, SECURITY_MODE_OPEN, SECURITY_MODE_OPEN,
// GATT_MAX_DATA_LENGTH, false, // max_length, fixed_length: values may not matter for gattc
// NULL);
// mp_obj_list_append(MP_OBJ_FROM_PTR(m_char_discovery_service->characteristic_list),
// MP_OBJ_FROM_PTR(characteristic));
// }
// if (response->count > 0) {
// m_discovery_successful = true;
// }
// m_discovery_in_process = false;
// }
// STATIC void on_desc_discovery_rsp(ble_gattc_evt_desc_disc_rsp_t *response, bleio_connection_internal_t* connection) {
// for (size_t i = 0; i < response->count; ++i) {
// ble_gattc_desc_t *gattc_desc = &response->descs[i];
// // Remember handles for certain well-known descriptors.
// switch (gattc_desc->uuid.uuid) {
// case BLE_UUID_DESCRIPTOR_CLIENT_CHAR_CONFIG:
// m_desc_discovery_characteristic->cccd_handle = gattc_desc->handle;
// break;
// case BLE_UUID_DESCRIPTOR_SERVER_CHAR_CONFIG:
// m_desc_discovery_characteristic->sccd_handle = gattc_desc->handle;
// break;
// case BLE_UUID_DESCRIPTOR_CHAR_USER_DESC:
// m_desc_discovery_characteristic->user_desc_handle = gattc_desc->handle;
// break;
// default:
// // TODO: sd_ble_gattc_descriptors_discover() can return things that are not descriptors,
// // so ignore those.
// // https://devzone.nordicsemi.com/f/nordic-q-a/49500/sd_ble_gattc_descriptors_discover-is-returning-attributes-that-are-not-descriptors
// break;
// }
// bleio_descriptor_obj_t *descriptor = m_new_obj(bleio_descriptor_obj_t);
// descriptor->base.type = &bleio_descriptor_type;
// bleio_uuid_obj_t *uuid = NULL;
// if (gattc_desc->uuid.type != BLE_UUID_TYPE_UNKNOWN) {
// // Known descriptor UUID.
// uuid = m_new_obj(bleio_uuid_obj_t);
// uuid->base.type = &bleio_uuid_type;
// bleio_uuid_construct_from_nrf_ble_uuid(uuid, &gattc_desc->uuid);
// } else {
// // The discovery response contained a 128-bit UUID that has not yet been registered with the
// // softdevice via sd_ble_uuid_vs_add(). We need to fetch the 128-bit value and register it.
// // For now, just leave the UUID as NULL.
// }
// common_hal_bleio_descriptor_construct(
// descriptor, m_desc_discovery_characteristic, uuid,
// SECURITY_MODE_OPEN, SECURITY_MODE_OPEN,
// GATT_MAX_DATA_LENGTH, false, mp_const_empty_bytes);
// descriptor->handle = gattc_desc->handle;
// mp_obj_list_append(MP_OBJ_FROM_PTR(m_desc_discovery_characteristic->descriptor_list),
// MP_OBJ_FROM_PTR(descriptor));
// }
// if (response->count > 0) {
// m_discovery_successful = true;
// }
// m_discovery_in_process = false;
// }
// STATIC bool discovery_on_ble_evt(ble_evt_t *ble_evt, mp_obj_t payload) {
// bleio_connection_internal_t* connection = MP_OBJ_TO_PTR(payload);
// switch (ble_evt->header.evt_id) {
// case BLE_GAP_EVT_DISCONNECTED:
// m_discovery_successful = false;
// m_discovery_in_process = false;
// break;
// case BLE_GATTC_EVT_PRIM_SRVC_DISC_RSP:
// on_primary_srv_discovery_rsp(&ble_evt->evt.gattc_evt.params.prim_srvc_disc_rsp, connection);
// break;
// case BLE_GATTC_EVT_CHAR_DISC_RSP:
// on_char_discovery_rsp(&ble_evt->evt.gattc_evt.params.char_disc_rsp, connection);
// break;
// case BLE_GATTC_EVT_DESC_DISC_RSP:
// on_desc_discovery_rsp(&ble_evt->evt.gattc_evt.params.desc_disc_rsp, connection);
// break;
// default:
// // CONNECTION_DEBUG_PRINTF(&mp_plat_print, "Unhandled discovery event: 0x%04x\n", ble_evt->header.evt_id);
// return false;
// break;
// }
// return true;
// }
// STATIC void discover_remote_services(bleio_connection_internal_t *self, mp_obj_t service_uuids_whitelist) {
// ble_drv_add_event_handler(discovery_on_ble_evt, self);
// // Start over with an empty list.
// self->remote_service_list = mp_obj_new_list(0, NULL);
// if (service_uuids_whitelist == mp_const_none) {
// // List of service UUID's not given, so discover all available services.
// uint16_t next_service_start_handle = BLE_GATT_HANDLE_START;
// while (discover_next_services(self, next_service_start_handle, MP_OBJ_NULL)) {
// // discover_next_services() appends to remote_services_list.
// // Get the most recently discovered service, and then ask for services
// // whose handles start after the last attribute handle inside that service.
// // There must be at least one if discover_next_services() returned true.
// const bleio_service_obj_t *service =
// self->remote_service_list->items[self->remote_service_list->len - 1];
// next_service_start_handle = service->end_handle + 1;
// }
// } else {
// mp_obj_iter_buf_t iter_buf;
// mp_obj_t iterable = mp_getiter(service_uuids_whitelist, &iter_buf);
// mp_obj_t uuid_obj;
// while ((uuid_obj = mp_iternext(iterable)) != MP_OBJ_STOP_ITERATION) {
// if (!mp_obj_is_type(uuid_obj, &bleio_uuid_type)) {
// mp_raise_TypeError(translate("non-UUID found in service_uuids_whitelist"));
// }
// bleio_uuid_obj_t *uuid = MP_OBJ_TO_PTR(uuid_obj);
// ble_uuid_t nrf_uuid;
// bleio_uuid_convert_to_nrf_ble_uuid(uuid, &nrf_uuid);
// // Service might or might not be discovered; that's ok. Caller has to check
// // Central.remote_services to find out.
// // We only need to call this once for each service to discover.
// discover_next_services(self, BLE_GATT_HANDLE_START, &nrf_uuid);
// }
// }
// for (size_t i = 0; i < self->remote_service_list->len; i++) {
// bleio_service_obj_t *service = MP_OBJ_TO_PTR(self->remote_service_list->items[i]);
// // Skip the service if it had an unknown (unregistered) UUID.
// if (service->uuid == NULL) {
// continue;
// }
// uint16_t next_char_start_handle = service->start_handle;
// // Stop when we go past the end of the range of handles for this service or
// // discovery call returns nothing.
// // discover_next_characteristics() appends to the characteristic_list.
// while (next_char_start_handle <= service->end_handle &&
// discover_next_characteristics(self, service, next_char_start_handle)) {
// // Get the most recently discovered characteristic, and then ask for characteristics
// // whose handles start after the last attribute handle inside that characteristic.
// const bleio_characteristic_obj_t *characteristic =
// MP_OBJ_TO_PTR(service->characteristic_list->items[service->characteristic_list->len - 1]);
// next_char_start_handle = characteristic->handle + 1;
// }
// // Got characteristics for this service. Now discover descriptors for each characteristic.
// size_t char_list_len = service->characteristic_list->len;
// for (size_t char_idx = 0; char_idx < char_list_len; ++char_idx) {
// bleio_characteristic_obj_t *characteristic =
// MP_OBJ_TO_PTR(service->characteristic_list->items[char_idx]);
// const bool last_characteristic = char_idx == char_list_len - 1;
// bleio_characteristic_obj_t *next_characteristic = last_characteristic
// ? NULL
// : MP_OBJ_TO_PTR(service->characteristic_list->items[char_idx + 1]);
// // Skip the characteristic if it had an unknown (unregistered) UUID.
// if (characteristic->uuid == NULL) {
// continue;
// }
// uint16_t next_desc_start_handle = characteristic->handle + 1;
// // Don't run past the end of this service or the beginning of the next characteristic.
// uint16_t next_desc_end_handle = next_characteristic == NULL
// ? service->end_handle
// : next_characteristic->handle - 1;
// // Stop when we go past the end of the range of handles for this service or
// // discovery call returns nothing.
// // discover_next_descriptors() appends to the descriptor_linked_list.
// while (next_desc_start_handle <= service->end_handle &&
// next_desc_start_handle <= next_desc_end_handle &&
// discover_next_descriptors(self, characteristic,
// next_desc_start_handle, next_desc_end_handle)) {
// // Get the most recently discovered descriptor, and then ask for descriptors
// // whose handles start after that descriptor's handle.
// // There must be at least one if discover_next_descriptors() returned true.
// const bleio_descriptor_obj_t *descriptor =
// characteristic->descriptor_list->items[characteristic->descriptor_list->len - 1];
// next_desc_start_handle = descriptor->handle + 1;
// }
// }
// }
// // This event handler is no longer needed.
// ble_drv_remove_event_handler(discovery_on_ble_evt, self);
// }
mp_obj_tuple_t *common_hal_bleio_connection_discover_remote_services(bleio_connection_obj_t *self, mp_obj_t service_uuids_whitelist) {
// FIX discover_remote_services(self->connection, service_uuids_whitelist);
bleio_connection_ensure_connected(self);
// Convert to a tuple and then clear the list so the callee will take ownership.
mp_obj_tuple_t *services_tuple =
mp_obj_new_tuple(self->connection->remote_service_list->len,
self->connection->remote_service_list->items);
mp_obj_list_clear(MP_OBJ_FROM_PTR(self->connection->remote_service_list));
return services_tuple;
}
uint16_t bleio_connection_get_conn_handle(bleio_connection_obj_t *self) {
if (self == NULL || self->connection == NULL) {
return BLE_CONN_HANDLE_INVALID;
}
return self->connection->conn_handle;
}
mp_obj_t bleio_connection_new_from_internal(bleio_connection_internal_t *internal) {
if (internal->connection_obj != mp_const_none) {
return internal->connection_obj;
}
bleio_connection_obj_t *connection = m_new_obj(bleio_connection_obj_t);
connection->base.type = &bleio_connection_type;
connection->connection = internal;
internal->connection_obj = connection;
return MP_OBJ_FROM_PTR(connection);
}
// Find the connection that uses the given conn_handle. Return NULL if not found.
bleio_connection_internal_t *bleio_conn_handle_to_connection(uint16_t conn_handle) {
bleio_connection_internal_t *connection;
for (size_t i = 0; i < BLEIO_TOTAL_CONNECTION_COUNT; i++) {
connection = &bleio_connections[i];
if (connection->conn_handle == conn_handle) {
return connection;
}
}
return NULL;
}

89
devices/ble_hci/common-hal/_bleio/Connection.h Normal file
View File

@ -0,0 +1,89 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2019 Dan Halbert for Adafruit Industries
* Copyright (c) 2018 Artur Pacholec
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#ifndef MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_CONNECTION_H
#define MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_CONNECTION_H
#include <stdbool.h>
#include "py/obj.h"
#include "py/objlist.h"
#include "common-hal/_bleio/__init__.h"
#include "shared-module/_bleio/Address.h"
#include "common-hal/_bleio/Service.h"
typedef enum {
PAIR_NOT_PAIRED,
PAIR_WAITING,
PAIR_PAIRED,
} pair_status_t;
// We split the Connection object into two so that the internal mechanics can live outside of the
// VM. If it were one object, then we'd risk user code seeing a connection object of theirs be
// reused.
typedef struct {
uint16_t conn_handle;
bool is_central;
// Remote services discovered when this peripheral is acting as a client.
mp_obj_list_t *remote_service_list;
// The advertising data and scan response buffers are held by us, not by the SD, so we must
// maintain them and not change it. If we need to change the contents during advertising,
// there are tricks to get the SD to notice (see DevZone - TBS).
bonding_keys_t bonding_keys;
// EDIV: Encrypted Diversifier: Identifies LTK during legacy pairing.
uint16_t ediv;
volatile pair_status_t pair_status;
uint8_t sec_status; // Internal security status.
mp_obj_t connection_obj;
// REMOVE ble_gap_conn_params_t conn_params;
volatile bool conn_params_updating;
uint16_t mtu;
// Request that CCCD values for this connection be saved, using sys_attr values.
volatile bool do_bond_cccds;
// Request that security key info for this connection be saved.
volatile bool do_bond_keys;
// Time of setting do_bond_ccds: we delay a bit to consolidate multiple CCCD changes
// into one write. Time is currently in ticks_ms.
uint64_t do_bond_cccds_request_time;
// FIX from att.c
uint8_t role;
bt_addr_le_t addr;
} bleio_connection_internal_t;
typedef struct {
mp_obj_base_t base;
bleio_connection_internal_t *connection;
// The HCI disconnect reason.
uint8_t disconnect_reason;
} bleio_connection_obj_t;
uint16_t bleio_connection_get_conn_handle(bleio_connection_obj_t *self);
mp_obj_t bleio_connection_new_from_internal(bleio_connection_internal_t *connection);
bleio_connection_internal_t *bleio_conn_handle_to_connection(uint16_t conn_handle);
#endif // MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_CONNECTION_H

114
devices/ble_hci/common-hal/_bleio/Descriptor.c Normal file
View File

@ -0,0 +1,114 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2019 Dan Halbert for Adafruit Industries
* Copyright (c) 2018 Artur Pacholec
* Copyright (c) 2016 Glenn Ruben Bakke
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#include "py/runtime.h"
#include "shared-bindings/_bleio/__init__.h"
#include "shared-bindings/_bleio/Descriptor.h"
#include "shared-bindings/_bleio/Service.h"
#include "shared-bindings/_bleio/UUID.h"
void common_hal_bleio_descriptor_construct(bleio_descriptor_obj_t *self, bleio_characteristic_obj_t *characteristic, bleio_uuid_obj_t *uuid, bleio_attribute_security_mode_t read_perm, bleio_attribute_security_mode_t write_perm, mp_int_t max_length, bool fixed_length, mp_buffer_info_t *initial_value_bufinfo) {
self->characteristic = characteristic;
self->uuid = uuid;
self->handle = BLE_GATT_HANDLE_INVALID;
self->read_perm = read_perm;
self->write_perm = write_perm;
self->value = mp_obj_new_bytes(initial_value_bufinfo->buf, initial_value_bufinfo->len);
const mp_int_t max_length_max = fixed_length ? BLE_GATTS_FIX_ATTR_LEN_MAX : BLE_GATTS_VAR_ATTR_LEN_MAX;
if (max_length < 0 || max_length > max_length_max) {
mp_raise_ValueError_varg(translate("max_length must be 0-%d when fixed_length is %s"),
max_length_max, fixed_length ? "True" : "False");
}
self->max_length = max_length;
self->fixed_length = fixed_length;
common_hal_bleio_descriptor_set_value(self, initial_value_bufinfo);
}
bleio_uuid_obj_t *common_hal_bleio_descriptor_get_uuid(bleio_descriptor_obj_t *self) {
return self->uuid;
}
bleio_characteristic_obj_t *common_hal_bleio_descriptor_get_characteristic(bleio_descriptor_obj_t *self) {
return self->characteristic;
}
size_t common_hal_bleio_descriptor_get_value(bleio_descriptor_obj_t *self, uint8_t *buf, size_t len) {
// Do GATT operations only if this descriptor has been registered
if (self->handle != BLE_GATT_HANDLE_INVALID) {
if (common_hal_bleio_service_get_is_remote(self->characteristic->service)) {
// uint16_t conn_handle = bleio_connection_get_conn_handle(self->characteristic->service->connection);
// FIX have att_read_req fill in a buffer
// uint8_t rsp[MAX(len, 512)];
// return att_read_req(conn_handle, self->handle, rsp, len);
return 0;
} else {
mp_buffer_info_t bufinfo;
if (!mp_get_buffer(self->value, &bufinfo, MP_BUFFER_READ)) {
return 0;
}
const size_t actual_length = MIN(len, bufinfo.len);
memcpy(buf, bufinfo.buf, actual_length);
return actual_length;
}
}
return 0;
}
void common_hal_bleio_descriptor_set_value(bleio_descriptor_obj_t *self, mp_buffer_info_t *bufinfo) {
if (self->fixed_length && bufinfo->len != self->max_length) {
mp_raise_ValueError(translate("Value length != required fixed length"));
}
if (bufinfo->len > self->max_length) {
mp_raise_ValueError(translate("Value length > max_length"));
}
self->value = mp_obj_new_bytes(bufinfo->buf, bufinfo->len);
// Do GATT operations only if this descriptor has been registered.
if (self->handle != BLE_GATT_HANDLE_INVALID) {
if (common_hal_bleio_service_get_is_remote(self->characteristic->service)) {
// FIX
// uint16_t conn_handle = bleio_connection_get_conn_handle(self->service->connection);
// att_write_req(conn_handle, self->handle, bufinfo->buf, bufinfo->len, rsp);
} else {
// Always write the value locally even if no connections are active.
if (self->fixed_length && bufinfo->len != self->max_length) {
return;
}
if (bufinfo->len > self->max_length) {
return;
}
self->value = mp_obj_new_bytes(bufinfo->buf, bufinfo->len);
}
}
}

53
devices/ble_hci/common-hal/_bleio/Descriptor.h Normal file
View File

@ -0,0 +1,53 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2018 Dan Halbert for Adafruit Industries
* Copyright (c) 2018 Artur Pacholec
* Copyright (c) 2016 Glenn Ruben Bakke
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#ifndef MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_DESCRIPTOR_H
#define MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_DESCRIPTOR_H
#include "py/obj.h"
#include "common-hal/_bleio/UUID.h"
// Forward declare characteristic because it includes a Descriptor.
struct _bleio_characteristic_obj;
typedef struct _bleio_descriptor_obj {
mp_obj_base_t base;
// Will be MP_OBJ_NULL before being assigned to a Characteristic.
struct _bleio_characteristic_obj *characteristic;
bleio_uuid_obj_t *uuid;
mp_obj_t value;
uint16_t max_length;
bool fixed_length;
uint16_t handle;
bleio_attribute_security_mode_t read_perm;
bleio_attribute_security_mode_t write_perm;
struct _bleio_descriptor_obj *next;
} bleio_descriptor_obj_t;
#endif // MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_DESCRIPTOR_H

268
devices/ble_hci/common-hal/_bleio/PacketBuffer.c Normal file
View File

@ -0,0 +1,268 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2019-2020 Scott Shawcroft for Adafruit Industries
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#include <string.h>
#include <stdio.h>
#include "lib/utils/interrupt_char.h"
#include "py/runtime.h"
#include "py/stream.h"
#include "shared-bindings/_bleio/__init__.h"
#include "shared-bindings/_bleio/Connection.h"
#include "shared-bindings/_bleio/PacketBuffer.h"
#include "supervisor/shared/tick.h"
STATIC void write_to_ringbuf(bleio_packet_buffer_obj_t *self, uint8_t *data, uint16_t len) {
if (len + sizeof(uint16_t) > ringbuf_capacity(&self->ringbuf)) {
// This shouldn't happen.
return;
}
// Push all the data onto the ring buffer.
// Make room for the new value by dropping the oldest packets first.
while (ringbuf_capacity(&self->ringbuf) - ringbuf_num_filled(&self->ringbuf) < len + sizeof(uint16_t)) {
uint16_t packet_length;
ringbuf_get_n(&self->ringbuf, (uint8_t *)&packet_length, sizeof(uint16_t));
for (uint16_t i = 0; i < packet_length; i++) {
ringbuf_get(&self->ringbuf);
}
// set an overflow flag?
}
ringbuf_put_n(&self->ringbuf, (uint8_t *)&len, sizeof(uint16_t));
ringbuf_put_n(&self->ringbuf, data, len);
}
STATIC uint32_t queue_next_write(bleio_packet_buffer_obj_t *self) {
// Queue up the next outgoing buffer. We use two, one that has been passed to the SD for
// transmission (when packet_queued is true) and the other is `pending` and can still be
// modified. By primarily appending to the `pending` buffer we can reduce the protocol overhead
// of the lower level link and ATT layers.
self->packet_queued = false;
if (self->pending_size > 0) {
mp_buffer_info_t bufinfo = {
.buf = self->outgoing[self->pending_index],
.len = self->pending_size,
};
common_hal_bleio_characteristic_set_value(self->characteristic, &bufinfo);
self->pending_size = 0;
self->pending_index = (self->pending_index + 1) % 2;
self->packet_queued = true;
}
return 0;
}
void bleio_packet_buffer_update(bleio_packet_buffer_obj_t *self, mp_buffer_info_t *bufinfo) {
write_to_ringbuf(self, bufinfo->buf, bufinfo->len);
}
void common_hal_bleio_packet_buffer_construct(
bleio_packet_buffer_obj_t *self, bleio_characteristic_obj_t *characteristic,
size_t buffer_size, size_t max_packet_size) {
self->characteristic = characteristic;
self->client = self->characteristic->service->is_remote;
bleio_characteristic_properties_t incoming =
self->characteristic->props & (CHAR_PROP_WRITE_NO_RESPONSE | CHAR_PROP_WRITE);
bleio_characteristic_properties_t outgoing =
self->characteristic->props & (CHAR_PROP_NOTIFY | CHAR_PROP_INDICATE);
if (self->client) {
// Swap if we're the client.
bleio_characteristic_properties_t temp = incoming;
incoming = outgoing;
outgoing = temp;
self->conn_handle = bleio_connection_get_conn_handle(MP_OBJ_TO_PTR(self->characteristic->service->connection));
} else {
self->conn_handle = BLE_CONN_HANDLE_INVALID;
}
if (incoming) {
if (!ringbuf_alloc(&self->ringbuf, buffer_size * (sizeof(uint16_t) + max_packet_size), false)) {
mp_raise_ValueError(translate("Buffer too large and unable to allocate"));
}
}
if (outgoing) {
self->packet_queued = false;
self->pending_index = 0;
self->pending_size = 0;
self->outgoing[0] = m_malloc(max_packet_size, false);
self->outgoing[1] = m_malloc(max_packet_size, false);
} else {
self->outgoing[0] = NULL;
self->outgoing[1] = NULL;
}
self->max_packet_size = max_packet_size;
bleio_characteristic_set_observer(self->characteristic, self);
}
mp_int_t common_hal_bleio_packet_buffer_readinto(bleio_packet_buffer_obj_t *self, uint8_t *data, size_t len) {
if (ringbuf_num_filled(&self->ringbuf) < 2) {
return 0;
}
// Copy received data.
// Get packet length, which is in first two bytes of packet.
uint16_t packet_length;
ringbuf_get_n(&self->ringbuf, (uint8_t *)&packet_length, sizeof(uint16_t));
mp_int_t ret;
if (packet_length > len) {
// Packet is longer than requested. Return negative of overrun value.
ret = len - packet_length;
// Discard the packet if it's too large. Don't fill data.
while (packet_length--) {
(void)ringbuf_get(&self->ringbuf);
}
} else {
// Read as much as possible, but might be shorter than len.
ringbuf_get_n(&self->ringbuf, data, packet_length);
ret = packet_length;
}
return ret;
}
mp_int_t common_hal_bleio_packet_buffer_write(bleio_packet_buffer_obj_t *self,
const uint8_t *data, size_t len, uint8_t *header, size_t header_len) {
if (self->outgoing[0] == NULL) {
mp_raise_bleio_BluetoothError(translate("Writes not supported on Characteristic"));
}
if (self->conn_handle == BLE_CONN_HANDLE_INVALID) {
return -1;
}
uint16_t outgoing_packet_length = common_hal_bleio_packet_buffer_get_outgoing_packet_length(self);
if (len + header_len > outgoing_packet_length) {
// Supplied data will not fit in a single BLE packet.
mp_raise_ValueError(translate("Total data to write is larger than outgoing_packet_length"));
}
if (len + self->pending_size > outgoing_packet_length) {
// No room to append len bytes to packet. Wait until we get a free buffer,
// and keep checking that we haven't been disconnected.
while (self->pending_size != 0 && self->conn_handle != BLE_CONN_HANDLE_INVALID) {
RUN_BACKGROUND_TASKS;
}
}
if (self->conn_handle == BLE_CONN_HANDLE_INVALID) {
return -1;
}
size_t num_bytes_written = 0;
uint8_t *pending = self->outgoing[self->pending_index];
if (self->pending_size == 0) {
memcpy(pending, header, header_len);
self->pending_size += header_len;
num_bytes_written += header_len;
}
memcpy(pending + self->pending_size, data, len);
self->pending_size += len;
num_bytes_written += len;
// If no writes are queued then sneak in this data.
if (!self->packet_queued) {
queue_next_write(self);
}
return num_bytes_written;
}
mp_int_t common_hal_bleio_packet_buffer_get_incoming_packet_length(bleio_packet_buffer_obj_t *self) {
// If this PacketBuffer is coming from a remote service via NOTIFY or INDICATE
// the maximum size is what can be sent in one
// BLE packet. But we must be connected to know that value.
//
// Otherwise it can be as long as the characteristic
// will permit, whether or not we're connected.
if (self->characteristic == NULL) {
return -1;
}
if (self->characteristic->service != NULL &&
self->characteristic->service->is_remote &&
(common_hal_bleio_characteristic_get_properties(self->characteristic) &
(CHAR_PROP_INDICATE | CHAR_PROP_NOTIFY))) {
// We are talking to a remote service, and data is arriving via NOTIFY or INDICATE.
if (self->conn_handle != BLE_CONN_HANDLE_INVALID) {
bleio_connection_internal_t *connection = bleio_conn_handle_to_connection(self->conn_handle);
if (connection) {
return MIN(common_hal_bleio_connection_get_max_packet_length(connection),
self->characteristic->max_length);
}
}
// There's no current connection, so we don't know the MTU, and
// we can't tell what the largest incoming packet length would be.
return -1;
}
return self->characteristic->max_length;
}
mp_int_t common_hal_bleio_packet_buffer_get_outgoing_packet_length(bleio_packet_buffer_obj_t *self) {
// If we are sending data via NOTIFY or INDICATE, the maximum size
// is what can be sent in one BLE packet. But we must be connected
// to know that value.
//
// Otherwise it can be as long as the characteristic
// will permit, whether or not we're connected.
if (self->characteristic == NULL) {
return -1;
}
if (self->characteristic->service != NULL &&
!self->characteristic->service->is_remote &&
(common_hal_bleio_characteristic_get_properties(self->characteristic) &
(CHAR_PROP_INDICATE | CHAR_PROP_NOTIFY))) {
// We are sending to a client, via NOTIFY or INDICATE.
if (self->conn_handle != BLE_CONN_HANDLE_INVALID) {
bleio_connection_internal_t *connection = bleio_conn_handle_to_connection(self->conn_handle);
if (connection) {
return MIN(MIN(common_hal_bleio_connection_get_max_packet_length(connection),
self->max_packet_size),
self->characteristic->max_length);
}
}
// There's no current connection, so we don't know the MTU, and
// we can't tell what the largest outgoing packet length would be.
return -1;
}
return MIN(self->characteristic->max_length, self->max_packet_size);
}
bool common_hal_bleio_packet_buffer_deinited(bleio_packet_buffer_obj_t *self) {
return self->characteristic == NULL;
}
void common_hal_bleio_packet_buffer_deinit(bleio_packet_buffer_obj_t *self) {
if (!common_hal_bleio_packet_buffer_deinited(self)) {
bleio_characteristic_clear_observer(self->characteristic);
}
}

54
devices/ble_hci/common-hal/_bleio/PacketBuffer.h Normal file
View File

@ -0,0 +1,54 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2019-2020 Scott Shawcroft for Adafruit Industries
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#ifndef MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_PACKETBUFFER_H
#define MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_PACKETBUFFER_H
#include "py/ringbuf.h"
#include "shared-bindings/_bleio/Characteristic.h"
typedef struct {
mp_obj_base_t base;
bleio_characteristic_obj_t *characteristic;
// Ring buffer storing consecutive incoming values.
ringbuf_t ringbuf;
// Two outgoing buffers to alternate between. One will be queued for transmission by the SD and
// the other is waiting to be queued and can be extended.
uint8_t *outgoing[2];
volatile uint16_t pending_size;
// We remember the conn_handle so we can do a NOTIFY/INDICATE to a client.
// We can find out the conn_handle on a Characteristic write or a CCCD write (but not a read).
volatile uint16_t conn_handle;
uint16_t max_packet_size;
uint8_t pending_index;
uint8_t write_type;
bool client;
bool packet_queued;
} bleio_packet_buffer_obj_t;
void bleio_packet_buffer_update(bleio_packet_buffer_obj_t *self, mp_buffer_info_t *bufinfo);
#endif // MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_PACKETBUFFER_H

130
devices/ble_hci/common-hal/_bleio/Service.c Normal file
View File

@ -0,0 +1,130 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2020 Dan Halbert for Adafruit Industries
* Copyright (c) 2018 Artur Pacholec
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#include "py/runtime.h"
#include "shared-bindings/_bleio/__init__.h"
#include "shared-bindings/_bleio/Characteristic.h"
#include "shared-bindings/_bleio/Descriptor.h"
#include "shared-bindings/_bleio/Service.h"
#include "shared-bindings/_bleio/Adapter.h"
uint32_t _common_hal_bleio_service_construct(bleio_service_obj_t *self, bleio_uuid_obj_t *uuid, bool is_secondary, mp_obj_list_t *characteristic_list) {
self->uuid = uuid;
self->characteristic_list = characteristic_list;
self->is_remote = false;
self->connection = NULL;
self->is_secondary = is_secondary;
vm_used_ble = true;
self->handle = bleio_adapter_add_attribute(&common_hal_bleio_adapter_obj, MP_OBJ_TO_PTR(self));
self->start_handle = self->handle;
self->end_handle = self->handle;
if (self->handle == BLE_GATT_HANDLE_INVALID) {
return 1;
}
return 0;
}
void common_hal_bleio_service_construct(bleio_service_obj_t *self, bleio_uuid_obj_t *uuid, bool is_secondary) {
if (_common_hal_bleio_service_construct(self, uuid, is_secondary,
mp_obj_new_list(0, NULL)) != 0) {
mp_raise_RuntimeError(translate("Failed to add service"));
}
}
void bleio_service_from_connection(bleio_service_obj_t *self, mp_obj_t connection) {
self->handle = 0xFFFF;
self->uuid = NULL;
self->characteristic_list = mp_obj_new_list(0, NULL);
self->is_remote = true;
self->is_secondary = false;
self->connection = connection;
}
bleio_uuid_obj_t *common_hal_bleio_service_get_uuid(bleio_service_obj_t *self) {
return self->uuid;
}
mp_obj_tuple_t *common_hal_bleio_service_get_characteristics(bleio_service_obj_t *self) {
return mp_obj_new_tuple(self->characteristic_list->len, self->characteristic_list->items);
}
bool common_hal_bleio_service_get_is_remote(bleio_service_obj_t *self) {
return self->is_remote;
}
bool common_hal_bleio_service_get_is_secondary(bleio_service_obj_t *self) {
return self->is_secondary;
}
void common_hal_bleio_service_add_characteristic(bleio_service_obj_t *self,
bleio_characteristic_obj_t *characteristic,
mp_buffer_info_t *initial_value_bufinfo,
const char *user_description) {
if (self->handle != common_hal_bleio_adapter_obj.last_added_service_handle) {
mp_raise_bleio_BluetoothError(
translate("Characteristic can only be added to most recently added service"));
}
characteristic->decl_handle = bleio_adapter_add_attribute(
&common_hal_bleio_adapter_obj, MP_OBJ_TO_PTR(characteristic));
// This is the value handle.
characteristic->handle = bleio_adapter_add_attribute(
&common_hal_bleio_adapter_obj, MP_OBJ_TO_PTR(characteristic));
self->end_handle = characteristic->handle;
if (characteristic->props & (CHAR_PROP_NOTIFY | CHAR_PROP_INDICATE)) {
// We need a CCCD if this characteristic is doing notify or indicate.
bleio_descriptor_obj_t *cccd = m_new_obj(bleio_descriptor_obj_t);
cccd->base.type = &bleio_descriptor_type;
uint16_t zero = 0;
mp_buffer_info_t zero_cccd_value = {
.buf = &zero,
.len = sizeof(zero),
};
common_hal_bleio_descriptor_construct(
cccd,
characteristic,
&cccd_uuid, // 0x2902
SECURITY_MODE_OPEN, // CCCD read perm
characteristic->read_perm, // Make CCCD write perm match characteristic read perm.
2, // 2 bytes
true, // fixed length
&zero_cccd_value // Initial value is 0.
);
// Adds CCCD to attribute table, and also extends self->end_handle to include the CCCD.
common_hal_bleio_characteristic_add_descriptor(characteristic, cccd);
characteristic->cccd = cccd;
}
mp_obj_list_append(self->characteristic_list, MP_OBJ_FROM_PTR(characteristic));
}

54
devices/ble_hci/common-hal/_bleio/Service.h Normal file
View File

@ -0,0 +1,54 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2018 Dan Halbert for Adafruit Industries
* Copyright (c) 2018 Artur Pacholec
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#ifndef MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_SERVICE_H
#define MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_SERVICE_H
#include "py/objlist.h"
#include "common-hal/_bleio/UUID.h"
typedef struct bleio_service_obj {
mp_obj_base_t base;
// Handle for the local service.
uint16_t handle;
// True if created during discovery.
bool is_remote;
bool is_secondary;
bleio_uuid_obj_t *uuid;
// The connection object is set only when this is a remote service.
// A local service doesn't know the connection.
mp_obj_t connection;
mp_obj_list_t *characteristic_list;
// Range of attribute handles of this service.
uint16_t start_handle;
uint16_t end_handle;
struct bleio_service_obj *next;
} bleio_service_obj_t;
void bleio_service_from_connection(bleio_service_obj_t *self, mp_obj_t connection);
#endif // MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_SERVICE_H

75
devices/ble_hci/common-hal/_bleio/UUID.c Normal file
View File

@ -0,0 +1,75 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2018 Dan Halbert for Adafruit Industries
* Copyright (c) 2018 Artur Pacholec
* Copyright (c) 2016 Glenn Ruben Bakke
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#include <string.h>
#include "py/runtime.h"
#include "common-hal/_bleio/UUID.h"
#include "shared-bindings/_bleio/__init__.h"
#include "shared-bindings/_bleio/Adapter.h"
// If uuid128 is NULL, this is a Bluetooth SIG 16-bit UUID.
// If uuid128 is not NULL, it's a 128-bit (16-byte) UUID, with bytes 12 and 13 zero'd out, where
// the 16-bit part goes. Those 16 bits are passed in uuid16.
void common_hal_bleio_uuid_construct(bleio_uuid_obj_t *self, mp_int_t uuid16, const uint8_t uuid128[16]) {
self->size = uuid128 == NULL ? 16 : 128;
self->uuid16 = uuid16;
if (uuid128) {
memcpy(self->uuid128, uuid128, 16);
self->uuid128[12] = uuid16 & 0xff;
self->uuid128[13] = uuid16 >> 8;
} else {
memset(self->uuid128, 0, 16);
}
}
uint32_t common_hal_bleio_uuid_get_size(bleio_uuid_obj_t *self) {
return self->size;
}
uint32_t common_hal_bleio_uuid_get_uuid16(bleio_uuid_obj_t *self) {
return self->uuid16;
}
void common_hal_bleio_uuid_get_uuid128(bleio_uuid_obj_t *self, uint8_t uuid128[16]) {
memcpy(uuid128, self->uuid128, 16);
}
void common_hal_bleio_uuid_pack_into(bleio_uuid_obj_t *self, uint8_t *buf) {
if (self->size == 16) {
buf[0] = self->uuid16 & 0xff;
buf[1] = self->uuid16 >> 8;
} else {
common_hal_bleio_uuid_get_uuid128(self, buf);
}
}
// Return a uui16 only if this is a standard uuid. Otherwise return BLE_UUID_UNKNOWN.
uint16_t bleio_uuid_get_uuid16_or_unknown(bleio_uuid_obj_t *uuid) {
return uuid->size == 16 ? uuid->uuid16 : BLE_UUID_UNKNOWN;
}

58
devices/ble_hci/common-hal/_bleio/UUID.h Normal file
View File

@ -0,0 +1,58 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2019 Dan Halbert for Adafruit Industries
* Copyright (c) 2018 Artur Pacholec
* Copyright (c) 2016 Glenn Ruben Bakke
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#ifndef MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_UUID_H
#define MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_UUID_H
#include "py/obj.h"
// Types returned by attribute table lookups. These are UUIDs.
typedef enum {
BLE_UUID_UNKNOWN = 0x0000,
BLE_UUID_SERVICE_PRIMARY = 0x2800,
BLE_UUID_SERVICE_SECONDARY = 0x2801,
BLE_UUID_SERVICE_INCLUDE = 0x2802,// not yet implemented by us
BLE_UUID_CHARACTERISTIC = 0x2803,
BLE_UUID_CHAR_EXTENDED_PROPS = 0x2900,// not yet implemented by us
BLE_UUID_CHAR_USER_DESC = 0x2901,// not yet implemented by us
BLE_UUID_CCCD = 0x2902,
BLE_UUID_SCCD = 0x2903,// not yet implemented by us
BLE_UUID_CHAR_PRESENTATION_FMT = 0x2904, // not yet implemented by us
BLE_UUID_CHAR_AGGREGATE_FMT = 0x2905,// not yet implemented by us
} ble_standard_uuid;
typedef struct {
mp_obj_base_t base;
uint8_t size;
uint16_t uuid16;
uint8_t uuid128[16];
} bleio_uuid_obj_t;
uint16_t bleio_uuid_get_uuid16_or_unknown(bleio_uuid_obj_t *uuid);
#endif // MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_UUID_H

112
devices/ble_hci/common-hal/_bleio/__init__.c Normal file
View File

@ -0,0 +1,112 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2018 Dan Halbert for Adafruit Industries
* Copyright (c) 2018 Artur Pacholec
* Copyright (c) 2016 Glenn Ruben Bakke
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#include <string.h>
#include "py/runtime.h"
#include "shared-bindings/_bleio/__init__.h"
#include "shared-bindings/_bleio/Adapter.h"
#include "shared-bindings/_bleio/Characteristic.h"
#include "shared-bindings/_bleio/Connection.h"
#include "shared-bindings/_bleio/Descriptor.h"
#include "shared-bindings/_bleio/Service.h"
#include "shared-bindings/_bleio/UUID.h"
#include "supervisor/shared/bluetooth/bluetooth.h"
// UUID shared by all cccd's.
bleio_uuid_obj_t cccd_uuid;
bool vm_used_ble;
// void check_sec_status(uint8_t sec_status) {
// if (sec_status == BLE_GAP_SEC_STATUS_SUCCESS) {
// return;
// }
// switch (sec_status) {
// case BLE_GAP_SEC_STATUS_UNSPECIFIED:
// mp_raise_bleio_SecurityError(translate("Unspecified issue. Can be that the pairing prompt on the other device was declined or ignored."));
// return;
// default:
// mp_raise_bleio_SecurityError(translate("Unknown security error: 0x%04x"), sec_status);
// }
// }
// Turn off BLE on a reset or reload.
void bleio_reset() {
// Create a UUID object for all CCCD's.
cccd_uuid.base.type = &bleio_uuid_type;
common_hal_bleio_uuid_construct(&cccd_uuid, BLE_UUID_CCCD, NULL);
bleio_hci_reset();
if (!common_hal_bleio_adapter_get_enabled(&common_hal_bleio_adapter_obj)) {
return;
}
bleio_adapter_reset(&common_hal_bleio_adapter_obj);
if (!vm_used_ble) {
// No user-code BLE operations were done, so we can maintain the supervisor state.
return;
}
common_hal_bleio_adapter_set_enabled(&common_hal_bleio_adapter_obj, false);
common_hal_bleio_adapter_obj.allocated = false;
bleio_set_adapter(mp_const_none);
// FIX bonding_reset();
supervisor_start_bluetooth();
}
// The singleton _bleio.Adapter object, bound to _bleio.adapter
bleio_adapter_obj_t common_hal_bleio_adapter_obj = {
.base = {
.type = &bleio_adapter_type,
},
};
bleio_adapter_obj_t *common_hal_bleio_allocate_adapter_or_raise(void) {
if (common_hal_bleio_adapter_obj.allocated) {
mp_raise_RuntimeError(translate("Too many Adapters"));
}
return &common_hal_bleio_adapter_obj;
}
void common_hal_bleio_check_connected(uint16_t conn_handle) {
if (conn_handle == BLE_CONN_HANDLE_INVALID) {
mp_raise_ConnectionError(translate("Not connected"));
}
}
void common_hal_bleio_gc_collect(void) {
bleio_adapter_gc_collect(&common_hal_bleio_adapter_obj);
}
void bleio_background(void) {
bleio_adapter_background(&common_hal_bleio_adapter_obj);
}

62
devices/ble_hci/common-hal/_bleio/__init__.h Normal file
View File

@ -0,0 +1,62 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2018 Dan Halbert for Adafruit Industries
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#ifndef MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_INIT_H
#define MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_INIT_H
#include <stdbool.h>
#include "shared-bindings/_bleio/UUID.h"
#include "att.h"
#include "hci.h"
void bleio_background(void);
void bleio_reset(void);
typedef struct {
// ble_gap_enc_key_t own_enc;
// ble_gap_enc_key_t peer_enc;
// ble_gap_id_key_t peer_id;
} bonding_keys_t;
// We assume variable length data.
// 20 bytes max (23 - 3).
#define GATT_MAX_DATA_LENGTH (BT_ATT_DEFAULT_LE_MTU - 3)
// FIX
#define BLE_GATT_HANDLE_INVALID 0x0000
#define BLE_CONN_HANDLE_INVALID 0xFFFF
#define BLE_GATTS_FIX_ATTR_LEN_MAX (510) /**< Maximum length for fixed length Attribute Values. */
#define BLE_GATTS_VAR_ATTR_LEN_MAX (512) /**< Maximum length for variable length Attribute Values. */
// Track if the user code modified the BLE state to know if we need to undo it on reload.
extern bool vm_used_ble;
// UUID shared by all CCCD's.
extern bleio_uuid_obj_t cccd_uuid;
#endif // MICROPY_INCLUDED_BLE_HCI_COMMON_HAL_INIT_H

1788
devices/ble_hci/common-hal/_bleio/att.c Normal file
View File

File diff suppressed because it is too large Load Diff

57
devices/ble_hci/common-hal/_bleio/att.h Normal file
View File

@ -0,0 +1,57 @@
// Derived from ArduinoBLE.
// Copyright 2020 Dan Halbert for Adafruit Industries
/*
This file is part of the ArduinoBLE library.
Copyright (c) 2018 Arduino SA. All rights reserved.
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
#ifndef MICROPY_INCLUDED_DEVICES_BLE_HCI_COMMON_HAL_BLEIO_ATT_H
#define MICROPY_INCLUDED_DEVICES_BLE_HCI_COMMON_HAL_BLEIO_ATT_H
#include <stdbool.h>
#include <stdint.h>
#include "hci_include/addr.h"
#include "hci_include/att.h"
#include "hci_include/att_internal.h"
void bleio_att_reset(void);
// FIX void att_set_event_handler(BLEDeviceEvent event, BLEDeviceEventHandler eventHandler);
bool att_address_is_connected(bt_addr_le_t *addr);
bool att_connect_to_address(bt_addr_le_t *addr);
bool att_disconnect(uint16_t conn_handle);
bool att_disconnect_all(void);
bool att_discover_attributes(bt_addr_le_t *addr, const char *service_uuid_filter);
bool att_exchange_mtu(uint16_t conn_handle);
bool att_handle_is_connected(uint16_t handle);
bool att_indicate(uint16_t handle, const uint8_t *value, int length);
bool att_is_connected(void);
bool att_notify(uint16_t handle, const uint8_t *value, int length);
int att_read_req(uint16_t conn_handle, uint16_t handle, uint8_t response_buffer[]);
int att_write_req(uint16_t conn_handle, uint16_t handle, const uint8_t *data, uint8_t data_len, uint8_t response_buffer[]);
uint16_t att_conn_handle(bt_addr_le_t *addr);
uint16_t att_mtu(uint16_t handle);
void att_add_connection(uint16_t handle, uint8_t role, bt_addr_le_t *peer_addr, uint16_t interval, uint16_t latency, uint16_t supervision_timeout, uint8_t master_clock_accuracy);
void att_process_data(uint16_t conn_handle, uint8_t dlen, uint8_t data[]);
void att_remove_connection(uint16_t conn_handle, uint8_t reason);
void att_set_max_mtu(uint16_t max_mtu);
void att_set_timeout(unsigned long timeout);
void att_write_cmd(uint16_t conn_handle, uint16_t handle, const uint8_t *data, uint8_t data_len);
#endif // MICROPY_INCLUDED_DEVICES_BLE_HCI_COMMON_HAL_BLEIO_ATT_H

805
devices/ble_hci/common-hal/_bleio/hci.c Normal file
View File

@ -0,0 +1,805 @@
// This file is derived from the ArduinoBLE library. Its header is below.
/*
This file is part of the ArduinoBLE library.
Copyright (c) 2018 Arduino SA. All rights reserved.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
#include "att.h"
#include "hci.h"
#include "py/obj.h"
#include "py/mperrno.h"
#include "py/runtime.h"
// Zephyr include files to define HCI communication values and structs.
#include "hci_include/hci.h"
#include "hci_include/hci_err.h"
#include "hci_include/l2cap_internal.h"
#include <string.h>
#include "py/mphal.h" // *****************************
#include "supervisor/shared/tick.h"
#include "shared-bindings/_bleio/__init__.h"
#include "common-hal/_bleio/Adapter.h"
#include "shared-bindings/microcontroller/__init__.h"
// Set to 1 for extensive HCI packet logging.
#define HCI_DEBUG 0
// HCI H4 protocol packet types: first byte in the packet.
#define H4_CMD 0x01
#define H4_ACL 0x02
#define H4_SCO 0x03
#define H4_EVT 0x04
#define CTS_TIMEOUT_MSECS (1000)
#define RESPONSE_TIMEOUT_MSECS (1000)
// These are the headers of the full packets that are sent over the serial interface.
// They all have a one-byte type-field at the front, one of the H4_xxx packet types.
typedef struct __attribute__ ((packed)) {
uint8_t pkt_type;
uint16_t opcode;
uint8_t param_len;
uint8_t params[];
} h4_hci_cmd_pkt_t;
#define ACL_DATA_PB_FIRST_NON_FLUSH 0
#define ACL_DATA_PB_MIDDLE 1
#define ACL_DATA_PB_FIRST_FLUSH 2
#define ACL_DATA_PB_FULL 3
typedef struct __attribute__ ((packed)) {
uint8_t pkt_type;
uint16_t handle : 12;
uint8_t pb : 2; // Packet boundary flag: ACL_DATA_PB values.
uint8_t bc : 2; // Broadcast flag: always 0b00 for BLE.
uint16_t data_len; // length of data[] in this packet.
uint8_t data[];
} h4_hci_acl_pkt_t;
// The ACL data in an h4_hci_acl_pkt_t may be fragmented across
// multiple ACL_DATA packets, and need to be recombined. This is the
// structure of the combined packet or the first fragment.
typedef struct __attribute__ ((packed)) {
uint16_t acl_data_len; // Length of acl_data. Does not include this header.
uint16_t cid; // Channel ID.
uint8_t acl_data[]; // Length is acl_data_len of full packet.
} acl_data_t;
typedef struct __attribute__ ((packed)) {
uint8_t pkt_type;
uint8_t evt;
uint8_t param_len;
uint8_t params[];
} h4_hci_evt_pkt_t;
//////////////////////////////////////////////////////////////////////
// Static storage:
// FIX size
#define RX_BUFFER_SIZE (3 + 255)
#define ACL_DATA_BUFFER_SIZE (255)
STATIC uint8_t rx_buffer[RX_BUFFER_SIZE];
STATIC size_t rx_idx;
STATIC uint8_t acl_data_buffer[ACL_DATA_BUFFER_SIZE];
STATIC size_t acl_data_len;
STATIC size_t num_command_packets_allowed;
STATIC volatile size_t pending_pkt;
// Results from parsing a command response packet.
STATIC bool cmd_response_received;
STATIC uint16_t cmd_response_opcode;
STATIC uint8_t cmd_response_status;
STATIC size_t cmd_response_len;
STATIC uint8_t *cmd_response_data;
STATIC volatile bool hci_poll_in_progress = false;
//////////////////////////////////////////////////////////////////////
#if HCI_DEBUG
#include "hci_debug.c"
#endif // HCI_DEBUG
STATIC void process_acl_data_pkt(uint8_t pkt_len, uint8_t pkt_data[]) {
h4_hci_acl_pkt_t *pkt = (h4_hci_acl_pkt_t *)pkt_data;
if (pkt->pb != ACL_DATA_PB_MIDDLE) {
// This is the start of a fragmented acl_data packet or is a full packet.
memcpy(acl_data_buffer, pkt->data, pkt->data_len);
acl_data_len = pkt->data_len;
} else {
// This is a middle or end fragment of acl data.
// Append to the accumulated data so far.
memcpy(&acl_data_buffer[acl_data_len], pkt->data, pkt->data_len);
acl_data_len += pkt->data_len;
}
acl_data_t *acl = (acl_data_t *)&acl_data_buffer;
if (acl_data_len != sizeof(acl) + acl->acl_data_len) {
// We don't have the full packet yet.
return;
}
if (acl->cid == BT_L2CAP_CID_ATT) {
att_process_data(pkt->handle, acl->acl_data_len, acl->acl_data);
}
// } else if (aclHdr->cid == BT_L2CAP_CID_LE_SIG) {
// L2CAPSignaling.handleData(aclHdr->handle & 0x0fff, aclHdr->len, &rx_buffer[1 + sizeof(HCIACLHdr)]);
// } else {
// struct __attribute__ ((packed)) {
// uint8_t op;
// uint8_t id;
// uint16_t length;
// uint16_t reason;
// uint16_t localCid;
// uint16_t remoteCid;
// } l2capRejectCid= { 0x01, 0x00, 0x006, 0x0002, aclHdr->cid, 0x0000 };
// sendAclPkt(aclHdr->handle & 0x0fff, 0x0005, sizeof(l2capRejectCid), &l2capRejectCid);
// }
}
// Process number of completed packets. Reduce number of pending packets by reported
// number of completed.
STATIC void process_num_comp_pkts(uint16_t handle, uint16_t num_pkts) {
if (num_pkts && pending_pkt > num_pkts) {
pending_pkt -= num_pkts;
} else {
pending_pkt = 0;
}
}
STATIC void process_evt_pkt(size_t pkt_len, uint8_t pkt_data[]) {
h4_hci_evt_pkt_t *pkt = (h4_hci_evt_pkt_t *)pkt_data;
switch (pkt->evt) {
case BT_HCI_EVT_DISCONN_COMPLETE: {
struct bt_hci_evt_disconn_complete *disconn_complete =
(struct bt_hci_evt_disconn_complete *)pkt->params;
(void)disconn_complete;
att_remove_connection(disconn_complete->handle, disconn_complete->reason);
// FIX L2CAPSignaling.removeConnection(disconn_complete->handle, disconn_complete->reason);
break;
}
case BT_HCI_EVT_CMD_COMPLETE: {
struct cmd_complete_with_status {
struct bt_hci_evt_cmd_complete cmd_complete;
struct bt_hci_evt_cc_status cc_status;
} __packed;
struct cmd_complete_with_status *evt = (struct cmd_complete_with_status *)pkt->params;
num_command_packets_allowed = evt->cmd_complete.ncmd;
cmd_response_received = true;
cmd_response_opcode = evt->cmd_complete.opcode;
cmd_response_status = evt->cc_status.status;
// All the bytes following cmd_complete, -including- the status byte, which is
// included in all the _bt_hci_rp_* structs.
cmd_response_data = (uint8_t *)&evt->cc_status;
// Includes status byte.
cmd_response_len = pkt->param_len - sizeof_field(struct cmd_complete_with_status, cmd_complete);
break;
}
case BT_HCI_EVT_CMD_STATUS: {
struct bt_hci_evt_cmd_status *evt = (struct bt_hci_evt_cmd_status *)pkt->params;
num_command_packets_allowed = evt->ncmd;
cmd_response_received = true;
cmd_response_opcode = evt->opcode;
cmd_response_status = evt->status;
cmd_response_data = NULL;
cmd_response_len = 0;
break;
}
case BT_HCI_EVT_NUM_COMPLETED_PACKETS: {
struct bt_hci_evt_num_completed_packets *evt =
(struct bt_hci_evt_num_completed_packets *)pkt->params;
// Start at zero-th pair: (conn handle, num completed packets).
struct bt_hci_handle_count *handle_and_count = &(evt->h[0]);
for (uint8_t i = 0; i < evt->num_handles; i++) {
process_num_comp_pkts(handle_and_count->handle, handle_and_count->count);
handle_and_count++;
}
break;
}
case BT_HCI_EVT_LE_META_EVENT: {
struct bt_hci_evt_le_meta_event *meta_evt = (struct bt_hci_evt_le_meta_event *)pkt->params;
uint8_t *le_evt = pkt->params + sizeof (struct bt_hci_evt_le_meta_event);
if (meta_evt->subevent == BT_HCI_EVT_LE_CONN_COMPLETE) {
// Advertising stops when connection occurs.
// We don't tell the adapter to stop, because stopping advertising
// when it's already stopped seems to exercise a bug in the ESP32 HCI code:
// It doesn't return a response.
bleio_adapter_advertising_was_stopped(&common_hal_bleio_adapter_obj);
struct bt_hci_evt_le_conn_complete *le_conn_complete =
(struct bt_hci_evt_le_conn_complete *)le_evt;
if (le_conn_complete->status == BT_HCI_ERR_SUCCESS) {
att_add_connection(
le_conn_complete->handle,
le_conn_complete->role,
&le_conn_complete->peer_addr,
le_conn_complete->interval,
le_conn_complete->latency,
le_conn_complete->supv_timeout,
le_conn_complete->clock_accuracy);
}
} else if (meta_evt->subevent == BT_HCI_EVT_LE_ADVERTISING_REPORT) {
struct bt_hci_evt_le_advertising_info *le_advertising_info =
(struct bt_hci_evt_le_advertising_info *)le_evt;
if (le_advertising_info->evt_type == BT_HCI_ADV_DIRECT_IND) {
// FIX
// last byte is RSSI
// GAP.handleLeAdvertisingReport(leAdvertisingReport->type,
// leAdvertisingReport->peerBdaddrType,
// leAdvertisingReport->peerBdaddr,
// leAdvertisingReport->eirLength,
// leAdvertisingReport->eirData,
// rssi); //FIX, don't separate
}
}
break;
}
default:
#if HCI_DEBUG
mp_printf(&mp_plat_print, "process_evt_pkt: Unknown event: %02x\n");
#endif
break;
}
}
void bleio_hci_reset(void) {
rx_idx = 0;
pending_pkt = 0;
hci_poll_in_progress = false;
bleio_att_reset();
}
hci_result_t hci_poll_for_incoming_pkt(void) {
common_hal_mcu_disable_interrupts();
if (hci_poll_in_progress) {
common_hal_mcu_enable_interrupts();
return HCI_OK;
}
hci_poll_in_progress = true;
common_hal_mcu_enable_interrupts();
// Assert RTS low to say we're ready to read data.
common_hal_digitalio_digitalinout_set_value(common_hal_bleio_adapter_obj.rts_digitalinout, false);
int errcode = 0;
bool packet_is_complete = false;
// Read bytes until we run out. There may be more than one packet in the input buffer.
while (!packet_is_complete &&
common_hal_busio_uart_rx_characters_available(common_hal_bleio_adapter_obj.hci_uart) > 0) {
// Read just one character a a time, so we don't accidentally get part of a second
// packet.
size_t num_read =
common_hal_busio_uart_read(common_hal_bleio_adapter_obj.hci_uart, rx_buffer + rx_idx, 1, &errcode);
if (num_read == 0) {
return HCI_OK;
}
if (errcode) {
if (errcode == EAGAIN) {
continue;
}
hci_poll_in_progress = false;
mp_printf(&mp_plat_print, "HCI_READ_ERROR, errcode: %x\n", errcode);
return HCI_READ_ERROR;
}
rx_idx++;
if (rx_idx >= sizeof(rx_buffer)) {
// Incoming packet is too large. Should not happen.
return HCI_READ_ERROR;
}
switch (rx_buffer[0]) {
case H4_ACL:
if (rx_idx >= sizeof(h4_hci_acl_pkt_t)) {
const size_t total_len =
sizeof(h4_hci_acl_pkt_t) + ((h4_hci_acl_pkt_t *)rx_buffer)->data_len;
if (rx_idx == total_len) {
packet_is_complete = true;
}
if (rx_idx > total_len) {
return HCI_PACKET_SIZE_ERROR;
}
}
break;
case H4_EVT:
if (rx_idx >= sizeof(h4_hci_evt_pkt_t)) {
const size_t total_len =
sizeof(h4_hci_evt_pkt_t) + ((h4_hci_evt_pkt_t *)rx_buffer)->param_len;
if (rx_idx == total_len) {
packet_is_complete = true;
}
if (rx_idx > total_len) {
return HCI_PACKET_SIZE_ERROR;
}
}
break;
default:
// Unknown or bad packet type. Start over.
rx_idx = 0;
break;
}
} // end while
if (packet_is_complete) {
// Stop incoming data while processing packet.
common_hal_digitalio_digitalinout_set_value(common_hal_bleio_adapter_obj.rts_digitalinout, true);
size_t pkt_len = rx_idx;
// Reset for next packet.
rx_idx = 0;
packet_is_complete = false;
switch (rx_buffer[0]) {
case H4_ACL:
#if HCI_DEBUG
dump_acl_pkt(false, pkt_len, rx_buffer);
#endif
process_acl_data_pkt(pkt_len, rx_buffer);
break;
case H4_EVT:
#if HCI_DEBUG
dump_evt_pkt(false, pkt_len, rx_buffer);
#endif
process_evt_pkt(pkt_len, rx_buffer);
break;
default:
#if HCI_DEBUG
mp_printf(&mp_plat_print, "Unknown HCI packet type: %d\n", rx_buffer[0]);
#endif
break;
}
// Let incoming bytes flow again.
common_hal_digitalio_digitalinout_set_value(common_hal_bleio_adapter_obj.rts_digitalinout, false);
}
// All done with this batch. Hold off receiving bytes until we're ready again.
///common_hal_digitalio_digitalinout_set_value(common_hal_bleio_adapter_obj.rts_digitalinout, true);
hci_poll_in_progress = false;
return HCI_OK;
}
STATIC hci_result_t write_pkt(uint8_t *buffer, size_t len) {
// Wait for CTS to go low before writing to HCI adapter.
uint64_t start = supervisor_ticks_ms64();
while (common_hal_digitalio_digitalinout_get_value(common_hal_bleio_adapter_obj.cts_digitalinout)) {
RUN_BACKGROUND_TASKS;
if (supervisor_ticks_ms64() - start > CTS_TIMEOUT_MSECS) {
return HCI_WRITE_TIMEOUT;
}
}
int errcode = 0;
common_hal_busio_uart_write(common_hal_bleio_adapter_obj.hci_uart, buffer, len, &errcode);
if (errcode) {
return HCI_WRITE_ERROR;
}
return HCI_OK;
}
STATIC hci_result_t send_command(uint16_t opcode, uint8_t params_len, void *params) {
uint8_t cmd_pkt_len = sizeof(h4_hci_cmd_pkt_t) + params_len;
uint8_t tx_buffer[cmd_pkt_len];
// cmd header is at the beginning of tx_buffer
h4_hci_cmd_pkt_t *cmd_pkt = (h4_hci_cmd_pkt_t *)tx_buffer;
cmd_pkt->pkt_type = H4_CMD;
cmd_pkt->opcode = opcode;
cmd_pkt->param_len = params_len;
memcpy(cmd_pkt->params, params, params_len);
#if HCI_DEBUG
dump_cmd_pkt(true, sizeof(tx_buffer), tx_buffer);
#endif
int result = write_pkt(tx_buffer, cmd_pkt_len);
if (result != HCI_OK) {
return result;
}
cmd_response_received = false;
// Wait for a response. Note that other packets may be received that are not
// command responses.
uint64_t start = supervisor_ticks_ms64();
while (supervisor_ticks_ms64() - start < RESPONSE_TIMEOUT_MSECS) {
// RUN_BACKGROUND_TASKS includes hci_poll_for_incoming_pkt();
RUN_BACKGROUND_TASKS;
if (cmd_response_received && cmd_response_opcode == opcode) {
// If this is definitely a response to the command that was sent,
// return the status value, which will will be
// BT_HCI_ERR_SUCCESS (0x00) if the command succeeded,
// or a BT_HCI_ERR_x value (> 0x00) if there was a problem.
return cmd_response_status;
}
}
// No I/O error, but no response sent back in time.
return HCI_RESPONSE_TIMEOUT;
}
hci_result_t hci_send_acl_pkt(uint16_t handle, uint8_t cid, uint16_t data_len, uint8_t *data) {
// Wait for all backlogged packets to finish.
while (pending_pkt >= common_hal_bleio_adapter_obj.max_acl_num_buffers) {
// RUN_BACKGROUND_TASKS includes hci_poll_for_incoming_pkt();
RUN_BACKGROUND_TASKS;
}
// buf_len is size of entire packet including header.
const size_t buf_len = sizeof(h4_hci_acl_pkt_t) + sizeof(acl_data_t) + data_len;
uint8_t tx_buffer[buf_len];
h4_hci_acl_pkt_t *acl_pkt = (h4_hci_acl_pkt_t *)tx_buffer;
acl_data_t *acl_data = (acl_data_t *)acl_pkt->data;
acl_pkt->pkt_type = H4_ACL;
acl_pkt->handle = handle;
acl_pkt->pb = ACL_DATA_PB_FIRST_FLUSH;
acl_pkt->bc = 0;
acl_pkt->data_len = (uint16_t)(sizeof(acl_data_t) + data_len);
acl_data->acl_data_len = data_len;
acl_data->cid = cid;
memcpy(&acl_data->acl_data, data, data_len);
#if HCI_DEBUG
dump_acl_pkt(true, buf_len, tx_buffer);
#endif
pending_pkt++;
int errcode = 0;
common_hal_busio_uart_write(common_hal_bleio_adapter_obj.hci_uart, tx_buffer, buf_len, &errcode);
if (errcode) {
return HCI_WRITE_ERROR;
}
return HCI_OK;
}
hci_result_t hci_reset(void) {
return send_command(BT_HCI_OP_RESET, 0, NULL);
}
hci_result_t hci_read_local_version(uint8_t *hci_version, uint16_t *hci_revision, uint8_t *lmp_version, uint16_t *manufacturer, uint16_t *lmp_subversion) {
hci_result_t result = send_command(BT_HCI_OP_READ_LOCAL_VERSION_INFO, 0, NULL);
if (result == HCI_OK) {
struct bt_hci_rp_read_local_version_info *response =
(struct bt_hci_rp_read_local_version_info *)cmd_response_data;
*hci_version = response->hci_version;
*hci_revision = response->hci_revision;
*lmp_version = response->lmp_version;
*manufacturer = response->manufacturer;
*lmp_subversion = response->lmp_subversion;
}
return result;
}
hci_result_t hci_read_bd_addr(bt_addr_t *addr) {
int result = send_command(BT_HCI_OP_READ_BD_ADDR, 0, NULL);
if (result == HCI_OK) {
struct bt_hci_rp_read_bd_addr *response = (struct bt_hci_rp_read_bd_addr *)cmd_response_data;
memcpy(addr->val, response->bdaddr.val, sizeof_field(bt_addr_t, val));
}
return result;
}
hci_result_t hci_read_rssi(uint16_t handle, int *rssi) {
int result = send_command(BT_HCI_OP_READ_RSSI, sizeof(handle), &handle);
if (result == HCI_OK) {
struct bt_hci_rp_read_rssi *response = (struct bt_hci_rp_read_rssi *)cmd_response_data;
*rssi = response->rssi;
}
return result;
}
hci_result_t hci_set_event_mask(uint64_t event_mask) {
return send_command(BT_HCI_OP_SET_EVENT_MASK, sizeof(event_mask), &event_mask);
}
hci_result_t hci_le_read_buffer_size(uint16_t *le_max_len, uint8_t *le_max_num) {
int result = send_command(BT_HCI_OP_LE_READ_BUFFER_SIZE, 0, NULL);
if (result == HCI_OK) {
struct bt_hci_rp_le_read_buffer_size *response =
(struct bt_hci_rp_le_read_buffer_size *)cmd_response_data;
*le_max_len = response->le_max_len;
*le_max_num = response->le_max_num;
}
return result;
}
hci_result_t hci_read_buffer_size(uint16_t *acl_max_len, uint8_t *sco_max_len, uint16_t *acl_max_num, uint16_t *sco_max_num) {
int result = send_command(BT_HCI_OP_READ_BUFFER_SIZE, 0, NULL);
if (result == HCI_OK) {
struct bt_hci_rp_read_buffer_size *response =
(struct bt_hci_rp_read_buffer_size *)cmd_response_data;
*acl_max_len = response->acl_max_len;
*sco_max_len = response->sco_max_len;
*acl_max_num = response->acl_max_num;
*sco_max_num = response->sco_max_num;
}
return result;
}
hci_result_t hci_le_set_random_address(uint8_t addr[6]) {
return send_command(BT_HCI_OP_LE_SET_RANDOM_ADDRESS, 6, addr);
}
hci_result_t hci_le_set_advertising_parameters(uint16_t min_interval, uint16_t max_interval, uint8_t type, uint8_t own_addr_type, bt_addr_le_t *direct_addr, uint8_t channel_map, uint8_t filter_policy) {
struct bt_hci_cp_le_set_adv_param params = {
.min_interval = min_interval,
.max_interval = max_interval,
.type = type,
.own_addr_type = own_addr_type,
// .direct_addr set below.
.channel_map = channel_map,
.filter_policy = filter_policy,
};
params.direct_addr.type = direct_addr->type;
memcpy(params.direct_addr.a.val, direct_addr->a.val, sizeof(params.direct_addr.a.val));
return send_command(BT_HCI_OP_LE_SET_ADV_PARAM, sizeof(params), &params);
}
hci_result_t hci_le_set_extended_advertising_parameters(uint8_t handle, uint16_t props, uint32_t prim_min_interval, uint32_t prim_max_interval, uint8_t prim_channel_map, uint8_t own_addr_type, bt_addr_le_t *peer_addr, uint8_t filter_policy, int8_t tx_power, uint8_t prim_adv_phy, uint8_t sec_adv_max_skip, uint8_t sec_adv_phy, uint8_t sid, uint8_t scan_req_notify_enable) {
struct bt_hci_cp_le_set_ext_adv_param params = {
.handle = handle,
.props = props,
// .prim_min_interval and .prim_max_interval set below
.prim_channel_map = prim_channel_map,
.own_addr_type = own_addr_type,
// .peer_addr set below.
.tx_power = tx_power,
.sec_adv_max_skip = sec_adv_max_skip,
.sec_adv_phy = sec_adv_phy,
.sid = sid,
.scan_req_notify_enable = scan_req_notify_enable,
};
// Assumes little-endian.
memcpy(params.prim_min_interval, (void *)&prim_min_interval,
sizeof_field(struct bt_hci_cp_le_set_ext_adv_param, prim_min_interval));
memcpy(params.prim_max_interval, (void *)&prim_max_interval,
sizeof_field(struct bt_hci_cp_le_set_ext_adv_param, prim_max_interval));
memcpy(params.peer_addr.a.val, peer_addr->a.val, sizeof_field(bt_addr_le_t, a.val));
return send_command(BT_HCI_OP_LE_SET_EXT_ADV_PARAM, sizeof(params), &params);
}
hci_result_t hci_le_read_maximum_advertising_data_length(uint16_t *max_adv_data_len) {
int result = send_command(BT_HCI_OP_LE_READ_MAX_ADV_DATA_LEN, 0, NULL);
if (result == HCI_OK) {
struct bt_hci_rp_le_read_max_adv_data_len *response =
(struct bt_hci_rp_le_read_max_adv_data_len *)cmd_response_data;
*max_adv_data_len = response->max_adv_data_len;
}
return result;
}
hci_result_t hci_le_read_local_supported_features(uint8_t features[8]) {
int result = send_command(BT_HCI_OP_LE_READ_LOCAL_FEATURES, 0, NULL);
if (result == HCI_OK) {
struct bt_hci_rp_le_read_local_features *response =
(struct bt_hci_rp_le_read_local_features *)cmd_response_data;
memcpy(features, response->features,
sizeof_field(struct bt_hci_rp_le_read_local_features, features));
}
return result;
}
hci_result_t hci_le_set_advertising_data(uint8_t len, uint8_t data[]) {
struct bt_hci_cp_le_set_adv_data params = {
// Zero out unused data bytes.
.data = { 0 },
};
params.len = len;
memcpy(params.data, data, len);
// All data bytes are sent even if some are unused.
return send_command(BT_HCI_OP_LE_SET_ADV_DATA, sizeof(params), &params);
}
hci_result_t hci_le_set_extended_advertising_data(uint8_t handle, uint8_t op, uint8_t frag_pref, uint8_t len, uint8_t data[]) {
const uint8_t max_len = sizeof_field(struct bt_hci_cp_le_set_ext_adv_data, data);
uint8_t valid_len = MIN(len, max_len);
struct bt_hci_cp_le_set_ext_adv_data params = {
.handle = handle,
.op = op,
.frag_pref = frag_pref,
.len = valid_len,
};
memcpy(params.data, data, valid_len);
return send_command(BT_HCI_OP_LE_SET_EXT_ADV_DATA, sizeof(params) - (max_len - valid_len), &params);
}
hci_result_t hci_le_set_scan_response_data(uint8_t len, uint8_t data[]) {
struct bt_hci_cp_le_set_scan_rsp_data params = {
// Zero out unused data bytes.
.data = { 0 },
};
params.len = len;
memcpy(params.data, data, len);
// All data bytes are sent even if some are unused.
return send_command(BT_HCI_OP_LE_SET_SCAN_RSP_DATA, sizeof(params), &params);
}
hci_result_t hci_le_set_advertising_enable(uint8_t enable) {
return send_command(BT_HCI_OP_LE_SET_ADV_ENABLE, sizeof(enable), &enable);
}
hci_result_t hci_le_set_extended_advertising_enable(uint8_t enable, uint8_t set_num, uint8_t handle[], uint16_t duration[], uint8_t max_ext_adv_evts[]) {
uint8_t params[sizeof(struct bt_hci_cp_le_set_ext_adv_enable) +
set_num * (sizeof(struct bt_hci_ext_adv_set))];
struct bt_hci_cp_le_set_ext_adv_enable *params_p = (struct bt_hci_cp_le_set_ext_adv_enable *)&params;
params_p->enable = enable;
params_p->set_num = set_num;
for (size_t i = 0; i < set_num; i++) {
params_p->s[i].handle = handle[i];
params_p->s[i].duration = duration[i];
params_p->s[i].max_ext_adv_evts = max_ext_adv_evts[i];
}
return send_command(BT_HCI_OP_LE_SET_EXT_ADV_ENABLE, sizeof(params), &params);
}
hci_result_t hci_le_set_scan_parameters(uint8_t scan_type, uint16_t interval, uint16_t window, uint8_t addr_type, uint8_t filter_policy) {
struct bt_hci_cp_le_set_scan_param params = {
.scan_type = scan_type,
.interval = interval,
.window = window,
.addr_type = addr_type,
.filter_policy = filter_policy,
};
return send_command(BT_HCI_OP_LE_SET_SCAN_PARAM, sizeof(params), &params);
}
hci_result_t hci_le_set_scan_enable(uint8_t enable, uint8_t filter_dup) {
struct bt_hci_cp_le_set_scan_enable params = {
.enable = enable,
.filter_dup = filter_dup,
};
return send_command(BT_HCI_OP_LE_SET_SCAN_ENABLE, sizeof(params), &params);
}
hci_result_t hci_le_create_conn(uint16_t scan_interval, uint16_t scan_window, uint8_t filter_policy, bt_addr_le_t *peer_addr, uint8_t own_addr_type, uint16_t conn_interval_min, uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout, uint16_t min_ce_len, uint16_t max_ce_len) {
struct bt_hci_cp_le_create_conn params = {
.scan_interval = scan_interval,
.scan_window = scan_window,
.filter_policy = filter_policy,
// .peer_addr is set below
.own_addr_type = own_addr_type,
.conn_interval_min = conn_interval_min,
.conn_interval_max = conn_interval_max,
.conn_latency = conn_latency,
.supervision_timeout = supervision_timeout,
.min_ce_len = min_ce_len,
.max_ce_len = max_ce_len,
};
params.peer_addr.type = peer_addr->type;
memcpy(params.peer_addr.a.val, peer_addr->a.val, sizeof(params.peer_addr.a.val));
return send_command(BT_HCI_OP_LE_CREATE_CONN, sizeof(params), &params);
}
hci_result_t hci_le_cancel_conn(void) {
return send_command(BT_HCI_OP_CONNECT_CANCEL, 0, NULL);
}
hci_result_t hci_le_conn_update(uint16_t handle, uint16_t conn_interval_min, uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout) {
struct hci_cp_le_conn_update params = {
.handle = handle,
.conn_interval_min = conn_interval_min,
.conn_interval_max = conn_interval_max,
.conn_latency = conn_latency,
.supervision_timeout = supervision_timeout,
.min_ce_len = 4,
.max_ce_len = 6,
};
return send_command(BT_HCI_OP_LE_CONN_UPDATE, sizeof(params), &params);
}
hci_result_t hci_disconnect(uint16_t handle) {
struct bt_hci_cp_disconnect params = {
.handle = handle,
.reason = BT_HCI_ERR_REMOTE_USER_TERM_CONN,
};
return send_command(BT_HCI_OP_DISCONNECT, sizeof(params), &params);
}
void hci_check_error(hci_result_t result) {
switch (result) {
case HCI_OK:
return;
case HCI_RESPONSE_TIMEOUT:
mp_raise_bleio_BluetoothError(translate("Timeout waiting for HCI response"));
return;
case HCI_WRITE_TIMEOUT:
mp_raise_bleio_BluetoothError(translate("Timeout waiting to write HCI request"));
return;
case HCI_READ_ERROR:
mp_raise_bleio_BluetoothError(translate("Error reading from HCI adapter"));
return;
case HCI_WRITE_ERROR:
mp_raise_bleio_BluetoothError(translate("Error writing to HCI adapter"));
return;
case HCI_PACKET_SIZE_ERROR:
mp_raise_RuntimeError(translate("HCI packet size mismatch"));
return;
case HCI_ATT_ERROR:
mp_raise_RuntimeError(translate("Error in ATT protocol code"));
return;
default:
// Should be an HCI status error, > 0.
if (result > 0) {
mp_raise_bleio_BluetoothError(translate("HCI status error: %02x"), result);
} else {
mp_raise_bleio_BluetoothError(translate("Unknown hci_result_t: %d"), result);
}
return;
}
}

81
devices/ble_hci/common-hal/_bleio/hci.h Normal file
View File

@ -0,0 +1,81 @@
/*
This file is part of the ArduinoBLE library.
Copyright (c) 2018 Arduino SA. All rights reserved.
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
#ifndef MICROPY_INCLUDED_DEVICES_BLE_HCI_COMMON_HAL_BLEIO_HCI_H
#define MICROPY_INCLUDED_DEVICES_BLE_HCI_COMMON_HAL_BLEIO_HCI_H
#include <stdint.h>
#include "common-hal/_bleio/hci_include/hci.h"
#include "common-hal/_bleio/hci_include/hci_err.h"
// Incomplete forward declaration to get around mutually-dependent include files.
typedef struct _bleio_adapter_obj_t bleio_adapter_obj_t;
// An hci_result_t is one of the HCI_x values below,
// or it is > 0 and is an HCI command status value (see hci_include/hci_err.h)
typedef int hci_result_t;
#define HCI_OK (0)
#define HCI_RESPONSE_TIMEOUT (-1)
#define HCI_WRITE_TIMEOUT (-2)
#define HCI_READ_ERROR (-3)
#define HCI_WRITE_ERROR (-4)
#define HCI_ATT_ERROR (-5)
#define HCI_PACKET_SIZE_ERROR (-6)
extern void bleio_hci_reset(void);
void hci_check_error(hci_result_t result);
hci_result_t hci_disconnect(uint16_t handle);
hci_result_t hci_le_cancel_conn(void);
hci_result_t hci_le_conn_update(uint16_t handle, uint16_t conn_interval_min, uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout);
hci_result_t hci_le_create_conn(uint16_t scan_interval, uint16_t scan_window, uint8_t filter_policy, bt_addr_le_t *peer_addr, uint8_t own_addr_type, uint16_t conn_interval_min, uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout, uint16_t min_ce_len, uint16_t max_ce_len);
hci_result_t hci_le_read_buffer_size(uint16_t *le_max_len, uint8_t *le_max_num);
hci_result_t hci_le_read_maximum_advertising_data_length(uint16_t *max_adv_data_len);
hci_result_t hci_le_read_local_supported_features(uint8_t features[8]);
hci_result_t hci_le_set_advertising_data(uint8_t length, uint8_t data[]);
hci_result_t hci_le_set_advertising_enable(uint8_t enable);
hci_result_t hci_le_set_advertising_parameters(uint16_t min_interval, uint16_t max_interval, uint8_t type, uint8_t own_addr_type, bt_addr_le_t *direct_addr, uint8_t channel_map, uint8_t filter_policy);
hci_result_t hci_le_set_extended_advertising_data(uint8_t handle, uint8_t op, uint8_t frag_pref, uint8_t len, uint8_t data[]);
hci_result_t hci_le_set_extended_advertising_enable(uint8_t enable, uint8_t set_num, uint8_t handle[], uint16_t duration[], uint8_t max_ext_adv_evts[]);
hci_result_t hci_le_set_extended_advertising_parameters(uint8_t handle, uint16_t props, uint32_t prim_min_interval, uint32_t prim_max_interval, uint8_t prim_channel_map, uint8_t own_addr_type, bt_addr_le_t *peer_addr, uint8_t filter_policy, int8_t tx_power, uint8_t prim_adv_phy, uint8_t sec_adv_max_skip, uint8_t sec_adv_phy, uint8_t sid, uint8_t scan_req_notify_enable);
hci_result_t hci_le_set_random_address(uint8_t addr[6]);
hci_result_t hci_le_set_scan_enable(uint8_t enable, uint8_t filter_dup);
hci_result_t hci_le_set_scan_parameters(uint8_t scan_type, uint16_t interval, uint16_t window, uint8_t addr_type, uint8_t filter_policy);
hci_result_t hci_le_set_scan_response_data(uint8_t length, uint8_t data[]);
hci_result_t hci_poll_for_incoming_pkt(void);
hci_result_t hci_read_bd_addr(bt_addr_t *addr);
hci_result_t hci_read_buffer_size(uint16_t *acl_max_len, uint8_t *sco_max_len, uint16_t *acl_max_num, uint16_t *sco_max_num);
hci_result_t hci_read_local_version(uint8_t *hci_version, uint16_t *hci_revision, uint8_t *lmp_version, uint16_t *manufacturer, uint16_t *lmp_subversion);
hci_result_t hci_read_rssi(uint16_t handle, int *rssi);
hci_result_t hci_reset(void);
hci_result_t hci_send_acl_pkt(uint16_t handle, uint8_t cid, uint16_t data_len, uint8_t *data);
hci_result_t hci_set_event_mask(uint64_t event_mask);
#endif // MICROPY_INCLUDED_DEVICES_BLE_HCI_COMMON_HAL_BLEIO_HCI_H

549
devices/ble_hci/common-hal/_bleio/hci_debug.c Normal file
View File

@ -0,0 +1,549 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2020 Dan Halbert for Adafruit Industries
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
// This file is #include'd in hci.c when HCI_DEBUG is non-zero.
STATIC const char *att_opcode_name(uint16_t opcode) {
switch (opcode) {
case BT_ATT_OP_ERROR_RSP:
return "ERROR_RSP";
case BT_ATT_OP_MTU_REQ:
return "MTU_REQ";
case BT_ATT_OP_MTU_RSP:
return "MTU_RSP";
case BT_ATT_OP_FIND_INFO_REQ:
return "FIND_INFO_REQ";
case BT_ATT_OP_FIND_INFO_RSP:
return "FIND_INFO_RSP";
case BT_ATT_OP_FIND_TYPE_REQ:
return "FIND_TYPE_REQ";
case BT_ATT_OP_FIND_TYPE_RSP:
return "FIND_TYPE_RSP";
case BT_ATT_OP_READ_TYPE_REQ:
return "READ_TYPE_REQ";
case BT_ATT_OP_READ_TYPE_RSP:
return "READ_TYPE_RSP";
case BT_ATT_OP_READ_REQ:
return "READ_REQ";
case BT_ATT_OP_READ_RSP:
return "READ_RSP";
case BT_ATT_OP_READ_BLOB_REQ:
return "READ_BLOB_REQ";
case BT_ATT_OP_READ_BLOB_RSP:
return "READ_BLOB_RSP";
case BT_ATT_OP_READ_MULT_REQ:
return "READ_MULT_REQ";
case BT_ATT_OP_READ_MULT_RSP:
return "READ_MULT_RSP";
case BT_ATT_OP_READ_GROUP_REQ:
return "READ_GROUP_REQ";
case BT_ATT_OP_READ_GROUP_RSP:
return "READ_GROUP_RSP";
case BT_ATT_OP_WRITE_REQ:
return "WRITE_REQ";
case BT_ATT_OP_WRITE_RSP:
return "WRITE_RSP";
case BT_ATT_OP_PREPARE_WRITE_REQ:
return "PREPARE_WRITE_REQ";
case BT_ATT_OP_PREPARE_WRITE_RSP:
return "PREPARE_WRITE_RSP";
case BT_ATT_OP_EXEC_WRITE_REQ:
return "EXEC_WRITE_REQ";
case BT_ATT_OP_EXEC_WRITE_RSP:
return "EXEC_WRITE_RSP";
case BT_ATT_OP_NOTIFY:
return "NOTIFY";
case BT_ATT_OP_INDICATE:
return "INDICATE";
case BT_ATT_OP_CONFIRM:
return "CONFIRM";
case BT_ATT_OP_READ_MULT_VL_REQ:
return "READ_MULT_VL_REQ";
case BT_ATT_OP_READ_MULT_VL_RSP:
return "READ_MULT_VL_RSP";
case BT_ATT_OP_NOTIFY_MULT:
return "NOTIFY_MULT";
case BT_ATT_OP_WRITE_CMD:
return "WRITE_CMD";
case BT_ATT_OP_SIGNED_WRITE_CMD:
return "SIGNED_WRITE_CMD";
default:
return "";
}
}
STATIC const char *hci_evt_name(uint8_t evt) {
switch (evt) {
case BT_HCI_EVT_UNKNOWN:
return "UNKNOWN";
case BT_HCI_EVT_VENDOR:
return "VENDOR";
case BT_HCI_EVT_INQUIRY_COMPLETE:
return "INQUIRY_COMPLETE";
case BT_HCI_EVT_CONN_COMPLETE:
return "CONN_COMPLETE";
case BT_HCI_EVT_CONN_REQUEST:
return "CONN_REQUEST";
case BT_HCI_EVT_DISCONN_COMPLETE:
return "DISCONN_COMPLETE";
case BT_HCI_EVT_AUTH_COMPLETE:
return "AUTH_COMPLETE";
case BT_HCI_EVT_REMOTE_NAME_REQ_COMPLETE:
return "REMOTE_NAME_REQ_COMPLETE";
case BT_HCI_EVT_ENCRYPT_CHANGE:
return "ENCRYPT_CHANGE";
case BT_HCI_EVT_REMOTE_FEATURES:
return "REMOTE_FEATURES";
case BT_HCI_EVT_REMOTE_VERSION_INFO:
return "REMOTE_VERSION_INFO";
case BT_HCI_EVT_CMD_COMPLETE:
return "CMD_COMPLETE";
case BT_HCI_EVT_CMD_STATUS:
return "CMD_STATUS";
case BT_HCI_EVT_ROLE_CHANGE:
return "ROLE_CHANGE";
case BT_HCI_EVT_NUM_COMPLETED_PACKETS:
return "NUM_COMPLETED_PACKETS";
case BT_HCI_EVT_PIN_CODE_REQ:
return "PIN_CODE_REQ";
case BT_HCI_EVT_LINK_KEY_REQ:
return "LINK_KEY_REQ";
case BT_HCI_EVT_LINK_KEY_NOTIFY:
return "LINK_KEY_NOTIFY";
case BT_HCI_EVT_DATA_BUF_OVERFLOW:
return "DATA_BUF_OVERFLOW";
case BT_HCI_EVT_INQUIRY_RESULT_WITH_RSSI:
return "INQUIRY_RESULT_WITH_RSSI";
case BT_HCI_EVT_REMOTE_EXT_FEATURES:
return "REMOTE_EXT_FEATURES";
case BT_HCI_EVT_SYNC_CONN_COMPLETE:
return "SYNC_CONN_COMPLETE";
case BT_HCI_EVT_EXTENDED_INQUIRY_RESULT:
return "EXTENDED_INQUIRY_RESULT";
case BT_HCI_EVT_ENCRYPT_KEY_REFRESH_COMPLETE:
return "ENCRYPT_KEY_REFRESH_COMPLETE";
case BT_HCI_EVT_IO_CAPA_REQ:
return "IO_CAPA_REQ";
case BT_HCI_EVT_IO_CAPA_RESP:
return "IO_CAPA_RESP";
case BT_HCI_EVT_USER_CONFIRM_REQ:
return "USER_CONFIRM_REQ";
case BT_HCI_EVT_USER_PASSKEY_REQ:
return "USER_PASSKEY_REQ";
case BT_HCI_EVT_SSP_COMPLETE:
return "SSP_COMPLETE";
case BT_HCI_EVT_USER_PASSKEY_NOTIFY:
return "USER_PASSKEY_NOTIFY";
case BT_HCI_EVT_LE_META_EVENT:
return "LE_META_EVENT";
case BT_HCI_EVT_AUTH_PAYLOAD_TIMEOUT_EXP:
return "AUTH_PAYLOAD_TIMEOUT_EXP";
default:
return "";
}
}
STATIC const char *hci_evt_le_name(uint8_t evt_le) {
switch (evt_le) {
case BT_HCI_EVT_LE_CONN_COMPLETE:
return "LE_CONN_COMPLETE";
case BT_HCI_EVT_LE_ADVERTISING_REPORT:
return "LE_ADVERTISING_REPORT";
case BT_HCI_EVT_LE_CONN_UPDATE_COMPLETE:
return "LE_CONN_UPDATE_COMPLETE";
case BT_HCI_EVT_LE_LTK_REQUEST:
return "LE_LTK_REQUEST";
case BT_HCI_EVT_LE_CONN_PARAM_REQ:
return "LE_CONN_PARAM_REQ";
case BT_HCI_EVT_LE_DATA_LEN_CHANGE:
return "LE_DATA_LEN_CHANGE";
case BT_HCI_EVT_LE_P256_PUBLIC_KEY_COMPLETE:
return "LE_P256_PUBLIC_KEY_COMPLETE";
case BT_HCI_EVT_LE_GENERATE_DHKEY_COMPLETE:
return "LE_GENERATE_DHKEY_COMPLETE";
case BT_HCI_EVT_LE_ENH_CONN_COMPLETE:
return "LE_ENH_CONN_COMPLETE";
case BT_HCI_EVT_LE_DIRECT_ADV_REPORT:
return "LE_DIRECT_ADV_REPORT";
case BT_HCI_EVT_LE_PHY_UPDATE_COMPLETE:
return "LE_PHY_UPDATE_COMPLETE";
case BT_HCI_EVT_LE_EXT_ADVERTISING_REPORT:
return "LE_EXT_ADVERTISING_REPORT";
case BT_HCI_EVT_LE_PER_ADV_SYNC_ESTABLISHED:
return "LE_PER_ADV_SYNC_ESTABLISHED";
case BT_HCI_EVT_LE_PER_ADVERTISING_REPORT:
return "LE_PER_ADVERTISING_REPORT";
case BT_HCI_EVT_LE_PER_ADV_SYNC_LOST:
return "LE_PER_ADV_SYNC_LOST";
case BT_HCI_EVT_LE_SCAN_TIMEOUT:
return "LE_SCAN_TIMEOUT";
case BT_HCI_EVT_LE_ADV_SET_TERMINATED:
return "LE_ADV_SET_TERMINATED";
case BT_HCI_EVT_LE_SCAN_REQ_RECEIVED:
return "LE_SCAN_REQ_RECEIVED";
case BT_HCI_EVT_LE_CHAN_SEL_ALGO:
return "LE_CHAN_SEL_ALGO";
default:
return "";
}
}
STATIC const char *hci_opcode_name(uint16_t opcode) {
switch (opcode) {
case BT_OP_NOP:
return "NOP";
case BT_HCI_OP_INQUIRY:
return "INQUIRY";
case BT_HCI_OP_INQUIRY_CANCEL:
return "INQUIRY_CANCEL";
case BT_HCI_OP_CONNECT:
return "CONNECT";
case BT_HCI_OP_DISCONNECT:
return "DISCONNECT";
case BT_HCI_OP_CONNECT_CANCEL:
return "CONNECT_CANCEL";
case BT_HCI_OP_ACCEPT_CONN_REQ:
return "ACCEPT_CONN_REQ";
case BT_HCI_OP_SETUP_SYNC_CONN:
return "SETUP_SYNC_CONN";
case BT_HCI_OP_ACCEPT_SYNC_CONN_REQ:
return "ACCEPT_SYNC_CONN_REQ";
case BT_HCI_OP_REJECT_CONN_REQ:
return "REJECT_CONN_REQ";
case BT_HCI_OP_LINK_KEY_REPLY:
return "LINK_KEY_REPLY";
case BT_HCI_OP_LINK_KEY_NEG_REPLY:
return "LINK_KEY_NEG_REPLY";
case BT_HCI_OP_PIN_CODE_REPLY:
return "PIN_CODE_REPLY";
case BT_HCI_OP_PIN_CODE_NEG_REPLY:
return "PIN_CODE_NEG_REPLY";
case BT_HCI_OP_AUTH_REQUESTED:
return "AUTH_REQUESTED";
case BT_HCI_OP_SET_CONN_ENCRYPT:
return "SET_CONN_ENCRYPT";
case BT_HCI_OP_REMOTE_NAME_REQUEST:
return "REMOTE_NAME_REQUEST";
case BT_HCI_OP_REMOTE_NAME_CANCEL:
return "REMOTE_NAME_CANCEL";
case BT_HCI_OP_READ_REMOTE_FEATURES:
return "READ_REMOTE_FEATURES";
case BT_HCI_OP_READ_REMOTE_EXT_FEATURES:
return "READ_REMOTE_EXT_FEATURES";
case BT_HCI_OP_READ_REMOTE_VERSION_INFO:
return "READ_REMOTE_VERSION_INFO";
case BT_HCI_OP_IO_CAPABILITY_REPLY:
return "IO_CAPABILITY_REPLY";
case BT_HCI_OP_USER_CONFIRM_REPLY:
return "USER_CONFIRM_REPLY";
case BT_HCI_OP_USER_CONFIRM_NEG_REPLY:
return "USER_CONFIRM_NEG_REPLY";
case BT_HCI_OP_USER_PASSKEY_REPLY:
return "USER_PASSKEY_REPLY";
case BT_HCI_OP_USER_PASSKEY_NEG_REPLY:
return "USER_PASSKEY_NEG_REPLY";
case BT_HCI_OP_IO_CAPABILITY_NEG_REPLY:
return "IO_CAPABILITY_NEG_REPLY";
case BT_HCI_OP_SET_EVENT_MASK:
return "SET_EVENT_MASK";
case BT_HCI_OP_RESET:
return "RESET";
case BT_HCI_OP_WRITE_LOCAL_NAME:
return "WRITE_LOCAL_NAME";
case BT_HCI_OP_WRITE_PAGE_TIMEOUT:
return "WRITE_PAGE_TIMEOUT";
case BT_HCI_OP_WRITE_SCAN_ENABLE:
return "WRITE_SCAN_ENABLE";
case BT_HCI_OP_READ_TX_POWER_LEVEL:
return "READ_TX_POWER_LEVEL";
case BT_HCI_OP_SET_CTL_TO_HOST_FLOW:
return "SET_CTL_TO_HOST_FLOW";
case BT_HCI_OP_HOST_BUFFER_SIZE:
return "HOST_BUFFER_SIZE";
case BT_HCI_OP_HOST_NUM_COMPLETED_PACKETS:
return "HOST_NUM_COMPLETED_PACKETS";
case BT_HCI_OP_WRITE_INQUIRY_MODE:
return "WRITE_INQUIRY_MODE";
case BT_HCI_OP_WRITE_SSP_MODE:
return "WRITE_SSP_MODE";
case BT_HCI_OP_SET_EVENT_MASK_PAGE_2:
return "SET_EVENT_MASK_PAGE_2";
case BT_HCI_OP_LE_WRITE_LE_HOST_SUPP:
return "LE_WRITE_LE_HOST_SUPP";
case BT_HCI_OP_WRITE_SC_HOST_SUPP:
return "WRITE_SC_HOST_SUPP";
case BT_HCI_OP_READ_AUTH_PAYLOAD_TIMEOUT:
return "READ_AUTH_PAYLOAD_TIMEOUT";
case BT_HCI_OP_WRITE_AUTH_PAYLOAD_TIMEOUT:
return "WRITE_AUTH_PAYLOAD_TIMEOUT";
case BT_HCI_OP_READ_LOCAL_VERSION_INFO:
return "READ_LOCAL_VERSION_INFO";
case BT_HCI_OP_READ_SUPPORTED_COMMANDS:
return "READ_SUPPORTED_COMMANDS";
case BT_HCI_OP_READ_LOCAL_EXT_FEATURES:
return "READ_LOCAL_EXT_FEATURES";
case BT_HCI_OP_READ_LOCAL_FEATURES:
return "READ_LOCAL_FEATURES";
case BT_HCI_OP_READ_BUFFER_SIZE:
return "READ_BUFFER_SIZE";
case BT_HCI_OP_READ_BD_ADDR:
return "READ_BD_ADDR";
case BT_HCI_OP_READ_RSSI:
return "READ_RSSI";
case BT_HCI_OP_READ_ENCRYPTION_KEY_SIZE:
return "READ_ENCRYPTION_KEY_SIZE";
case BT_HCI_OP_LE_SET_EVENT_MASK:
return "LE_SET_EVENT_MASK";
case BT_HCI_OP_LE_READ_BUFFER_SIZE:
return "LE_READ_BUFFER_SIZE";
case BT_HCI_OP_LE_READ_LOCAL_FEATURES:
return "LE_READ_LOCAL_FEATURES";
case BT_HCI_OP_LE_SET_RANDOM_ADDRESS:
return "LE_SET_RANDOM_ADDRESS";
case BT_HCI_OP_LE_SET_ADV_PARAM:
return "LE_SET_ADV_PARAM";
case BT_HCI_OP_LE_READ_ADV_CHAN_TX_POWER:
return "LE_READ_ADV_CHAN_TX_POWER";
case BT_HCI_OP_LE_SET_ADV_DATA:
return "LE_SET_ADV_DATA";
case BT_HCI_OP_LE_SET_SCAN_RSP_DATA:
return "LE_SET_SCAN_RSP_DATA";
case BT_HCI_OP_LE_SET_ADV_ENABLE:
return "LE_SET_ADV_ENABLE";
case BT_HCI_OP_LE_SET_SCAN_PARAM:
return "LE_SET_SCAN_PARAM";
case BT_HCI_OP_LE_SET_SCAN_ENABLE:
return "LE_SET_SCAN_ENABLE";
case BT_HCI_OP_LE_CREATE_CONN:
return "LE_CREATE_CONN";
case BT_HCI_OP_LE_CREATE_CONN_CANCEL:
return "LE_CREATE_CONN_CANCEL";
case BT_HCI_OP_LE_READ_WL_SIZE:
return "LE_READ_WL_SIZE";
case BT_HCI_OP_LE_CLEAR_WL:
return "LE_CLEAR_WL";
case BT_HCI_OP_LE_ADD_DEV_TO_WL:
return "LE_ADD_DEV_TO_WL";
case BT_HCI_OP_LE_REM_DEV_FROM_WL:
return "LE_REM_DEV_FROM_WL";
case BT_HCI_OP_LE_CONN_UPDATE:
return "LE_CONN_UPDATE";
case BT_HCI_OP_LE_SET_HOST_CHAN_CLASSIF:
return "LE_SET_HOST_CHAN_CLASSIF";
case BT_HCI_OP_LE_READ_CHAN_MAP:
return "LE_READ_CHAN_MAP";
case BT_HCI_OP_LE_READ_REMOTE_FEATURES:
return "LE_READ_REMOTE_FEATURES";
case BT_HCI_OP_LE_ENCRYPT:
return "LE_ENCRYPT";
case BT_HCI_OP_LE_RAND:
return "LE_RAND";
case BT_HCI_OP_LE_START_ENCRYPTION:
return "LE_START_ENCRYPTION";
case BT_HCI_OP_LE_LTK_REQ_REPLY:
return "LE_LTK_REQ_REPLY";
case BT_HCI_OP_LE_LTK_REQ_NEG_REPLY:
return "LE_LTK_REQ_NEG_REPLY";
case BT_HCI_OP_LE_READ_SUPP_STATES:
return "LE_READ_SUPP_STATES";
case BT_HCI_OP_LE_RX_TEST:
return "LE_RX_TEST";
case BT_HCI_OP_LE_TX_TEST:
return "LE_TX_TEST";
case BT_HCI_OP_LE_TEST_END:
return "LE_TEST_END";
case BT_HCI_OP_LE_CONN_PARAM_REQ_REPLY:
return "LE_CONN_PARAM_REQ_REPLY";
case BT_HCI_OP_LE_CONN_PARAM_REQ_NEG_REPLY:
return "LE_CONN_PARAM_REQ_NEG_REPLY";
case BT_HCI_OP_LE_SET_DATA_LEN:
return "LE_SET_DATA_LEN";
case BT_HCI_OP_LE_READ_DEFAULT_DATA_LEN:
return "LE_READ_DEFAULT_DATA_LEN";
case BT_HCI_OP_LE_WRITE_DEFAULT_DATA_LEN:
return "LE_WRITE_DEFAULT_DATA_LEN";
case BT_HCI_OP_LE_P256_PUBLIC_KEY:
return "LE_P256_PUBLIC_KEY";
case BT_HCI_OP_LE_GENERATE_DHKEY:
return "LE_GENERATE_DHKEY";
case BT_HCI_OP_LE_ADD_DEV_TO_RL:
return "LE_ADD_DEV_TO_RL";
case BT_HCI_OP_LE_REM_DEV_FROM_RL:
return "LE_REM_DEV_FROM_RL";
case BT_HCI_OP_LE_CLEAR_RL:
return "LE_CLEAR_RL";
case BT_HCI_OP_LE_READ_RL_SIZE:
return "LE_READ_RL_SIZE";
case BT_HCI_OP_LE_READ_PEER_RPA:
return "LE_READ_PEER_RPA";
case BT_HCI_OP_LE_READ_LOCAL_RPA:
return "LE_READ_LOCAL_RPA";
case BT_HCI_OP_LE_SET_ADDR_RES_ENABLE:
return "LE_SET_ADDR_RES_ENABLE";
case BT_HCI_OP_LE_SET_RPA_TIMEOUT:
return "LE_SET_RPA_TIMEOUT";
case BT_HCI_OP_LE_READ_MAX_DATA_LEN:
return "LE_READ_MAX_DATA_LEN";
case BT_HCI_OP_LE_READ_PHY:
return "LE_READ_PHY";
case BT_HCI_OP_LE_SET_DEFAULT_PHY:
return "LE_SET_DEFAULT_PHY";
case BT_HCI_OP_LE_SET_PHY:
return "LE_SET_PHY";
case BT_HCI_OP_LE_ENH_RX_TEST:
return "LE_ENH_RX_TEST";
case BT_HCI_OP_LE_ENH_TX_TEST:
return "LE_ENH_TX_TEST";
case BT_HCI_OP_LE_SET_ADV_SET_RANDOM_ADDR:
return "LE_SET_ADV_SET_RANDOM_ADDR";
case BT_HCI_OP_LE_SET_EXT_ADV_PARAM:
return "LE_SET_EXT_ADV_PARAM";
case BT_HCI_OP_LE_SET_EXT_ADV_DATA:
return "LE_SET_EXT_ADV_DATA";
case BT_HCI_OP_LE_SET_EXT_SCAN_RSP_DATA:
return "LE_SET_EXT_SCAN_RSP_DATA";
case BT_HCI_OP_LE_SET_EXT_ADV_ENABLE:
return "LE_SET_EXT_ADV_ENABLE";
case BT_HCI_OP_LE_READ_MAX_ADV_DATA_LEN:
return "LE_READ_MAX_ADV_DATA_LEN";
case BT_HCI_OP_LE_READ_NUM_ADV_SETS:
return "LE_READ_NUM_ADV_SETS";
case BT_HCI_OP_LE_REMOVE_ADV_SET:
return "LE_REMOVE_ADV_SET";
case BT_HCI_OP_CLEAR_ADV_SETS:
return "CLEAR_ADV_SETS";
case BT_HCI_OP_LE_SET_PER_ADV_PARAM:
return "LE_SET_PER_ADV_PARAM";
case BT_HCI_OP_LE_SET_PER_ADV_DATA:
return "LE_SET_PER_ADV_DATA";
case BT_HCI_OP_LE_SET_PER_ADV_ENABLE:
return "LE_SET_PER_ADV_ENABLE";
case BT_HCI_OP_LE_SET_EXT_SCAN_PARAM:
return "LE_SET_EXT_SCAN_PARAM";
case BT_HCI_OP_LE_SET_EXT_SCAN_ENABLE:
return "LE_SET_EXT_SCAN_ENABLE";
case BT_HCI_OP_LE_EXT_CREATE_CONN:
return "LE_EXT_CREATE_CONN";
case BT_HCI_OP_LE_PER_ADV_CREATE_SYNC:
return "LE_PER_ADV_CREATE_SYNC";
case BT_HCI_OP_LE_PER_ADV_CREATE_SYNC_CANCEL:
return "LE_PER_ADV_CREATE_SYNC_CANCEL";
case BT_HCI_OP_LE_PER_ADV_TERMINATE_SYNC:
return "LE_PER_ADV_TERMINATE_SYNC";
case BT_HCI_OP_LE_ADD_DEV_TO_PER_ADV_LIST:
return "LE_ADD_DEV_TO_PER_ADV_LIST";
case BT_HCI_OP_LE_REM_DEV_FROM_PER_ADV_LIST:
return "LE_REM_DEV_FROM_PER_ADV_LIST";
case BT_HCI_OP_LE_CLEAR_PER_ADV_LIST:
return "LE_CLEAR_PER_ADV_LIST";
case BT_HCI_OP_LE_READ_PER_ADV_LIST_SIZE:
return "LE_READ_PER_ADV_LIST_SIZE";
case BT_HCI_OP_LE_READ_TX_POWER:
return "LE_READ_TX_POWER";
case BT_HCI_OP_LE_READ_RF_PATH_COMP:
return "LE_READ_RF_PATH_COMP";
case BT_HCI_OP_LE_WRITE_RF_PATH_COMP:
return "LE_WRITE_RF_PATH_COMP";
case BT_HCI_OP_LE_SET_PRIVACY_MODE:
return "LE_SET_PRIVACY_MODE";
default:
return "";
}
}
STATIC void dump_cmd_pkt(bool tx, uint8_t pkt_len, uint8_t pkt_data[]) {
h4_hci_cmd_pkt_t *pkt = (h4_hci_cmd_pkt_t *)pkt_data;
mp_printf(&mp_plat_print,
"%s HCI COMMAND (%x) op: %s (%04x), len: %d, data: ",
tx ? "TX->" : "RX<-",
pkt->pkt_type,
hci_opcode_name(pkt->opcode), pkt->opcode, pkt->param_len);
for (size_t i = 0; i < pkt->param_len; i++) {
mp_printf(&mp_plat_print, "%02x ", pkt->params[i]);
}
if (pkt_len != sizeof(h4_hci_cmd_pkt_t) + pkt->param_len) {
mp_printf(&mp_plat_print, " LENGTH MISMATCH, pkt_len: %d", pkt_len);
}
mp_printf(&mp_plat_print, "\n");
}
STATIC void dump_acl_pkt(bool tx, uint8_t pkt_len, uint8_t pkt_data[]) {
h4_hci_acl_pkt_t *pkt = (h4_hci_acl_pkt_t *)pkt_data;
acl_data_t *acl = (acl_data_t *)pkt->data;
mp_printf(&mp_plat_print,
"%s HCI ACLDATA (%x) ",
tx ? "TX->" : "RX<-", pkt->pkt_type);
if (pkt->pb != ACL_DATA_PB_MIDDLE && acl->cid == BT_L2CAP_CID_ATT) {
// This is the start of a fragmented acl_data packet or is a full packet,
// and is an ATT protocol packet.
mp_printf(&mp_plat_print, "att: %s (%02x), ", att_opcode_name(acl->acl_data[0]), acl->acl_data[0]);
}
mp_printf(&mp_plat_print,
"handle: %04x, pb: %d, bc: %d, data_len: %d, ",
pkt->handle, pkt->pb, pkt->bc, pkt->data_len);
if (pkt->pb != ACL_DATA_PB_MIDDLE) {
// This is the start of a fragmented acl_data packet or is a full packet.
mp_printf(&mp_plat_print,
"acl data_len: %d, cid: %04x, data: ",
acl->acl_data_len, acl->cid);
for (size_t i = 0; i < acl->acl_data_len; i++) {
mp_printf(&mp_plat_print, "%02x ", acl->acl_data[i]);
}
} else {
for (size_t i = 0; i < pkt->data_len; i++) {
mp_printf(&mp_plat_print, "more data: %02x ", pkt->data[i]);
}
}
if (pkt_len != sizeof(h4_hci_acl_pkt_t) + pkt->data_len) {
mp_printf(&mp_plat_print, " LENGTH MISMATCH, pkt_len: %d", pkt_len);
}
mp_printf(&mp_plat_print, "\n");
}
STATIC void dump_evt_pkt(bool tx, uint8_t pkt_len, uint8_t pkt_data[]) {
h4_hci_evt_pkt_t *pkt = (h4_hci_evt_pkt_t *)pkt_data;
mp_printf(&mp_plat_print,
"%s HCI EVENT (%x) evt: %s (%02x), param_len: %d, data: ",
tx ? "TX->" : "RX<-",
pkt->pkt_type,
pkt->evt == BT_HCI_EVT_LE_META_EVENT
? hci_evt_le_name(pkt->params[0])
: hci_evt_name(pkt->evt),
pkt->evt, pkt->param_len);
for (size_t i = 0; i < pkt->param_len; i++) {
mp_printf(&mp_plat_print, "%02x ", pkt->params[i]);
}
if (pkt_len != sizeof(h4_hci_evt_pkt_t) + pkt->param_len) {
mp_printf(&mp_plat_print, " LENGTH MISMATCH, pkt_len: %d", pkt_len);
}
mp_printf(&mp_plat_print, "\n");
}

2
devices/ble_hci/common-hal/_bleio/hci_include/NOTE.txt Normal file
View File

@ -0,0 +1,2 @@
The HCI-related include files here were copied from the Zephyr project, from this commit:
https://github.com/zephyrproject-rtos/zephyr/tree/0a87f9359edf1ec1c169626df3e19c2b4a4e9646/include/bluetooth

95
devices/ble_hci/common-hal/_bleio/hci_include/addr.h Normal file
View File

@ -0,0 +1,95 @@
// CircuitPython: Adapted from Zephyer include files.
/** @file
* @brief Bluetooth device address definitions and utilities.
*/
/*
* Copyright (c) 2019 Nordic Semiconductor ASA
* Copyright 2020 Dan Halbert for Adafruit Industries
*
* SPDX-License-Identifier: Apache-2.0
*/
#ifndef ZEPHYR_INCLUDE_BLUETOOTH_ADDR_H_
#define ZEPHYR_INCLUDE_BLUETOOTH_ADDR_H_
#include <stdbool.h>
#include <string.h>
/**
* @brief Bluetooth device address definitions and utilities.
* @defgroup bt_addr Device Address
* @ingroup bluetooth
* @{
*/
#define BT_ADDR_LE_PUBLIC 0x00
#define BT_ADDR_LE_RANDOM 0x01
#define BT_ADDR_LE_PUBLIC_ID 0x02
#define BT_ADDR_LE_RANDOM_ID 0x03
/** Bluetooth Device Address */
typedef struct {
uint8_t val[6];
} bt_addr_t;
/** Bluetooth LE Device Address */
typedef struct {
uint8_t type;
bt_addr_t a;
} bt_addr_le_t;
#define BT_ADDR_ANY ((bt_addr_t[]) { { { 0, 0, 0, 0, 0, 0 } } })
#define BT_ADDR_NONE ((bt_addr_t[]) { { \
{ 0xff, 0xff, 0xff, 0xff, 0xff, 0xff } } })
#define BT_ADDR_LE_ANY ((bt_addr_le_t[]) { { 0, { { 0, 0, 0, 0, 0, 0 } } } })
#define BT_ADDR_LE_NONE ((bt_addr_le_t[]) { { 0, \
{ { 0xff, 0xff, 0xff, 0xff, 0xff, 0xff } } } })
static inline int bt_addr_cmp(const bt_addr_t *a, const bt_addr_t *b) {
return memcmp(a, b, sizeof(*a));
}
static inline int bt_addr_le_cmp(const bt_addr_le_t *a, const bt_addr_le_t *b) {
return memcmp(a, b, sizeof(*a));
}
static inline void bt_addr_copy(bt_addr_t *dst, const bt_addr_t *src) {
memcpy(dst, src, sizeof(*dst));
}
static inline void bt_addr_le_copy(bt_addr_le_t *dst, const bt_addr_le_t *src) {
memcpy(dst, src, sizeof(*dst));
}
#define BT_ADDR_IS_RPA(a) (((a)->val[5] & 0xc0) == 0x40)
#define BT_ADDR_IS_NRPA(a) (((a)->val[5] & 0xc0) == 0x00)
#define BT_ADDR_IS_STATIC(a) (((a)->val[5] & 0xc0) == 0xc0)
#define BT_ADDR_SET_RPA(a) ((a)->val[5] = (((a)->val[5] & 0x3f) | 0x40))
#define BT_ADDR_SET_NRPA(a) ((a)->val[5] &= 0x3f)
#define BT_ADDR_SET_STATIC(a) ((a)->val[5] |= 0xc0)
int bt_addr_le_create_nrpa(bt_addr_le_t *addr);
int bt_addr_le_create_static(bt_addr_le_t *addr);
static inline bool bt_addr_le_is_rpa(const bt_addr_le_t *addr) {
if (addr->type != BT_ADDR_LE_RANDOM) {
return false;
}
return BT_ADDR_IS_RPA(&addr->a);
}
static inline bool bt_addr_le_is_identity(const bt_addr_le_t *addr) {
if (addr->type == BT_ADDR_LE_PUBLIC) {
return true;
}
return BT_ADDR_IS_STATIC(&addr->a);
}
/**
* @}
*/
#endif /* ZEPHYR_INCLUDE_BLUETOOTH_ADDR_H_ */

41
devices/ble_hci/common-hal/_bleio/hci_include/att.h Normal file
View File

@ -0,0 +1,41 @@
// CircuitPython: Adapted from Zephyr include file.
/** @file
* @brief Attribute Protocol handling.
*/
/*
* Copyright (c) 2016 Intel Corporation
*
* SPDX-License-Identifier: Apache-2.0
*/
#ifndef ZEPHYR_INCLUDE_BLUETOOTH_ATT_H_
#define ZEPHYR_INCLUDE_BLUETOOTH_ATT_H_
/* Error codes for Error response PDU */
#define BT_ATT_ERR_INVALID_HANDLE 0x01
#define BT_ATT_ERR_READ_NOT_PERMITTED 0x02
#define BT_ATT_ERR_WRITE_NOT_PERMITTED 0x03
#define BT_ATT_ERR_INVALID_PDU 0x04
#define BT_ATT_ERR_AUTHENTICATION 0x05
#define BT_ATT_ERR_NOT_SUPPORTED 0x06
#define BT_ATT_ERR_INVALID_OFFSET 0x07
#define BT_ATT_ERR_AUTHORIZATION 0x08
#define BT_ATT_ERR_PREPARE_QUEUE_FULL 0x09
#define BT_ATT_ERR_ATTRIBUTE_NOT_FOUND 0x0a
#define BT_ATT_ERR_ATTRIBUTE_NOT_LONG 0x0b
#define BT_ATT_ERR_ENCRYPTION_KEY_SIZE 0x0c
#define BT_ATT_ERR_INVALID_ATTRIBUTE_LEN 0x0d
#define BT_ATT_ERR_UNLIKELY 0x0e
#define BT_ATT_ERR_INSUFFICIENT_ENCRYPTION 0x0f
#define BT_ATT_ERR_UNSUPPORTED_GROUP_TYPE 0x10
#define BT_ATT_ERR_INSUFFICIENT_RESOURCES 0x11
#define BT_ATT_ERR_DB_OUT_OF_SYNC 0x12
#define BT_ATT_ERR_VALUE_NOT_ALLOWED 0x13
/* Common Profile Error Codes (from CSS) */
#define BT_ATT_ERR_WRITE_REQ_REJECTED 0xfc
#define BT_ATT_ERR_CCC_IMPROPER_CONF 0xfd
#define BT_ATT_ERR_PROCEDURE_IN_PROGRESS 0xfe
#define BT_ATT_ERR_OUT_OF_RANGE 0xff
#endif /* ZEPHYR_INCLUDE_BLUETOOTH_ATT_H_ */

272
devices/ble_hci/common-hal/_bleio/hci_include/att_internal.h Normal file
View File

@ -0,0 +1,272 @@
// CircuitPython: Adapted from Zephyr include file.
/* att_internal.h - Attribute protocol handling */
/*
* Copyright (c) 2015-2016 Intel Corporation
*
* SPDX-License-Identifier: Apache-2.0
*/
#include <stdbool.h>
// for __packed
#include <sys/cdefs.h>
#define BT_EATT_PSM 0x27
#define BT_ATT_DEFAULT_LE_MTU 23
#define BT_ATT_TIMEOUT K_SECONDS(30)
// FIX #if BT_L2CAP_RX_MTU < CONFIG_BT_L2CAP_TX_MTU
// #define BT_ATT_MTU BT_L2CAP_RX_MTU
// #else
// #define BT_ATT_MTU CONFIG_BT_L2CAP_TX_MTU
// #endif
struct bt_att_hdr {
uint8_t code;
} __packed;
#define BT_ATT_OP_ERROR_RSP 0x01
struct bt_att_error_rsp {
uint8_t request;
uint16_t handle;
uint8_t error;
} __packed;
#define BT_ATT_OP_MTU_REQ 0x02
struct bt_att_exchange_mtu_req {
uint16_t mtu;
} __packed;
#define BT_ATT_OP_MTU_RSP 0x03
struct bt_att_exchange_mtu_rsp {
uint16_t mtu;
} __packed;
/* Find Information Request */
#define BT_ATT_OP_FIND_INFO_REQ 0x04
struct bt_att_find_info_req {
uint16_t start_handle;
uint16_t end_handle;
} __packed;
/* Format field values for BT_ATT_OP_FIND_INFO_RSP */
#define BT_ATT_INFO_16 0x01
#define BT_ATT_INFO_128 0x02
struct bt_att_info_16 {
uint16_t handle;
uint16_t uuid;
} __packed;
struct bt_att_info_128 {
uint16_t handle;
uint8_t uuid[16];
} __packed;
/* Find Information Response */
#define BT_ATT_OP_FIND_INFO_RSP 0x05
struct bt_att_find_info_rsp {
uint8_t format;
uint8_t info[];
} __packed;
/* Find By Type Value Request */
#define BT_ATT_OP_FIND_TYPE_REQ 0x06
struct bt_att_find_type_req {
uint16_t start_handle;
uint16_t end_handle;
uint16_t type;
uint8_t value[];
} __packed;
struct bt_att_handle_group {
uint16_t start_handle;
uint16_t end_handle;
} __packed;
/* Find By Type Value Response */
#define BT_ATT_OP_FIND_TYPE_RSP 0x07
struct bt_att_find_type_rsp {
uint8_t _dummy[0];
struct bt_att_handle_group list[];
} __packed;
/* Read By Type Request */
#define BT_ATT_OP_READ_TYPE_REQ 0x08
struct bt_att_read_type_req {
uint16_t start_handle;
uint16_t end_handle;
uint8_t uuid[];
} __packed;
struct bt_att_data {
uint16_t handle;
uint8_t value[];
} __packed;
/* Read By Type Response */
#define BT_ATT_OP_READ_TYPE_RSP 0x09
struct bt_att_read_type_rsp {
uint8_t len;
struct bt_att_data data[];
} __packed;
/* Read Request */
#define BT_ATT_OP_READ_REQ 0x0a
struct bt_att_read_req {
uint16_t handle;
} __packed;
/* Read Response */
#define BT_ATT_OP_READ_RSP 0x0b
struct bt_att_read_rsp {
uint8_t _dummy[0];
uint8_t value[];
} __packed;
/* Read Blob Request */
#define BT_ATT_OP_READ_BLOB_REQ 0x0c
struct bt_att_read_blob_req {
uint16_t handle;
uint16_t offset;
} __packed;
/* Read Blob Response */
#define BT_ATT_OP_READ_BLOB_RSP 0x0d
struct bt_att_read_blob_rsp {
uint8_t _dummy[0];
uint8_t value[];
} __packed;
/* Read Multiple Request */
#define BT_ATT_READ_MULT_MIN_LEN_REQ 0x04
#define BT_ATT_OP_READ_MULT_REQ 0x0e
struct bt_att_read_mult_req {
uint8_t _dummy[0];
uint16_t handles[];
} __packed;
/* Read Multiple Respose */
#define BT_ATT_OP_READ_MULT_RSP 0x0f
struct bt_att_read_mult_rsp {
uint8_t _dummy[0];
uint8_t value[];
} __packed;
/* Read by Group Type Request */
#define BT_ATT_OP_READ_GROUP_REQ 0x10
struct bt_att_read_group_req {
uint16_t start_handle;
uint16_t end_handle;
uint8_t uuid[];
} __packed;
struct bt_att_group_data {
uint16_t start_handle;
uint16_t end_handle;
uint8_t value[];
} __packed;
/* Read by Group Type Response */
#define BT_ATT_OP_READ_GROUP_RSP 0x11
struct bt_att_read_group_rsp {
uint8_t len;
struct bt_att_group_data data[];
} __packed;
/* Write Request */
#define BT_ATT_OP_WRITE_REQ 0x12
struct bt_att_write_req {
uint16_t handle;
uint8_t value[];
} __packed;
/* Write Response */
#define BT_ATT_OP_WRITE_RSP 0x13
/* Prepare Write Request */
#define BT_ATT_OP_PREPARE_WRITE_REQ 0x16
struct bt_att_prepare_write_req {
uint16_t handle;
uint16_t offset;
uint8_t value[];
} __packed;
/* Prepare Write Respond */
#define BT_ATT_OP_PREPARE_WRITE_RSP 0x17
struct bt_att_prepare_write_rsp {
uint16_t handle;
uint16_t offset;
uint8_t value[];
} __packed;
/* Execute Write Request */
#define BT_ATT_FLAG_CANCEL 0x00
#define BT_ATT_FLAG_EXEC 0x01
#define BT_ATT_OP_EXEC_WRITE_REQ 0x18
struct bt_att_exec_write_req {
uint8_t flags;
} __packed;
/* Execute Write Response */
#define BT_ATT_OP_EXEC_WRITE_RSP 0x19
/* Handle Value Notification */
#define BT_ATT_OP_NOTIFY 0x1b
struct bt_att_notify {
uint16_t handle;
uint8_t value[];
} __packed;
/* Handle Value Indication */
#define BT_ATT_OP_INDICATE 0x1d
struct bt_att_indicate {
uint16_t handle;
uint8_t value[];
} __packed;
/* Handle Value Confirm */
#define BT_ATT_OP_CONFIRM 0x1e
struct bt_att_signature {
uint8_t value[12];
} __packed;
#define BT_ATT_OP_READ_MULT_VL_REQ 0x20
struct bt_att_read_mult_vl_req {
uint8_t _dummy[0];
uint16_t handles[];
} __packed;
/* Read Multiple Respose */
#define BT_ATT_OP_READ_MULT_VL_RSP 0x21
struct bt_att_read_mult_vl_rsp {
uint16_t len;
uint8_t value[];
} __packed;
/* Handle Multiple Value Notification */
#define BT_ATT_OP_NOTIFY_MULT 0x23
struct bt_att_notify_mult {
uint16_t handle;
uint16_t len;
uint8_t value[];
} __packed;
/* Write Command */
#define BT_ATT_OP_WRITE_CMD 0x52
struct bt_att_write_cmd {
uint16_t handle;
uint8_t value[];
} __packed;
/* Signed Write Command */
#define BT_ATT_OP_SIGNED_WRITE_CMD 0xd2
struct bt_att_signed_write_cmd {
uint16_t handle;
uint8_t value[];
} __packed;

1772
devices/ble_hci/common-hal/_bleio/hci_include/hci.h Normal file
View File

File diff suppressed because it is too large Load Diff

92
devices/ble_hci/common-hal/_bleio/hci_include/hci_err.h Normal file
View File

@ -0,0 +1,92 @@
/** @file
* @brief Bluetooth Host Control Interface status codes.
*/
/*
* Copyright (c) 2019 Nordic Semiconductor ASA
*
* SPDX-License-Identifier: Apache-2.0
*/
#ifndef ZEPHYR_INCLUDE_BLUETOOTH_HCI_STATUS_H_
#define ZEPHYR_INCLUDE_BLUETOOTH_HCI_STATUS_H_
#ifdef __cplusplus
extern "C" {
#endif
/** HCI Error Codes, BT Core Spec v5.2 [Vol 1, Part F]. */
#define BT_HCI_ERR_SUCCESS 0x00
#define BT_HCI_ERR_UNKNOWN_CMD 0x01
#define BT_HCI_ERR_UNKNOWN_CONN_ID 0x02
#define BT_HCI_ERR_HW_FAILURE 0x03
#define BT_HCI_ERR_PAGE_TIMEOUT 0x04
#define BT_HCI_ERR_AUTH_FAIL 0x05
#define BT_HCI_ERR_PIN_OR_KEY_MISSING 0x06
#define BT_HCI_ERR_MEM_CAPACITY_EXCEEDED 0x07
#define BT_HCI_ERR_CONN_TIMEOUT 0x08
#define BT_HCI_ERR_CONN_LIMIT_EXCEEDED 0x09
#define BT_HCI_ERR_SYNC_CONN_LIMIT_EXCEEDED 0x0a
#define BT_HCI_ERR_CONN_ALREADY_EXISTS 0x0b
#define BT_HCI_ERR_CMD_DISALLOWED 0x0c
#define BT_HCI_ERR_INSUFFICIENT_RESOURCES 0x0d
#define BT_HCI_ERR_INSUFFICIENT_SECURITY 0x0e
#define BT_HCI_ERR_BD_ADDR_UNACCEPTABLE 0x0f
#define BT_HCI_ERR_CONN_ACCEPT_TIMEOUT 0x10
#define BT_HCI_ERR_UNSUPP_FEATURE_PARAM_VAL 0x11
#define BT_HCI_ERR_INVALID_PARAM 0x12
#define BT_HCI_ERR_REMOTE_USER_TERM_CONN 0x13
#define BT_HCI_ERR_REMOTE_LOW_RESOURCES 0x14
#define BT_HCI_ERR_REMOTE_POWER_OFF 0x15
#define BT_HCI_ERR_LOCALHOST_TERM_CONN 0x16
#define BT_HCI_ERR_REPEATED_ATTEMPTS 0x17
#define BT_HCI_ERR_PAIRING_NOT_ALLOWED 0x18
#define BT_HCI_ERR_UNKNOWN_LMP_PDU 0x19
#define BT_HCI_ERR_UNSUPP_REMOTE_FEATURE 0x1a
#define BT_HCI_ERR_SCO_OFFSET_REJECTED 0x1b
#define BT_HCI_ERR_SCO_INTERVAL_REJECTED 0x1c
#define BT_HCI_ERR_SCO_AIR_MODE_REJECTED 0x1d
#define BT_HCI_ERR_INVALID_LL_PARAM 0x1e
#define BT_HCI_ERR_UNSPECIFIED 0x1f
#define BT_HCI_ERR_UNSUPP_LL_PARAM_VAL 0x20
#define BT_HCI_ERR_ROLE_CHANGE_NOT_ALLOWED 0x21
#define BT_HCI_ERR_LL_RESP_TIMEOUT 0x22
#define BT_HCI_ERR_LL_PROC_COLLISION 0x23
#define BT_HCI_ERR_LMP_PDU_NOT_ALLOWED 0x24
#define BT_HCI_ERR_ENC_MODE_NOT_ACCEPTABLE 0x25
#define BT_HCI_ERR_LINK_KEY_CANNOT_BE_CHANGED 0x26
#define BT_HCI_ERR_REQUESTED_QOS_NOT_SUPPORTED 0x27
#define BT_HCI_ERR_INSTANT_PASSED 0x28
#define BT_HCI_ERR_PAIRING_NOT_SUPPORTED 0x29
#define BT_HCI_ERR_DIFF_TRANS_COLLISION 0x2a
#define BT_HCI_ERR_QOS_UNACCEPTABLE_PARAM 0x2c
#define BT_HCI_ERR_QOS_REJECTED 0x2d
#define BT_HCI_ERR_CHAN_ASSESS_NOT_SUPPORTED 0x2e
#define BT_HCI_ERR_INSUFF_SECURITY 0x2f
#define BT_HCI_ERR_PARAM_OUT_OF_MANDATORY_RANGE 0x30
#define BT_HCI_ERR_ROLE_SWITCH_PENDING 0x32
#define BT_HCI_ERR_RESERVED_SLOT_VIOLATION 0x34
#define BT_HCI_ERR_ROLE_SWITCH_FAILED 0x35
#define BT_HCI_ERR_EXT_INQ_RESP_TOO_LARGE 0x36
#define BT_HCI_ERR_SIMPLE_PAIR_NOT_SUPP_BY_HOST 0x37
#define BT_HCI_ERR_HOST_BUSY_PAIRING 0x38
#define BT_HCI_ERR_CONN_REJECTED_DUE_TO_NO_CHAN 0x39
#define BT_HCI_ERR_CONTROLLER_BUSY 0x3a
#define BT_HCI_ERR_UNACCEPT_CONN_PARAM 0x3b
#define BT_HCI_ERR_ADV_TIMEOUT 0x3c
#define BT_HCI_ERR_TERM_DUE_TO_MIC_FAIL 0x3d
#define BT_HCI_ERR_CONN_FAIL_TO_ESTAB 0x3e
#define BT_HCI_ERR_MAC_CONN_FAILED 0x3f
#define BT_HCI_ERR_CLOCK_ADJUST_REJECTED 0x40
#define BT_HCI_ERR_SUBMAP_NOT_DEFINED 0x41
#define BT_HCI_ERR_UNKNOWN_ADV_IDENTIFIER 0x42
#define BT_HCI_ERR_LIMIT_REACHED 0x43
#define BT_HCI_ERR_OP_CANCELLED_BY_HOST 0x44
#define BT_HCI_ERR_PACKET_TOO_LONG 0x45
#define BT_HCI_ERR_AUTHENTICATION_FAIL __DEPRECATED_MACRO BT_HCI_ERR_AUTH_FAIL
#ifdef __cplusplus
}
#endif
#endif /* ZEPHYR_INCLUDE_BLUETOOTH_HCI_STATUS_H_ */

152
devices/ble_hci/common-hal/_bleio/hci_include/hci_raw.h Normal file
View File

@ -0,0 +1,152 @@
/** @file
* @brief Bluetooth HCI RAW channel handling
*/
/*
* Copyright (c) 2016 Intel Corporation
*
* SPDX-License-Identifier: Apache-2.0
*/
#ifndef ZEPHYR_INCLUDE_BLUETOOTH_HCI_RAW_H_
#define ZEPHYR_INCLUDE_BLUETOOTH_HCI_RAW_H_
/**
* @brief HCI RAW channel
* @defgroup hci_raw HCI RAW channel
* @ingroup bluetooth
* @{
*/
#ifdef __cplusplus
extern "C" {
#endif
#if defined(CONFIG_BT_CTLR_TX_BUFFER_SIZE)
#define BT_L2CAP_MTU (CONFIG_BT_CTLR_TX_BUFFER_SIZE - BT_L2CAP_HDR_SIZE)
#else
#define BT_L2CAP_MTU 65 /* 64-byte public key + opcode */
#endif /* CONFIG_BT_CTLR */
/** Data size needed for ACL buffers */
#define BT_BUF_ACL_SIZE BT_L2CAP_BUF_SIZE(BT_L2CAP_MTU)
#if defined(CONFIG_BT_CTLR_TX_BUFFERS)
#define BT_HCI_ACL_COUNT CONFIG_BT_CTLR_TX_BUFFERS
#else
#define BT_HCI_ACL_COUNT 6
#endif
#define BT_BUF_TX_SIZE MAX(BT_BUF_RX_SIZE, BT_BUF_ACL_SIZE)
/** @brief Send packet to the Bluetooth controller
*
* Send packet to the Bluetooth controller. Caller needs to
* implement netbuf pool.
*
* @param buf netbuf packet to be send
*
* @return Zero on success or (negative) error code otherwise.
*/
int bt_send(struct net_buf *buf);
enum {
/** Passthrough mode
*
* While in this mode the buffers are passed as is between the stack
* and the driver.
*/
BT_HCI_RAW_MODE_PASSTHROUGH = 0x00,
/** H:4 mode
*
* While in this mode H:4 headers will added into the buffers
* according to the buffer type when coming from the stack and will be
* removed and used to set the buffer type.
*/
BT_HCI_RAW_MODE_H4 = 0x01,
};
/** @brief Set Bluetooth RAW channel mode
*
* Set access mode of Bluetooth RAW channel.
*
* @param mode Access mode.
*
* @return Zero on success or (negative) error code otherwise.
*/
int bt_hci_raw_set_mode(uint8_t mode);
/** @brief Get Bluetooth RAW channel mode
*
* Get access mode of Bluetooth RAW channel.
*
* @return Access mode.
*/
uint8_t bt_hci_raw_get_mode(void);
#define BT_HCI_ERR_EXT_HANDLED 0xff
/** Helper macro to define a command extension
*
* @param _op Opcode of the command.
* @param _min_len Minimal length of the command.
* @param _func Handler function to be called.
*/
#define BT_HCI_RAW_CMD_EXT(_op, _min_len, _func) \
{ \
.op = _op, \
.min_len = _min_len, \
.func = _func, \
}
struct bt_hci_raw_cmd_ext {
/** Opcode of the command */
uint16_t op;
/** Minimal length of the command */
size_t min_len;
/** Handler function.
*
* Handler function to be called when a command is intercepted.
*
* @param buf Buffer containing the command.
*
* @return HCI Status code or BT_HCI_ERR_EXT_HANDLED if command has
* been handled already and a response has been sent as oppose to
* BT_HCI_ERR_SUCCESS which just indicates that the command can be
* sent to the controller to be processed.
*/
uint8_t (*func)(struct net_buf *buf);
};
/** @brief Register Bluetooth RAW command extension table
*
* Register Bluetooth RAW channel command extension table, opcodes in this
* table are intercepted to sent to the handler function.
*
* @param cmds Pointer to the command extension table.
* @param size Size of the command extension table.
*/
void bt_hci_raw_cmd_ext_register(struct bt_hci_raw_cmd_ext *cmds, size_t size);
/** @brief Enable Bluetooth RAW channel:
*
* Enable Bluetooth RAW HCI channel.
*
* @param rx_queue netbuf queue where HCI packets received from the Bluetooth
* controller are to be queued. The queue is defined in the caller while
* the available buffers pools are handled in the stack.
*
* @return Zero on success or (negative) error code otherwise.
*/
int bt_enable_raw(struct k_fifo *rx_queue);
#ifdef __cplusplus
}
#endif
/**
* @}
*/
#endif /* ZEPHYR_INCLUDE_BLUETOOTH_HCI_RAW_H_ */

379
devices/ble_hci/common-hal/_bleio/hci_include/hci_vs.h Normal file
View File

@ -0,0 +1,379 @@
/* hci_vs.h - Bluetooth Host Control Interface Vendor Specific definitions */
/*
* Copyright (c) 2017-2018 Nordic Semiconductor ASA
* Copyright (c) 2015-2016 Intel Corporation
*
* SPDX-License-Identifier: Apache-2.0
*/
#ifndef ZEPHYR_INCLUDE_BLUETOOTH_HCI_VS_H_
#define ZEPHYR_INCLUDE_BLUETOOTH_HCI_VS_H_
#include <bluetooth/hci.h>
#ifdef __cplusplus
extern "C" {
#endif
#define BT_VS_CMD_BIT_VERSION 0
#define BT_VS_CMD_BIT_SUP_CMD 1
#define BT_VS_CMD_BIT_SUP_FEAT 2
#define BT_VS_CMD_BIT_SET_EVT_MASK 3
#define BT_VS_CMD_BIT_RESET 4
#define BT_VS_CMD_BIT_WRITE_BDADDR 5
#define BT_VS_CMD_BIT_SET_TRACE_ENABLE 6
#define BT_VS_CMD_BIT_READ_BUILD_INFO 7
#define BT_VS_CMD_BIT_READ_STATIC_ADDRS 8
#define BT_VS_CMD_BIT_READ_KEY_ROOTS 9
#define BT_VS_CMD_BIT_READ_CHIP_TEMP 10
#define BT_VS_CMD_BIT_READ_HOST_STACK_CMD 11
#define BT_VS_CMD_BIT_SET_SCAN_REP_ENABLE 12
#define BT_VS_CMD_BIT_WRITE_TX_POWER 13
#define BT_VS_CMD_BIT_READ_TX_POWER 14
#define BT_VS_CMD_SUP_FEAT(cmd) BT_LE_FEAT_TEST(cmd, \
BT_VS_CMD_BIT_SUP_FEAT)
#define BT_VS_CMD_READ_STATIC_ADDRS(cmd) BT_LE_FEAT_TEST(cmd, \
BT_VS_CMD_BIT_READ_STATIC_ADDRS)
#define BT_VS_CMD_READ_KEY_ROOTS(cmd) BT_LE_FEAT_TEST(cmd, \
BT_VS_CMD_BIT_READ_KEY_ROOTS)
#define BT_HCI_VS_HW_PLAT_INTEL 0x0001
#define BT_HCI_VS_HW_PLAT_NORDIC 0x0002
#define BT_HCI_VS_HW_PLAT_NXP 0x0003
#define BT_HCI_VS_HW_VAR_NORDIC_NRF51X 0x0001
#define BT_HCI_VS_HW_VAR_NORDIC_NRF52X 0x0002
#define BT_HCI_VS_HW_VAR_NORDIC_NRF53X 0x0003
#define BT_HCI_VS_FW_VAR_STANDARD_CTLR 0x0001
#define BT_HCI_VS_FW_VAR_VS_CTLR 0x0002
#define BT_HCI_VS_FW_VAR_FW_LOADER 0x0003
#define BT_HCI_VS_FW_VAR_RESCUE_IMG 0x0004
#define BT_HCI_OP_VS_READ_VERSION_INFO BT_OP(BT_OGF_VS, 0x0001)
struct bt_hci_rp_vs_read_version_info {
uint8_t status;
uint16_t hw_platform;
uint16_t hw_variant;
uint8_t fw_variant;
uint8_t fw_version;
uint16_t fw_revision;
uint32_t fw_build;
} __packed;
#define BT_HCI_OP_VS_READ_SUPPORTED_COMMANDS BT_OP(BT_OGF_VS, 0x0002)
struct bt_hci_rp_vs_read_supported_commands {
uint8_t status;
uint8_t commands[64];
} __packed;
#define BT_HCI_OP_VS_READ_SUPPORTED_FEATURES BT_OP(BT_OGF_VS, 0x0003)
struct bt_hci_rp_vs_read_supported_features {
uint8_t status;
uint8_t features[8];
} __packed;
#define BT_HCI_OP_VS_SET_EVENT_MASK BT_OP(BT_OGF_VS, 0x0004)
struct bt_hci_cp_vs_set_event_mask {
uint8_t event_mask[8];
} __packed;
#define BT_HCI_VS_RESET_SOFT 0x00
#define BT_HCI_VS_RESET_HARD 0x01
#define BT_HCI_OP_VS_RESET BT_OP(BT_OGF_VS, 0x0005)
struct bt_hci_cp_vs_reset {
uint8_t type;
} __packed;
#define BT_HCI_OP_VS_WRITE_BD_ADDR BT_OP(BT_OGF_VS, 0x0006)
struct bt_hci_cp_vs_write_bd_addr {
bt_addr_t bdaddr;
} __packed;
#define BT_HCI_VS_TRACE_DISABLED 0x00
#define BT_HCI_VS_TRACE_ENABLED 0x01
#define BT_HCI_VS_TRACE_HCI_EVTS 0x00
#define BT_HCI_VS_TRACE_VDC 0x01
#define BT_HCI_OP_VS_SET_TRACE_ENABLE BT_OP(BT_OGF_VS, 0x0007)
struct bt_hci_cp_vs_set_trace_enable {
uint8_t enable;
uint8_t type;
} __packed;
#define BT_HCI_OP_VS_READ_BUILD_INFO BT_OP(BT_OGF_VS, 0x0008)
struct bt_hci_rp_vs_read_build_info {
uint8_t status;
uint8_t info[];
} __packed;
struct bt_hci_vs_static_addr {
bt_addr_t bdaddr;
uint8_t ir[16];
} __packed;
#define BT_HCI_OP_VS_READ_STATIC_ADDRS BT_OP(BT_OGF_VS, 0x0009)
struct bt_hci_rp_vs_read_static_addrs {
uint8_t status;
uint8_t num_addrs;
struct bt_hci_vs_static_addr a[];
} __packed;
#define BT_HCI_OP_VS_READ_KEY_HIERARCHY_ROOTS BT_OP(BT_OGF_VS, 0x000a)
struct bt_hci_rp_vs_read_key_hierarchy_roots {
uint8_t status;
uint8_t ir[16];
uint8_t er[16];
} __packed;
#define BT_HCI_OP_VS_READ_CHIP_TEMP BT_OP(BT_OGF_VS, 0x000b)
struct bt_hci_rp_vs_read_chip_temp {
uint8_t status;
int8_t temps;
} __packed;
struct bt_hci_vs_cmd {
uint16_t vendor_id;
uint16_t opcode_base;
} __packed;
#define BT_HCI_VS_VID_ANDROID 0x0001
#define BT_HCI_VS_VID_MICROSOFT 0x0002
#define BT_HCI_OP_VS_READ_HOST_STACK_CMDS BT_OP(BT_OGF_VS, 0x000c)
struct bt_hci_rp_vs_read_host_stack_cmds {
uint8_t status;
uint8_t num_cmds;
struct bt_hci_vs_cmd c[];
} __packed;
#define BT_HCI_VS_SCAN_REQ_REPORTS_DISABLED 0x00
#define BT_HCI_VS_SCAN_REQ_REPORTS_ENABLED 0x01
#define BT_HCI_OP_VS_SET_SCAN_REQ_REPORTS BT_OP(BT_OGF_VS, 0x000d)
struct bt_hci_cp_vs_set_scan_req_reports {
uint8_t enable;
} __packed;
#define BT_HCI_VS_LL_HANDLE_TYPE_ADV 0x00
#define BT_HCI_VS_LL_HANDLE_TYPE_SCAN 0x01
#define BT_HCI_VS_LL_HANDLE_TYPE_CONN 0x02
#define BT_HCI_VS_LL_TX_POWER_LEVEL_NO_PREF 0x7F
#define BT_HCI_OP_VS_WRITE_TX_POWER_LEVEL BT_OP(BT_OGF_VS, 0x000e)
struct bt_hci_cp_vs_write_tx_power_level {
uint8_t handle_type;
uint16_t handle;
int8_t tx_power_level;
} __packed;
struct bt_hci_rp_vs_write_tx_power_level {
uint8_t status;
uint8_t handle_type;
uint16_t handle;
int8_t selected_tx_power;
} __packed;
#define BT_HCI_OP_VS_READ_TX_POWER_LEVEL BT_OP(BT_OGF_VS, 0x000f)
struct bt_hci_cp_vs_read_tx_power_level {
uint8_t handle_type;
uint16_t handle;
} __packed;
struct bt_hci_rp_vs_read_tx_power_level {
uint8_t status;
uint8_t handle_type;
uint16_t handle;
int8_t tx_power_level;
} __packed;
#define BT_HCI_OP_VS_READ_USB_TRANSPORT_MODE BT_OP(BT_OGF_VS, 0x0010)
struct bt_hci_rp_vs_read_usb_transport_mode {
uint8_t status;
uint8_t num_supported_modes;
uint8_t supported_mode[];
} __packed;
#define BT_HCI_VS_USB_H2_MODE 0x00
#define BT_HCI_VS_USB_H4_MODE 0x01
#define BT_HCI_OP_VS_SET_USB_TRANSPORT_MODE BT_OP(BT_OGF_VS, 0x0011)
struct bt_hci_cp_vs_set_usb_transport_mode {
uint8_t mode;
} __packed;
/* Events */
struct bt_hci_evt_vs {
uint8_t subevent;
} __packed;
#define BT_HCI_EVT_VS_FATAL_ERROR 0x02
struct bt_hci_evt_vs_fatal_error {
uint64_t pc;
uint8_t err_info[];
} __packed;
#define BT_HCI_VS_TRACE_LMP_TX 0x01
#define BT_HCI_VS_TRACE_LMP_RX 0x02
#define BT_HCI_VS_TRACE_LLCP_TX 0x03
#define BT_HCI_VS_TRACE_LLCP_RX 0x04
#define BT_HCI_VS_TRACE_LE_CONN_IND 0x05
#define BT_HCI_EVT_VS_TRACE_INFO 0x03
struct bt_hci_evt_vs_trace_info {
uint8_t type;
uint8_t data[];
} __packed;
#define BT_HCI_EVT_VS_SCAN_REQ_RX 0x04
struct bt_hci_evt_vs_scan_req_rx {
bt_addr_le_t addr;
int8_t rssi;
} __packed;
/* Event mask bits */
#define BT_EVT_MASK_VS_FATAL_ERROR BT_EVT_BIT(1)
#define BT_EVT_MASK_VS_TRACE_INFO BT_EVT_BIT(2)
#define BT_EVT_MASK_VS_SCAN_REQ_RX BT_EVT_BIT(3)
/* Mesh HCI commands */
#define BT_HCI_MESH_REVISION 0x01
#define BT_HCI_OP_VS_MESH BT_OP(BT_OGF_VS, 0x0042)
#define BT_HCI_MESH_EVT_PREFIX 0xF0
struct bt_hci_cp_mesh {
uint8_t opcode;
} __packed;
#define BT_HCI_OC_MESH_GET_OPTS 0x00
struct bt_hci_rp_mesh_get_opts {
uint8_t status;
uint8_t opcode;
uint8_t revision;
uint8_t ch_map;
int8_t min_tx_power;
int8_t max_tx_power;
uint8_t max_scan_filter;
uint8_t max_filter_pattern;
uint8_t max_adv_slot;
uint8_t max_tx_window;
uint8_t evt_prefix_len;
uint8_t evt_prefix;
} __packed;
#define BT_HCI_MESH_PATTERN_LEN_MAX 0x0f
#define BT_HCI_OC_MESH_SET_SCAN_FILTER 0x01
struct bt_hci_mesh_pattern {
uint8_t pattern_len;
uint8_t pattern[];
} __packed;
struct bt_hci_cp_mesh_set_scan_filter {
uint8_t scan_filter;
uint8_t filter_dup;
uint8_t num_patterns;
struct bt_hci_mesh_pattern patterns[];
} __packed;
struct bt_hci_rp_mesh_set_scan_filter {
uint8_t status;
uint8_t opcode;
uint8_t scan_filter;
} __packed;
#define BT_HCI_OC_MESH_ADVERTISE 0x02
struct bt_hci_cp_mesh_advertise {
uint8_t adv_slot;
uint8_t own_addr_type;
bt_addr_t random_addr;
uint8_t ch_map;
int8_t tx_power;
uint8_t min_tx_delay;
uint8_t max_tx_delay;
uint8_t retx_count;
uint8_t retx_interval;
uint8_t scan_delay;
uint16_t scan_duration;
uint8_t scan_filter;
uint8_t data_len;
uint8_t data[31];
} __packed;
struct bt_hci_rp_mesh_advertise {
uint8_t status;
uint8_t opcode;
uint8_t adv_slot;
} __packed;
#define BT_HCI_OC_MESH_ADVERTISE_TIMED 0x03
struct bt_hci_cp_mesh_advertise_timed {
uint8_t adv_slot;
uint8_t own_addr_type;
bt_addr_t random_addr;
uint8_t ch_map;
int8_t tx_power;
uint8_t retx_count;
uint8_t retx_interval;
uint32_t instant;
uint16_t tx_delay;
uint16_t tx_window;
uint8_t data_len;
uint8_t data[31];
} __packed;
struct bt_hci_rp_mesh_advertise_timed {
uint8_t status;
uint8_t opcode;
uint8_t adv_slot;
} __packed;
#define BT_HCI_OC_MESH_ADVERTISE_CANCEL 0x04
struct bt_hci_cp_mesh_advertise_cancel {
uint8_t adv_slot;
} __packed;
struct bt_hci_rp_mesh_advertise_cancel {
uint8_t status;
uint8_t opcode;
uint8_t adv_slot;
} __packed;
#define BT_HCI_OC_MESH_SET_SCANNING 0x05
struct bt_hci_cp_mesh_set_scanning {
uint8_t enable;
uint8_t ch_map;
uint8_t scan_filter;
} __packed;
struct bt_hci_rp_mesh_set_scanning {
uint8_t status;
uint8_t opcode;
} __packed;
/* Events */
struct bt_hci_evt_mesh {
uint8_t prefix;
uint8_t subevent;
} __packed;
#define BT_HCI_EVT_MESH_ADV_COMPLETE 0x00
struct bt_hci_evt_mesh_adv_complete {
uint8_t adv_slot;
} __packed;
#define BT_HCI_EVT_MESH_SCANNING_REPORT 0x01
struct bt_hci_evt_mesh_scan_report {
bt_addr_le_t addr;
uint8_t chan;
int8_t rssi;
uint32_t instant;
uint8_t data_len;
uint8_t data[];
} __packed;
struct bt_hci_evt_mesh_scanning_report {
uint8_t num_reports;
struct bt_hci_evt_mesh_scan_report reports[];
} __packed;
#ifdef __cplusplus
}
#endif
#endif /* ZEPHYR_INCLUDE_BLUETOOTH_HCI_VS_H_ */

230
devices/ble_hci/common-hal/_bleio/hci_include/l2cap_internal.h Normal file
View File

@ -0,0 +1,230 @@
// CircuitPython: Adapted from Zephyr include file.
/** @file
* @brief Internal APIs for Bluetooth L2CAP handling.
*/
/*
* Copyright (c) 2015-2016 Intel Corporation
*
* SPDX-License-Identifier: Apache-2.0
*/
#include <stdbool.h>
// for __packed
#include <string.h>
enum l2cap_conn_list_action {
BT_L2CAP_CHAN_LOOKUP,
BT_L2CAP_CHAN_DETACH,
};
#define BT_L2CAP_CID_BR_SIG 0x0001
#define BT_L2CAP_CID_ATT 0x0004
#define BT_L2CAP_CID_LE_SIG 0x0005
#define BT_L2CAP_CID_SMP 0x0006
#define BT_L2CAP_CID_BR_SMP 0x0007
#define BT_L2CAP_PSM_RFCOMM 0x0003
struct bt_l2cap_hdr {
uint16_t len;
uint16_t cid;
} __packed;
struct bt_l2cap_sig_hdr {
uint8_t code;
uint8_t ident;
uint16_t len;
} __packed;
#define BT_L2CAP_REJ_NOT_UNDERSTOOD 0x0000
#define BT_L2CAP_REJ_MTU_EXCEEDED 0x0001
#define BT_L2CAP_REJ_INVALID_CID 0x0002
#define BT_L2CAP_CMD_REJECT 0x01
struct bt_l2cap_cmd_reject {
uint16_t reason;
uint8_t data[];
} __packed;
struct bt_l2cap_cmd_reject_cid_data {
uint16_t scid;
uint16_t dcid;
} __packed;
#define BT_L2CAP_CONN_REQ 0x02
struct bt_l2cap_conn_req {
uint16_t psm;
uint16_t scid;
} __packed;
/* command statuses in reposnse */
#define BT_L2CAP_CS_NO_INFO 0x0000
#define BT_L2CAP_CS_AUTHEN_PEND 0x0001
/* valid results in conn response on BR/EDR */
#define BT_L2CAP_BR_SUCCESS 0x0000
#define BT_L2CAP_BR_PENDING 0x0001
#define BT_L2CAP_BR_ERR_PSM_NOT_SUPP 0x0002
#define BT_L2CAP_BR_ERR_SEC_BLOCK 0x0003
#define BT_L2CAP_BR_ERR_NO_RESOURCES 0x0004
#define BT_L2CAP_BR_ERR_INVALID_SCID 0x0006
#define BT_L2CAP_BR_ERR_SCID_IN_USE 0x0007
#define BT_L2CAP_CONN_RSP 0x03
struct bt_l2cap_conn_rsp {
uint16_t dcid;
uint16_t scid;
uint16_t result;
uint16_t status;
} __packed;
#define BT_L2CAP_CONF_SUCCESS 0x0000
#define BT_L2CAP_CONF_UNACCEPT 0x0001
#define BT_L2CAP_CONF_REJECT 0x0002
#define BT_L2CAP_CONF_REQ 0x04
struct bt_l2cap_conf_req {
uint16_t dcid;
uint16_t flags;
uint8_t data[];
} __packed;
#define BT_L2CAP_CONF_RSP 0x05
struct bt_l2cap_conf_rsp {
uint16_t scid;
uint16_t flags;
uint16_t result;
uint8_t data[];
} __packed;
/* Option type used by MTU config request data */
#define BT_L2CAP_CONF_OPT_MTU 0x01
/* Options bits selecting most significant bit (hint) in type field */
#define BT_L2CAP_CONF_HINT 0x80
#define BT_L2CAP_CONF_MASK 0x7f
struct bt_l2cap_conf_opt {
uint8_t type;
uint8_t len;
uint8_t data[];
} __packed;
#define BT_L2CAP_DISCONN_REQ 0x06
struct bt_l2cap_disconn_req {
uint16_t dcid;
uint16_t scid;
} __packed;
#define BT_L2CAP_DISCONN_RSP 0x07
struct bt_l2cap_disconn_rsp {
uint16_t dcid;
uint16_t scid;
} __packed;
#define BT_L2CAP_INFO_FEAT_MASK 0x0002
#define BT_L2CAP_INFO_FIXED_CHAN 0x0003
#define BT_L2CAP_INFO_REQ 0x0a
struct bt_l2cap_info_req {
uint16_t type;
} __packed;
/* info result */
#define BT_L2CAP_INFO_SUCCESS 0x0000
#define BT_L2CAP_INFO_NOTSUPP 0x0001
#define BT_L2CAP_INFO_RSP 0x0b
struct bt_l2cap_info_rsp {
uint16_t type;
uint16_t result;
uint8_t data[];
} __packed;
#define BT_L2CAP_CONN_PARAM_REQ 0x12
struct bt_l2cap_conn_param_req {
uint16_t min_interval;
uint16_t max_interval;
uint16_t latency;
uint16_t timeout;
} __packed;
#define BT_L2CAP_CONN_PARAM_ACCEPTED 0x0000
#define BT_L2CAP_CONN_PARAM_REJECTED 0x0001
#define BT_L2CAP_CONN_PARAM_RSP 0x13
struct bt_l2cap_conn_param_rsp {
uint16_t result;
} __packed;
#define BT_L2CAP_LE_CONN_REQ 0x14
struct bt_l2cap_le_conn_req {
uint16_t psm;
uint16_t scid;
uint16_t mtu;
uint16_t mps;
uint16_t credits;
} __packed;
/* valid results in conn response on LE */
#define BT_L2CAP_LE_SUCCESS 0x0000
#define BT_L2CAP_LE_ERR_PSM_NOT_SUPP 0x0002
#define BT_L2CAP_LE_ERR_NO_RESOURCES 0x0004
#define BT_L2CAP_LE_ERR_AUTHENTICATION 0x0005
#define BT_L2CAP_LE_ERR_AUTHORIZATION 0x0006
#define BT_L2CAP_LE_ERR_KEY_SIZE 0x0007
#define BT_L2CAP_LE_ERR_ENCRYPTION 0x0008
#define BT_L2CAP_LE_ERR_INVALID_SCID 0x0009
#define BT_L2CAP_LE_ERR_SCID_IN_USE 0x000A
#define BT_L2CAP_LE_ERR_UNACCEPT_PARAMS 0x000B
#define BT_L2CAP_LE_ERR_INVALID_PARAMS 0x000C
#define BT_L2CAP_LE_CONN_RSP 0x15
struct bt_l2cap_le_conn_rsp {
uint16_t dcid;
uint16_t mtu;
uint16_t mps;
uint16_t credits;
uint16_t result;
} __packed;
#define BT_L2CAP_LE_CREDITS 0x16
struct bt_l2cap_le_credits {
uint16_t cid;
uint16_t credits;
} __packed;
#define BT_L2CAP_ECRED_CONN_REQ 0x17
struct bt_l2cap_ecred_conn_req {
uint16_t psm;
uint16_t mtu;
uint16_t mps;
uint16_t credits;
uint16_t scid[];
} __packed;
#define BT_L2CAP_ECRED_CONN_RSP 0x18
struct bt_l2cap_ecred_conn_rsp {
uint16_t mtu;
uint16_t mps;
uint16_t credits;
uint16_t result;
uint16_t dcid[];
} __packed;
#define BT_L2CAP_ECRED_RECONF_REQ 0x19
struct bt_l2cap_ecred_reconf_req {
uint16_t mtu;
uint16_t mps;
uint16_t scid[];
} __packed;
#define BT_L2CAP_RECONF_SUCCESS 0x0000
#define BT_L2CAP_RECONF_INVALID_MTU 0x0001
#define BT_L2CAP_RECONF_INVALID_MPS 0x0002
#define BT_L2CAP_ECRED_RECONF_RSP 0x1a
struct bt_l2cap_ecred_reconf_rsp {
uint16_t result;
} __packed;

29
devices/ble_hci/supervisor/bluetooth.c Normal file
View File

@ -0,0 +1,29 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2019 Scott Shawcroft for Adafruit Industries
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#if CIRCUITPY_BLE_FILE_SERVICE
#error CIRCUITPY_BLE_FILE_SERVICE not implemented for CIRCUITPY_BLEIO_HCI
#endif

34
devices/ble_hci/supervisor/bluetooth.h Normal file
View File

@ -0,0 +1,34 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2019 Scott Shawcroft for Adafruit Industries
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#ifndef MICROPY_INCLUDED_DEVICE_BLE_HCI_SUPERVISOR_BLUETOOTH_H
#define MICROPY_INCLUDED_DEVICE_BLE_HCI_SUPERVISOR_BLUETOOTH_H
void supervisor_start_bluetooth(void);
bool supervisor_bluetooth_hook(ble_evt_t *ble_evt);
void supervisor_bluetooth_background(void);
#endif // MICROPY_INCLUDED_DEVICE_BLE_HCI_SUPERVISOR_BLUETOOTH_H

191
docs/Makefile
View File

@ -1,191 +0,0 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
PYTHON = python3
SPHINXOPTS = -W --keep-going
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = build/$(MICROPY_PORT)
CPYDIFFDIR = ../tools
CPYDIFF = gen-cpydiff.py
GENRSTDIR = genrst
# Run "make FORCE= ..." to avoid rebuilding from scratch (and risk
# producing incorrect docs).
FORCE = -E
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " cpydiff to generate the MicroPython differences from CPython"
clean:
rm -rf $(BUILDDIR)/*
rm -f $(GENRSTDIR)/*
cpydiff:
@echo "Generating MicroPython Differences."
rm -f $(GENRSTDIR)/*
cd $(CPYDIFFDIR) && $(PYTHON) $(CPYDIFF)
html: cpydiff
$(SPHINXBUILD) $(FORCE) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/MicroPython.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MicroPython.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/MicroPython"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/MicroPython"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex: cpydiff
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf: cpydiff
$(SPHINXBUILD) $(FORCE) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja: cpydiff
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

53
docs/README.md
View File

@ -1,53 +1,48 @@
MicroPython Documentation
Adafruit's CircuitPython Documentation
=========================
The MicroPython documentation can be found at:
http://docs.micropython.org/en/latest/
The latest documentation can be found at:
http://circuitpython.readthedocs.io/en/latest/
The documentation you see there is generated from the files in the docs tree:
https://github.com/micropython/micropython/tree/master/docs
The documentation you see there is generated from the files in the whole tree:
https://github.com/adafruit/circuitpython/tree/main
Building the documentation locally
----------------------------------
If you're making changes to the documentation, you may want to build the
If you're making changes to the documentation, you should build the
documentation locally so that you can preview your changes.
Install Sphinx, and optionally (for the RTD-styling), sphinx_rtd_theme,
Install Sphinx, recommonmark, and optionally (for the RTD-styling), sphinx_rtd_theme,
preferably in a virtualenv:
pip install sphinx
pip install recommonmark
pip install sphinx_rtd_theme
In `micropython/docs`, build the docs:
In `circuitpython/`, build the docs:
make html
You'll find the index page at `micropython/docs/build/html/index.html`.
You'll find the index page at `_build/html/index.html`.
Having readthedocs.org build the documentation
----------------------------------------------
### More flexibility
If you would like to have docs for forks/branches hosted on GitHub, GitLab or
BitBucket an alternative to building the docs locally is to sign up for a free
https://readthedocs.org account. The rough steps to follow are:
1. sign-up for an account, unless you already have one
2. in your account settings: add GitHub as a connected service (assuming
you have forked this repo on github)
3. in your account projects: import your forked/cloned micropython repository
into readthedocs
4. in the project's versions: add the branches you are developing on or
for which you'd like readthedocs to auto-generate docs whenever you
push a change
Running `make` by itself will list out the multiple doc generating commands available.
PDF manual generation
---------------------
All commands will, by default, run with `-E` (forces a rebuild from scratch of docs) and `-v` (verbosity level 1). This can be customized as desired:
This can be achieved with:
# will turn OFF the force rebuild
make html FORCE=
make latexpdf
# will turn OFF the verbosity
make html VERBOSE=
but require rather complete install of LaTeX with various extensions. On
Debian/Ubuntu, try (500MB+ download):
# will turn OFF the force rebuild and make it doubly verbose when running
make html FORCE= VERBOSE="-v -v"
apt-get install texlive-latex-recommended texlive-latex-extra
You can also pass other options to sphinx by using `SPHINXOPTS`.
make html SPHINXOPTS="-T"
For more flexibility and customization, take a look at the Makefile for all variables you can pass in and overwrite.

108
docs/autoapi/templates/python/module.rst Normal file
View File

@ -0,0 +1,108 @@
{% if not obj.display %}
:orphan:
{% endif %}
:mod:`{{ obj.name }}`
======={{ "=" * obj.name|length }}
.. py:module:: {{ obj.name }}
{% if obj.docstring %}
.. autoapi-nested-parse::
{{ obj.docstring|prepare_docstring|indent(3) }}
{% endif %}
{% if support_matrix_reverse[obj.name] is defined %}
.. raw:: html
<p>
<details>
<summary>Available on these boards</summary>
<ul>
{% for board in support_matrix_reverse[obj.name] %}
<li> {{ board }}
{% endfor %}
</ul>
</details>
</p>
{% endif %}
{% block subpackages %}
{% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
{% if visible_subpackages %}
.. toctree::
:maxdepth: 2
{% for subpackage in visible_subpackages %}
{{ subpackage.short_name }}/index.rst
{% endfor %}
{% endif %}
{% endblock %}
{% block submodules %}
{% set visible_submodules = obj.submodules|selectattr("display")|list %}
{% if visible_submodules %}
.. toctree::
:titlesonly:
:maxdepth: 1
{% for submodule in visible_submodules %}
{{ submodule.short_name }}/index.rst
{% endfor %}
{% endif %}
{% endblock %}
{% block content %}
{% if obj.all is not none %}
{% set visible_children = obj.children|selectattr("short_name", "in", obj.all)|list %}
{% elif obj.type is equalto("package") %}
{% set visible_children = obj.children|selectattr("display")|list %}
{% else %}
{% set visible_children = obj.children|selectattr("display")|rejectattr("imported")|list %}
{% endif %}
{% if visible_children %}
{% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %}
{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %}
{% if "show-module-summary" in autoapi_options and (visible_classes or visible_functions) %}
{% block classes %}
{% if visible_classes %}
Classes
~~~~~~~
.. autoapisummary::
{% for klass in visible_classes %}
{{ klass.id }}
{% endfor %}
{% endif %}
{% endblock %}
{% block functions %}
{% if visible_functions %}
Functions
~~~~~~~~~
.. autoapisummary::
{% for function in visible_functions %}
{{ function.id }}
{% endfor %}
{% endif %}
{% endblock %}
{% endif %}
{% for obj_item in visible_children %}
{{ obj_item.rendered|indent(0) }}
{% endfor %}
{% endif %}
{% endblock %}

87
docs/common_hal.md Normal file
View File

@ -0,0 +1,87 @@
# Adding ``*io`` support to other ports
`digitalio` provides a well-defined, cross-port hardware abstraction layer built to support different devices and their drivers. It's backed by the Common HAL, a C api suitable for supporting different hardware in a similar manner. By sharing this C api, developers can support new hardware easily and cross-port functionality to the new hardware.
These instructions also apply to `analogio`, `busio`, `pulseio` and `touchio`. Most drivers depend on `analogio`, `digitalio` and `busio` so start with those.
## File layout
Common HAL related files are found in these locations:
* `shared-bindings` Shared home for the Python <-> C bindings which includes inline RST documentation for the created interfaces. The common hal functions are defined in the .h files of the corresponding C files.
* `shared-module` Shared home for C code built on the Common HAL and used by all ports. This code only uses `common_hal` methods defined in `shared-bindings`.
* `<port>/common-hal` Port-specific implementation of the Common HAL.
Each folder has the substructure of <python module name>/<class name> and they should match 1:1. `__init__.c` is used for module globals that are not classes (similar to `__init__.py`).
## Adding support
### Modifying the build
The first step is to hook the `shared-bindings` into your build for the modules you wish to support. Here's an example of this step for the `atmel-samd/Makefile`:
```
SRC_BINDINGS = \
board/__init__.c \
microcontroller/__init__.c \
microcontroller/Pin.c \
analogio/__init__.c \
analogio/AnalogIn.c \
analogio/AnalogOut.c \
digitalio/__init__.c \
digitalio/DigitalInOut.c \
pulseio/__init__.c \
pulseio/PulseIn.c \
pulseio/PulseOut.c \
pulseio/PWMOut.c \
busio/__init__.c \
busio/I2C.c \
busio/SPI.c \
busio/UART.c \
neopixel_write/__init__.c \
time/__init__.c \
usb_hid/__init__.c \
usb_hid/Device.c
SRC_BINDINGS_EXPANDED = $(addprefix shared-bindings/, $(SRC_BINDINGS)) \
$(addprefix common-hal/, $(SRC_BINDINGS))
# Add the resulting objects to the full list
OBJ += $(addprefix $(BUILD)/, $(SRC_BINDINGS_EXPANDED:.c=.o))
# Add the sources for QSTR generation
SRC_QSTR += $(SRC_C) $(SRC_BINDINGS_EXPANDED) $(STM_SRC_C)
```
The `Makefile` defines the modules to build and adds the sources to include the `shared-bindings` version and the `common-hal` version within the port specific directory. You may comment out certain subfolders to reduce the number of modules to add but don't comment out individual classes. It won't compile then.
### Hooking the modules in
Built in modules are typically defined in `mpconfigport.h`. To add support you should have something like:
```
extern const struct _mp_obj_module_t microcontroller_module;
extern const struct _mp_obj_module_t analogio_module;
extern const struct _mp_obj_module_t digitalio_module;
extern const struct _mp_obj_module_t pulseio_module;
extern const struct _mp_obj_module_t busio_module;
extern const struct _mp_obj_module_t board_module;
extern const struct _mp_obj_module_t time_module;
extern const struct _mp_obj_module_t neopixel_write_module;
#define MICROPY_PORT_BUILTIN_MODULES \
{ MP_OBJ_NEW_QSTR(MP_QSTR_microcontroller), (mp_obj_t)&microcontroller_module }, \
{ MP_OBJ_NEW_QSTR(MP_QSTR_analogio), (mp_obj_t)&analogio_module }, \
{ MP_OBJ_NEW_QSTR(MP_QSTR_digitalio), (mp_obj_t)&digitalio_module }, \
{ MP_OBJ_NEW_QSTR(MP_QSTR_pulseio), (mp_obj_t)&pulseio_module }, \
{ MP_OBJ_NEW_QSTR(MP_QSTR_busio), (mp_obj_t)&busio_module }, \
{ MP_OBJ_NEW_QSTR(MP_QSTR_board), (mp_obj_t)&board_module }, \
{ MP_OBJ_NEW_QSTR(MP_QSTR_time), (mp_obj_t)&time_module }, \
{ MP_OBJ_NEW_QSTR(MP_QSTR_neopixel_write),(mp_obj_t)&neopixel_write_module } \
```
### Implementing the Common HAL
At this point in the port, nothing will compile yet, because there's still work to be done to fix missing sources, compile issues, and link issues. I suggest start with a common-hal directory from another port that implements it such as `atmel-samd` or `esp8266`, deleting the function contents and stubbing out any return statements. Once that is done, you should be able to compile cleanly and import the modules, but nothing will work (though you are getting closer).
The last step is actually implementing each function in a port specific way. I can't help you with this. :-) If you have any questions how a Common HAL function should work then see the corresponding .h file in `shared-bindings`.
### Testing
Woohoo! You are almost done. After you implement everything, lots of drivers and sample code should just work. There are a number of drivers and examples written for Adafruit's Feather ecosystem. Here are places to start:
* [Adafruit repos with CircuitPython topic](https://github.com/search?q=topic%3Acircuitpython+org%3Aadafruit+fork%3Atrue)
* [Adafruit driver bundle](https://github.com/adafruit/Adafruit_CircuitPython_Bundle)

301
docs/conf.py
View File

@ -1,301 +0,0 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# MicroPython documentation build configuration file, created by
# sphinx-quickstart on Sun Sep 21 11:42:03 2014.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys
import os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('.'))
# The members of the html_context dict are available inside topindex.html
micropy_version = os.getenv('MICROPY_VERSION') or 'latest'
micropy_all_versions = (os.getenv('MICROPY_ALL_VERSIONS') or 'latest').split(',')
url_pattern = '%s/en/%%s' % (os.getenv('MICROPY_URL_PREFIX') or '/',)
html_context = {
'cur_version':micropy_version,
'all_versions':[
(ver, url_pattern % ver) for ver in micropy_all_versions
],
'downloads':[
('PDF', url_pattern % micropy_version + '/micropython-docs.pdf'),
],
}
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'MicroPython'
copyright = '2014-2021, Damien P. George, Paul Sokolovsky, and contributors'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# We don't follow "The short X.Y version" vs "The full version, including alpha/beta/rc tags"
# breakdown, so use the same version identifier for both to avoid confusion.
version = release = '1.16'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['build', '.venv']
# The reST default role (used for this markup: `text`) to use for all
# documents.
default_role = 'any'
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# Global include files. Sphinx docs suggest using rst_epilog in preference
# of rst_prolog, so we follow. Absolute paths below mean "from the base
# of the doctree".
rst_epilog = """
.. include:: /templates/replace.inc
"""
# -- Options for HTML output ----------------------------------------------
# on_rtd is whether we are on readthedocs.org
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if not on_rtd: # only import and set the theme if we're building docs locally
try:
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), '.']
except:
html_theme = 'default'
html_theme_path = ['.']
else:
html_theme_path = ['.']
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = ['.']
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = '../../logo/trans-logo.png'
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
html_favicon = 'static/favicon.ico'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
html_last_updated_fmt = '%d %b %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
html_additional_pages = {"index": "topindex.html"}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'MicroPythondoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
# Include 3 levels of headers in PDF ToC
'preamble': '\setcounter{tocdepth}{2}',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'MicroPython.tex', 'MicroPython Documentation',
'Damien P. George, Paul Sokolovsky, and contributors', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'micropython', 'MicroPython Documentation',
['Damien P. George, Paul Sokolovsky, and contributors'], 1),
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'MicroPython', 'MicroPython Documentation',
'Damien P. George, Paul Sokolovsky, and contributors', 'MicroPython', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'python': ('https://docs.python.org/3.5', None)}

774
docs/design_guide.rst Normal file
View File

@ -0,0 +1,774 @@
.. role:: strike
Design Guide
============
This guide covers a variety of development practices for CircuitPython core and library APIs. These
APIs are both `built-into CircuitPython
<https://github.com/adafruit/circuitpython/tree/main/shared-bindings>`_ and those that are
`distributed on GitHub <https://github.com/search?utf8=%E2%9C%93&q=topic%3Acircuitpython&type=>`_
and in the `Adafruit <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_ and `Community
<https://github.com/adafruit/CircuitPython_Community_Bundle/>`_ bundles. Consistency with these
practices ensures that beginners can learn a pattern once and apply it throughout the CircuitPython
ecosystem.
Start libraries with the cookiecutter
-------------------------------------
Cookiecutter is a tool that lets you bootstrap a new repo based on another repo.
We've made one `here <https://github.com/adafruit/cookiecutter-adafruit-circuitpython>`_
for CircuitPython libraries that include configs for Travis CI and ReadTheDocs
along with a setup.py, license, code of conduct, readme among other files.
.. code-block::sh
# The first time
pip install cookiecutter
cookiecutter gh:adafruit/cookiecutter-adafruit-circuitpython
Cookiecutter will provide a series of prompts relating to the library and then create a new
directory with all of the files. See `the CircuitPython cookiecutter README
<https://github.com/adafruit/cookiecutter-adafruit-circuitpython#introduction>`_ for more details.
Module Naming
-------------
Adafruit funded libraries should be under the
`adafruit organization <https://github.com/adafruit>`_ and have the format
``Adafruit_CircuitPython_<name>`` and have a corresponding ``adafruit_<name>``
directory (aka package) or ``adafruit_<name>.py`` file (aka module).
If the name would normally have a space, such as "Thermal Printer", use an underscore instead
("Thermal_Printer"). This underscore will be used everywhere even when the separation between
"adafruit" and "circuitpython" is done with a ``-``. Use the underscore in the cookiecutter prompts.
Community created libraries should have the repo format ``CircuitPython_<name>`` and
not have the ``adafruit_`` module or package prefix.
Both should have the CircuitPython repository topic on GitHub.
Terminology
-----------
As our Code of Conduct states, we strive to use "welcoming and inclusive
language." Whether it is in documentation or in code, the words we use matter.
This means we disfavor language that due to historical and social context can
make community members and potential community members feel unwelcome.
There are specific terms to avoid except where technical limitations require it.
While specific cases may call for other terms, consider using these suggested
terms first:
+--------------------+---------------------+
| Preferred | Deprecated |
+====================+=====================+
| Main (device) | :strike:`Master` |
+--------------------+---------------------+
| Peripheral | :strike:`Slave` |
+--------------------+ +
| Sensor | |
+--------------------+ +
| Secondary (device) | |
+--------------------+---------------------+
| Denylist | :strike:`Blacklist` |
+--------------------+---------------------+
| Allowlist | :strike:`Whitelist` |
+--------------------+---------------------+
Note that "technical limitations" refers e.g., to the situation where an
upstream library or URL has to contain those substrings in order to work.
However, when it comes to documentation and the names of parameters and
properties in CircuitPython, we will use alternate terms even if this breaks
tradition with past practice.
.. _lifetime-and-contextmanagers:
Lifetime and ContextManagers
--------------------------------------------------------------------------------
A driver should be initialized and ready to use after construction. If the
device requires deinitialization, then provide it through ``deinit()`` and also
provide ``__enter__`` and ``__exit__`` to create a context manager usable with
``with``.
For example, a user can then use ``deinit()```::
import digitalio
import board
import time
led = digitalio.DigitalInOut(board.D13)
led.direction = digitalio.Direction.OUTPUT
for i in range(10):
led.value = True
time.sleep(0.5)
led.value = False
time.sleep(0.5)
led.deinit()
This will deinit the underlying hardware at the end of the program as long as no
exceptions occur.
Alternatively, using a ``with`` statement ensures that the hardware is deinitialized::
import digitalio
import board
import time
with digitalio.DigitalInOut(board.D13) as led:
led.direction = digitalio.Direction.OUTPUT
for i in range(10):
led.value = True
time.sleep(0.5)
led.value = False
time.sleep(0.5)
Python's ``with`` statement ensures that the deinit code is run regardless of
whether the code within the with statement executes without exceptions.
For small programs like the examples this isn't a major concern because all
user usable hardware is reset after programs are run or the REPL is run. However,
for more complex programs that may use hardware intermittently and may also
handle exceptions on their own, deinitializing the hardware using a with
statement will ensure hardware isn't enabled longer than needed.
Verify your device
--------------------------------------------------------------------------------
Whenever possible, make sure device you are talking to is the device you expect.
If not, raise a RuntimeError. Beware that I2C addresses can be identical on
different devices so read registers you know to make sure they match your
expectation. Validating this upfront will help catch mistakes.
Getters/Setters
--------------------------------------------------------------------------------
When designing a driver for a device, use properties for device state and use
methods for sequences of abstract actions that the device performs. State is a
property of the device as a whole that exists regardless of what the code is
doing. This includes things like temperature, time, sound, light and the state
of a switch. For a more complete list see the sensor properties bullet below.
Another way to separate state from actions is that state is usually something
the user can sense themselves by sight or feel for example. Actions are
something the user can watch. The device does this and then this.
Making this separation clear to the user will help beginners understand when to
use what.
Here is more info on properties from
`Python <https://docs.python.org/3/library/functions.html#property>`_.
Exceptions and asserts
--------------------------------------------------------------------------------
Raise an appropriate `Exception <https://docs.python.org/3/library/exceptions.html#bltin-exceptions>`_,
along with a useful message, whenever a critical test or other condition fails.
Example::
if not 0 <= pin <= 7:
raise ValueError("Pin number must be 0-7.")
If memory is constrained and a more compact method is needed, use `assert`
instead.
Example::
assert 0 <= pin <= 7, "Pin number must be 0-7."
Design for compatibility with CPython
--------------------------------------------------------------------------------
CircuitPython is aimed to be one's first experience with code. It will be the
first step into the world of hardware and software. To ease one's exploration
out from this first step, make sure that functionality shared with CPython shares
the same API. It doesn't need to be the full API it can be a subset. However, do
not add non-CPython APIs to the same modules. Instead, use separate non-CPython
modules to add extra functionality. By distinguishing API boundaries at modules
you increase the likelihood that incorrect expectations are found on import and
not randomly during runtime.
When adding a new module for additional functionality related to a CPython
module do NOT simply prefix it with u. This is not a large enough differentiation
from CPython. This is the MicroPython convention and they use u* modules
interchangeably with the CPython name. This is confusing. Instead, think up a
new name that is related to the extra functionality you are adding.
For example, storage mounting and unmounting related functions were moved from
``uos`` into a new `storage` module. Terminal related functions were moved into
`multiterminal`. These names better match their functionality and do not
conflict with CPython names. Make sure to check that you don't conflict with
CPython libraries too. That way we can port the API to CPython in the future.
Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When adding extra functionality to CircuitPython to mimic what a normal
operating system would do, either copy an existing CPython API (for example file
writing) or create a separate module to achieve what you want. For example,
mounting and unmount drives is not a part of CPython so it should be done in a
module, such as a new ``storage`` module, that is only available in CircuitPython.
That way when someone moves the code to CPython they know what parts need to be
adapted.
Document inline
--------------------------------------------------------------------------------
Whenever possible, document your code right next to the code that implements it.
This makes it more likely to stay up to date with the implementation itself. Use
Sphinx's automodule to format these all nicely in ReadTheDocs. The cookiecutter
helps set these up.
Use `Sphinx flavor rST <http://www.sphinx-doc.org/en/stable/rest.html>`_ for markup.
Lots of documentation is a good thing but it can take a lot of space. To
minimize the space used on disk and on load, distribute the library as both .py
and .mpy, MicroPython and CircuitPython's bytecode format that omits comments.
Module description
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
After the license comment::
"""
`<module name>`
=================================================
<Longer description>
* Author(s):
Implementation Notes
--------------------
**Hardware:**
* `Adafruit Device Description
<hyperlink>`_ (Product ID: <Product Number>)
**Software and Dependencies:**
* Adafruit CircuitPython firmware for the supported boards:
https://circuitpython.org/downloads
* Adafruit's Bus Device library:
https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
* Adafruit's Register library:
https://github.com/adafruit/Adafruit_CircuitPython_Register
"""
Class description
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
At the class level document what class does and how to initialize it::
class DS3231:
"""DS3231 real-time clock.
:param ~busio.I2C i2c_bus: The I2C bus the DS3231 is connected to.
:param int address: The I2C address of the device. Defaults to :const:`0x40`
"""
def __init__(self, i2c_bus, address=0x40):
self._i2c = i2c_bus
Renders as:
.. py:class:: DS3231(i2c_bus, address=64)
:noindex:
DS3231 real-time clock.
:param ~busio.I2C i2c_bus: The I2C bus the DS3231 is connected to.
:param int address: The I2C address of the device. Defaults to :const:`0x40`
Documenting Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Although there are different ways to document class and functions definitions in Python,
the following is the prevalent method of documenting parameters
for CircuitPython libraries. When documenting class parameters you should use the
following structure:
.. code-block:: sh
:param param_type param_name: Parameter_description
param_type
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The type of the parameter. This could be among other `int`, `float`, `str` `bool`, etc.
To document an object in the CircuitPython domain, you need to include a ``~`` before the
definition as shown in the following example:
.. code-block:: sh
:param ~busio.I2C i2c_bus: The I2C bus the DS3231 is connected to.
To include references to CircuitPython modules, cookiecutter creates an entry in the
intersphinx_mapping section in the ``conf.py`` file located within the ``docs`` directory.
To add different types outside CircuitPython you need to include them in the intersphinx_mapping::
intersphinx_mapping = {
"python": ("https://docs.python.org/3.4", None),
"BusDevice":("https://circuitpython.readthedocs.io/projects/busdevice/en/latest/", None,),
"CircuitPython": ("https://circuitpython.readthedocs.io/en/latest/", None),
}
The intersphinx_mapping above includes references to Python, BusDevice and CircuitPython
Documentation
When the parameter have two different types, you should reference them as follows::
class Character_LCD:
"""Base class for character LCD
:param ~digitalio.DigitalInOut rs: The reset data line
:param ~pwmio.PWMOut,~digitalio.DigitalInOut blue: Blue RGB Anode
"""
def __init__(self, rs, blue):
self._rc = rs
self.blue = blue
Renders as:
.. py:class:: Character_LCD(rs, blue)
:noindex:
Base class for character LCD
:param ~digitalio.DigitalInOut rs: The reset data line
:param ~pwmio.PWMOut,~digitalio.DigitalInOut blue: Blue RGB Anode
param_name
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter name used in the class or method definition
Parameter_description
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter description. When the parameter defaults to a particular value, it is good
practice to include the default::
:param int pitch: Pitch value for the servo. Defaults to :const:`4500`
Attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Attributes are state on objects. (See `Getters/Setters`_ above for more discussion
about when to use them.) They can be defined internally in a number of different
ways. Each approach is enumerated below with an explanation of where the comment
goes.
Regardless of how the attribute is implemented, it should have a short
description of what state it represents including the type, possible values and/or
units. It should be marked as ``(read-only)`` or ``(write-only)`` at the end of
the first line for attributes that are not both readable and writable.
Instance attributes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Comment comes from after the assignment::
def __init__(self, drive_mode):
self.drive_mode = drive_mode
"""
The pin drive mode. One of:
- `digitalio.DriveMode.PUSH_PULL`
- `digitalio.DriveMode.OPEN_DRAIN`
"""
Renders as:
.. py:attribute:: drive_mode
:noindex:
The pin drive mode. One of:
- `digitalio.DriveMode.PUSH_PULL`
- `digitalio.DriveMode.OPEN_DRAIN`
Property description
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Comment comes from the getter::
@property
def datetime(self):
"""The current date and time as a `time.struct_time`."""
return self.datetime_register
@datetime.setter
def datetime(self, value):
pass
Renders as:
.. py:attribute:: datetime
:noindex:
The current date and time as a `time.struct_time`.
Read-only example::
@property
def temperature(self):
"""
The current temperature in degrees Celsius. (read-only)
The device may require calibration to get accurate readings.
"""
return self._read(TEMPERATURE)
Renders as:
.. py:attribute:: temperature
:noindex:
The current temperature in degrees Celsius. (read-only)
The device may require calibration to get accurate readings.
Data descriptor description
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Comment is after the definition::
lost_power = i2c_bit.RWBit(0x0f, 7)
"""True if the device has lost power since the time was set."""
Renders as:
.. py:attribute:: lost_power
:noindex:
True if the device has lost power since the time was set.
Method description
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
First line after the method definition::
def turn_right(self, degrees):
"""Turns the bot ``degrees`` right.
:param float degrees: Degrees to turn right
"""
Renders as:
.. py:method:: turn_right(degrees)
:noindex:
Turns the bot ``degrees`` right.
:param float degrees: Degrees to turn right
Documentation References to other Libraries
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When you need to make references to documentation in other libraries you should refer the class using single
backticks ``:class:`~adafruit_motor.servo.Servo```. You must also add the reference in the ``conf.py`` file in the
``intersphinx_mapping section`` by adding a new entry::
"adafruit_motor": ("https://circuitpython.readthedocs.io/projects/motor/en/latest/", None,),
Use BusDevice
--------------------------------------------------------------------------------
`BusDevice <https://github.com/adafruit/Adafruit_CircuitPython_BusDevice>`_ is an
awesome foundational library that manages talking on a shared I2C or SPI device
for you. The devices manage locking which ensures that a transfer is done as a
single unit despite CircuitPython internals and, in the future, other Python
threads. For I2C, the device also manages the device address. The SPI device,
manages baudrate settings, chip select line and extra post-transaction clock
cycles.
I2C Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: python
from adafruit_bus_device import i2c_device
DEVICE_DEFAULT_I2C_ADDR = 0x42
class Widget:
"""A generic widget."""
def __init__(self, i2c, address=DEVICE_DEFAULT_I2C_ADDR):
self.i2c_device = i2c_device.I2CDevice(i2c, address)
self.buf = bytearray(1)
@property
def register(self):
"""Widget's one register."""
with self.i2c_device as i2c:
i2c.writeto(b'0x00')
i2c.readfrom_into(self.buf)
return self.buf[0]
SPI Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: python
from adafruit_bus_device import spi_device
class SPIWidget:
"""A generic widget with a weird baudrate."""
def __init__(self, spi, chip_select):
# chip_select is a pin reference such as board.D10.
self.spi_device = spi_device.SPIDevice(spi, chip_select, baudrate=12345)
self.buf = bytearray(1)
@property
def register(self):
"""Widget's one register."""
with self.spi_device as spi:
spi.write(b'0x00')
spi.readinto(self.buf)
return self.buf[0]
Class documentation example template
--------------------------------------------------------------------------------
When documenting classes, you should use the following template to illustrate basic usage.
It is similar with the simpletest example, however this will display the information in the Read The Docs
documentation.
The advantage of using this template is it makes the documentation consistent across the libraries.
This is an example for a AHT20 temperature sensor. Include the following after the class parameter:
.. code-block:: python
"""
**Quickstart: Importing and using the AHT10/AHT20 temperature sensor**
Here is an example of using the :class:`AHTx0` class.
First you will need to import the libraries to use the sensor
.. code-block:: python
import board
import adafruit_ahtx0
Once this is done you can define your `board.I2C` object and define your sensor object
.. code-block:: python
i2c = board.I2C() # uses board.SCL and board.SDA
aht = adafruit_ahtx0.AHTx0(i2c)
Now you have access to the temperature and humidity using
the :attr:`temperature` and :attr:`relative_humidity` attributes
.. code-block:: python
temperature = aht.temperature
relative_humidity = aht.relative_humidity
"""
Use composition
--------------------------------------------------------------------------------
When writing a driver, take in objects that provide the functionality you need
rather than taking their arguments and constructing them yourself or subclassing
a parent class with functionality. This technique is known as composition and
leads to code that is more flexible and testable than traditional inheritance.
.. seealso:: `Wikipedia <https://en.wikipedia.org/wiki/Dependency_inversion_principle>`_
has more information on "dependency inversion".
For example, if you are writing a driver for an I2C device, then take in an I2C
object instead of the pins themselves. This allows the calling code to provide
any object with the appropriate methods such as an I2C expansion board.
Another example is to expect a :py:class:`~digitalio.DigitalInOut` for a pin to
toggle instead of a :py:class:`~microcontroller.Pin` from :py:mod:`board`.
Taking in the :py:class:`~microcontroller.Pin` object alone would limit the
driver to pins on the actual microcontroller instead of pins provided by another
driver such as an IO expander.
Lots of small modules
--------------------------------------------------------------------------------
CircuitPython boards tend to have a small amount of internal flash and a small
amount of ram but large amounts of external flash for the file system. So, create
many small libraries that can be loaded as needed instead of one large file that
does everything.
Speed second
--------------------------------------------------------------------------------
Speed isn't as important as API clarity and code size. So, prefer simple APIs
like properties for state even if it sacrifices a bit of speed.
Avoid allocations in drivers
--------------------------------------------------------------------------------
Although Python doesn't require managing memory, it's still a good practice for
library writers to think about memory allocations. Avoid them in drivers if
you can because you never know how much something will be called. Fewer
allocations means less time spent cleaning up. So, where you can, prefer
bytearray buffers that are created in ``__init__`` and used throughout the
object with methods that read or write into the buffer instead of creating new
objects. Unified hardware API classes such as `busio.SPI` are design to read and
write to subsections of buffers.
It's ok to allocate an object to return to the user. Just beware of causing more
than one allocation per call due to internal logic.
**However**, this is a memory tradeoff so do not do it for large or rarely used
buffers.
Examples
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
struct.pack
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use `struct.pack_into` instead of `struct.pack`.
Use of MicroPython ``const()``
--------------------------------------------------------------------------------
The MicroPython ``const()`` feature, as discussed in `this forum post
<https://forum.micropython.org/viewtopic.php?t=450>`_, and in `this issue thread
<https://github.com/micropython/micropython/issues/573>`_, provides some
optimizations that can be useful on smaller, memory constrained devices. However,
when using ``const()``, keep in mind these general guide lines:
- Always use via an import, ex: ``from micropython import const``
- Limit use to global (module level) variables only.
- If user will not need access to variable, prefix name with a leading
underscore, ex: ``_SOME_CONST``.
Libraries Examples
------------------
When adding examples, cookiecutter will add a ``<name>_simpletest.py`` file in the examples directory for you.
Be sure to include code with the library minimal functionalities to work on a device.
You could other examples if needed featuring different
functionalities of the library.
If you add additional examples, be sure to include them in the ``examples.rst``. Naming of the examples
files should use the name of the library followed by a description, using underscore to separate them.
When using print statements you should use the ``" ".format()`` format, as there are particular boards
that are not capable to use f-strings.
.. code-block:: python
text_to_display = "World!"
print("Hello {}".format(text_to_display))
Sensor properties and units
--------------------------------------------------------------------------------
The `Adafruit Unified Sensor Driver Arduino library <https://learn.adafruit.com/using-the-adafruit-unified-sensor-driver/introduction>`_ has a
`great list <https://learn.adafruit.com/using-the-adafruit-unified-sensor-driver?view=all#standardised-si-units-for-sensor-data>`_
of measurements and their units. Use the same ones including the property name
itself so that drivers can be used interchangeably when they have the same
properties.
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| Property name | Python type | Units |
+=======================+=======================+=========================================================================+
| ``acceleration`` | (float, float, float) | x, y, z meter per second per second |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``magnetic`` | (float, float, float) | x, y, z micro-Tesla (uT) |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``orientation`` | (float, float, float) | x, y, z degrees |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``gyro`` | (float, float, float) | x, y, z radians per second |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``temperature`` | float | degrees Celsius |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``CO2`` | float | measured CO2 in ppm |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``eCO2`` | float | equivalent/estimated CO2 in ppm (estimated from some other measurement) |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``TVOC`` | float | Total Volatile Organic Compounds in ppb |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``distance`` | float | centimeters (cm) |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``proximity`` | int | non-unit-specific proximity values (monotonic but not actual distance) |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``light`` | float | non-unit-specific light levels (should be monotonic but is not lux) |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``lux`` | float | SI lux |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``pressure`` | float | hectopascal (hPa) |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``relative_humidity`` | float | percent |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``current`` | float | milliamps (mA) |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``voltage`` | float | volts (V) |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``color`` | int | RGB, eight bits per channel (0xff0000 is red) |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``alarm`` | (time.struct, str) | Sample alarm time and string to characterize frequency such as "hourly" |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``datetime`` | time.struct | date and time |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``duty_cycle`` | int | 16-bit PWM duty cycle (regardless of output resolution) |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``frequency`` | int | Hertz (Hz) |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``value`` | bool | Digital logic |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``value`` | int | 16-bit Analog value, unit-less |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``weight`` | float | grams (g) |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
| ``sound_level`` | float | non-unit-specific sound level (monotonic but not actual decibels) |
+-----------------------+-----------------------+-------------------------------------------------------------------------+
Adding native modules
--------------------------------------------------------------------------------
The Python API for a new module should be defined and documented in
``shared-bindings`` and define an underlying C API. If the implementation is
port-agnostic or relies on underlying APIs of another module, the code should
live in ``shared-module``. If it is port specific then it should live in ``common-hal``
within the port's folder. In either case, the file and folder structure should
mimic the structure in ``shared-bindings``.
To test your native modules or core enhancements, follow these Adafruit Learning Guides
for building local firmware to flash onto your device(s):
`Build CircuitPython <https://learn.adafruit.com/building-circuitpython>`_
MicroPython compatibility
--------------------------------------------------------------------------------
Keeping compatibility with MicroPython isn't a high priority. It should be done
when it's not in conflict with any of the above goals.

264
docs/develop/cmodules.rst
View File

@ -1,264 +0,0 @@
.. _cmodules:
MicroPython external C modules
==============================
When developing modules for use with MicroPython you may find you run into
limitations with the Python environment, often due to an inability to access
certain hardware resources or Python speed limitations.
If your limitations can't be resolved with suggestions in :ref:`speed_python`,
writing some or all of your module in C (and/or C++ if implemented for your port)
is a viable option.
If your module is designed to access or work with commonly available
hardware or libraries please consider implementing it inside the MicroPython
source tree alongside similar modules and submitting it as a pull request.
If however you're targeting obscure or proprietary systems it may make
more sense to keep this external to the main MicroPython repository.
This chapter describes how to compile such external modules into the
MicroPython executable or firmware image. Both Make and CMake build
tools are supported, and when writing an external module it's a good idea to
add the build files for both of these tools so the module can be used on all
ports. But when compiling a particular port you will only need to use one
method of building, either Make or CMake.
An alternative approach is to use :ref:`natmod` which allows writing custom C
code that is placed in a .mpy file, which can be imported dynamically in to
a running MicroPython system without the need to recompile the main firmware.
Structure of an external C module
---------------------------------
A MicroPython user C module is a directory with the following files:
* ``*.c`` / ``*.cpp`` / ``*.h`` source code files for your module.
These will typically include the low level functionality being implemented and
the MicroPython binding functions to expose the functions and module(s).
Currently the best reference for writing these functions/modules is
to find similar modules within the MicroPython tree and use them as examples.
* ``micropython.mk`` contains the Makefile fragment for this module.
``$(USERMOD_DIR)`` is available in ``micropython.mk`` as the path to your
module directory. As it's redefined for each c module, is should be expanded
in your ``micropython.mk`` to a local make variable,
eg ``EXAMPLE_MOD_DIR := $(USERMOD_DIR)``
Your ``micropython.mk`` must add your modules source files relative to your
expanded copy of ``$(USERMOD_DIR)`` to ``SRC_USERMOD``, eg
``SRC_USERMOD += $(EXAMPLE_MOD_DIR)/example.c``
If you have custom compiler options (like ``-I`` to add directories to search
for header files), these should be added to ``CFLAGS_USERMOD`` for C code
and to ``CXXFLAGS_USERMOD`` for C++ code.
* ``micropython.cmake`` contains the CMake configuration for this module.
In ``micropython.cmake``, you may use ``${CMAKE_CURRENT_LIST_DIR}`` as the path to
the current module.
Your ``micropython.cmake`` should define an ``INTERFACE`` library and associate
your source files, compile definitions and include directories with it.
The library should then be linked to the ``usermod`` target.
.. code-block:: cmake
add_library(usermod_cexample INTERFACE)
target_sources(usermod_cexample INTERFACE
${CMAKE_CURRENT_LIST_DIR}/examplemodule.c
)
target_include_directories(usermod_cexample INTERFACE
${CMAKE_CURRENT_LIST_DIR}
)
target_link_libraries(usermod INTERFACE usermod_cexample)
See below for full usage example.
Basic example
-------------
This simple module named ``cexample`` provides a single function
``cexample.add_ints(a, b)`` which adds the two integer args together and returns
the result. It can be found in the MicroPython source tree
`in the examples directory <https://github.com/micropython/micropython/tree/master/examples/usercmodule/cexample>`_
and has a source file and a Makefile fragment with content as described above::
micropython/
└──examples/
└──usercmodule/
└──cexample/
├── examplemodule.c
├── micropython.mk
└── micropython.cmake
Refer to the comments in these files for additional explanation.
Next to the ``cexample`` module there's also ``cppexample`` which
works in the same way but shows one way of mixing C and C++ code
in MicroPython.
Compiling the cmodule into MicroPython
--------------------------------------
To build such a module, compile MicroPython (see `getting started
<https://github.com/micropython/micropython/wiki/Getting-Started>`_),
applying 2 modifications:
1. Set the build-time flag ``USER_C_MODULES`` to point to the modules
you want to include. For ports that use Make this variable should be a
directory which is searched automatically for modules. For ports that
use CMake this variable should be a file which includes the modules to
build. See below for details.
2. Enable the modules by setting the corresponding C preprocessor macro to
1. This is only needed if the modules you are building are not
automatically enabled.
For building the example modules which come with MicroPython,
set ``USER_C_MODULES`` to the ``examples/usercmodule`` directory for Make,
or to ``examples/usercmodule/micropython.cmake`` for CMake.
For example, here's how the to build the unix port with the example modules:
.. code-block:: bash
cd micropython/ports/unix
make USER_C_MODULES=../../examples/usercmodule
You may need to run ``make clean`` once at the start when including new
user modules in the build. The build output will show the modules found::
...
Including User C Module from ../../examples/usercmodule/cexample
Including User C Module from ../../examples/usercmodule/cppexample
...
For a CMake-based port such as rp2, this will look a little different (note
that CMake is actually invoked by ``make``):
.. code-block:: bash
cd micropython/ports/rp2
make USER_C_MODULES=../../examples/usercmodule/micropython.cmake
Again, you may need to run ``make clean`` first for CMake to pick up the
user modules. The CMake build output lists the modules by name::
...
Including User C Module(s) from ../../examples/usercmodule/micropython.cmake
Found User C Module(s): usermod_cexample, usermod_cppexample
...
The contents of the top-level ``micropython.cmake`` can be used to control which
modules are enabled.
For your own projects it's more convenient to keep custom code out of the main
MicroPython source tree, so a typical project directory structure will look
like this::
my_project/
├── modules/
│ ├── example1/
│ │ ├── example1.c
│ │ ├── micropython.mk
│ │ └── micropython.cmake
│ ├── example2/
│ │ ├── example2.c
│ │ ├── micropython.mk
│ │ └── micropython.cmake
│ └── micropython.cmake
└── micropython/
├──ports/
... ├──stm32/
...
When building with Make set ``USER_C_MODULES`` to the ``my_project/modules``
directory. For example, building the stm32 port:
.. code-block:: bash
cd my_project/micropython/ports/stm32
make USER_C_MODULES=../../../modules
When building with CMake the top level ``micropython.cmake`` -- found directly
in the ``my_project/modules`` directory -- should ``include`` all of the modules
you want to have available:
.. code-block:: cmake
include(${CMAKE_CURRENT_LIST_DIR}/example1/micropython.cmake)
include(${CMAKE_CURRENT_LIST_DIR}/example2/micropython.cmake)
Then build with:
.. code-block:: bash
cd my_project/micropython/ports/esp32
make USER_C_MODULES=../../../../modules/micropython.cmake
Note that the esp32 port needs the extra ``..`` for relative paths due to the
location of its main ``CMakeLists.txt`` file. You can also specify absolute
paths to ``USER_C_MODULES``.
All modules specified by the ``USER_C_MODULES`` variable (either found in this
directory when using Make, or added via ``include`` when using CMake) will be
compiled, but only those which are enabled will be available for importing.
User modules are usually enabled by default (this is decided by the developer
of the module), in which case there is nothing more to do than set ``USER_C_MODULES``
as described above.
If a module is not enabled by default then the corresponding C preprocessor macro
must be enabled. This macro name can be found by searching for the ``MP_REGISTER_MODULE``
line in the module's source code (it usually appears at the end of the main source file).
The third argument to ``MP_REGISTER_MODULE`` is the macro name, and this must be set
to 1 using ``CFLAGS_EXTRA`` to make the module available. If the third argument is just
the number 1 then the module is enabled by default.
For example, the ``examples/usercmodule/cexample`` module is enabled by default so
has the following line in its source code:
.. code-block:: c
MP_REGISTER_MODULE(MP_QSTR_cexample, example_user_cmodule, 1);
Alternatively, to make this module disabled by default but selectable through
a preprocessor configuration option, it would be:
.. code-block:: c
MP_REGISTER_MODULE(MP_QSTR_cexample, example_user_cmodule, MODULE_CEXAMPLE_ENABLED);
In this case the module is enabled by adding ``CFLAGS_EXTRA=-DMODULE_CEXAMPLE_ENABLED=1``
to the ``make`` command, or editing ``mpconfigport.h`` or ``mpconfigboard.h`` to add
.. code-block:: c
#define MODULE_CEXAMPLE_ENABLED (1)
Note that the exact method depends on the port as they have different
structures. If not done correctly it will compile but importing will
fail to find the module.
Module usage in MicroPython
---------------------------
Once built into your copy of MicroPython, the module
can now be accessed in Python just like any other builtin module, e.g.
.. code-block:: python
import cexample
print(cexample.add_ints(1, 3))
# should display 4

317
docs/develop/compiler.rst
View File

@ -1,317 +0,0 @@
.. _compiler:
The Compiler
============
The compilation process in MicroPython involves the following steps:
* The lexer converts the stream of text that makes up a MicroPython program into tokens.
* The parser then converts the tokens into an abstract syntax (parse tree).
* Then bytecode or native code is emitted based on the parse tree.
For purposes of this discussion we are going to add a simple language feature ``add1``
that can be use in Python as:
.. code-block:: bash
>>> add1 3
4
>>>
The ``add1`` statement takes an integer as argument and adds ``1`` to it.
Adding a grammar rule
----------------------
MicroPython's grammar is based on the `CPython grammar <https://docs.python.org/3.5/reference/grammar.html>`_
and is defined in `py/grammar.h <https://github.com/micropython/micropython/blob/master/py/grammar.h>`_.
This grammar is what is used to parse MicroPython source files.
There are two macros you need to know to define a grammar rule: ``DEF_RULE`` and ``DEF_RULE_NC``.
``DEF_RULE`` allows you to define a rule with an associated compile function,
while ``DEF_RULE_NC`` has no compile (NC) function for it.
A simple grammar definition with a compile function for our new ``add1`` statement
looks like the following:
.. code-block:: c
DEF_RULE(add1_stmt, c(add1_stmt), and(2), tok(KW_ADD1), rule(testlist))
The second argument ``c(add1_stmt)`` is the corresponding compile function that should be implemented
in ``py/compile.c`` to turn this rule into executable code.
The third required argument can be ``or`` or ``and``. This specifies the number of nodes associated
with a statement. For example, in this case, our ``add1`` statement is similar to ADD1 in assembly
language. It takes one numeric argument. Therefore, the ``add1_stmt`` has two nodes associated with it.
One node is for the statement itself, i.e the literal ``add1`` corresponding to ``KW_ADD1``,
and the other for its argument, a ``testlist`` rule which is the top-level expression rule.
.. note::
The ``add1`` rule here is just an example and not part of the standard
MicroPython grammar.
The fourth argument in this example is the token associated with the rule, ``KW_ADD1``. This token should be
defined in the lexer by editing ``py/lexer.h``.
Defining the same rule without a compile function is achieved by using the ``DEF_RULE_NC`` macro
and omitting the compile function argument:
.. code-block:: c
DEF_RULE_NC(add1_stmt, and(2), tok(KW_ADD1), rule(testlist))
The remaining arguments take on the same meaning. A rule without a compile function must
be handled explicitly by all rules that may have this rule as a node. Such NC-rules are usually
used to express sub-parts of a complicated grammar structure that cannot be expressed in a
single rule.
.. note::
The macros ``DEF_RULE`` and ``DEF_RULE_NC`` take other arguments. For an in-depth understanding of
supported parameters, see `py/grammar.h <https://github.com/micropython/micropython/blob/master/py/grammar.h>`_.
Adding a lexical token
----------------------
Every rule defined in the grammar should have a token associated with it that is defined in ``py/lexer.h``.
Add this token by editing the ``_mp_token_kind_t`` enum:
.. code-block:: c
:emphasize-lines: 12
typedef enum _mp_token_kind_t {
...
MP_TOKEN_KW_OR,
MP_TOKEN_KW_PASS,
MP_TOKEN_KW_RAISE,
MP_TOKEN_KW_RETURN,
MP_TOKEN_KW_TRY,
MP_TOKEN_KW_WHILE,
MP_TOKEN_KW_WITH,
MP_TOKEN_KW_YIELD,
MP_TOKEN_KW_ADD1,
...
} mp_token_kind_t;
Then also edit ``py/lexer.c`` to add the new keyword literal text:
.. code-block:: c
:emphasize-lines: 12
STATIC const char *const tok_kw[] = {
...
"or",
"pass",
"raise",
"return",
"try",
"while",
"with",
"yield",
"add1",
...
};
Notice the keyword is named depending on what you want it to be. For consistency, maintain the
naming standard accordingly.
.. note::
The order of these keywords in ``py/lexer.c`` must match the order of tokens in the enum
defined in ``py/lexer.h``.
Parsing
-------
In the parsing stage the parser takes the tokens produced by the lexer and converts them to an abstract syntax tree (AST) or
*parse tree*. The implementation for the parser is defined in `py/parse.c <https://github.com/micropython/micropython/blob/master/py/parse.c>`_.
The parser also maintains a table of constants for use in different aspects of parsing, similar to what a
`symbol table <https://steemit.com/programming/@drifter1/writing-a-simple-compiler-on-my-own-symbol-table-basic-structure>`_
does.
Several optimizations like `constant folding <http://compileroptimizations.com/category/constant_folding.htm>`_
on integers for most operations e.g. logical, binary, unary, etc, and optimizing enhancements on parenthesis
around expressions are performed during this phase, along with some optimizations on strings.
It's worth noting that *docstrings* are discarded and not accessible to the compiler.
Even optimizations like `string interning <https://en.wikipedia.org/wiki/String_interning>`_ are
not applied to *docstrings*.
Compiler passes
---------------
Like many compilers, MicroPython compiles all code to MicroPython bytecode or native code. The functionality
that achieves this is implemented in `py/compile.c <https://github.com/micropython/micropython/blob/master/py/compile.c>`_.
The most relevant method you should know about is this:
.. code-block:: c
mp_obj_t mp_compile(mp_parse_tree_t *parse_tree, qstr source_file, bool is_repl) {
// Compile the input parse_tree to a raw-code structure.
mp_raw_code_t *rc = mp_compile_to_raw_code(parse_tree, source_file, is_repl);
// Create and return a function object that executes the outer module.
return mp_make_function_from_raw_code(rc, MP_OBJ_NULL, MP_OBJ_NULL);
}
The compiler compiles the code in four passes: scope, stack size, code size and emit.
Each pass runs the same C code over the same AST data structure, with different things
being computed each time based on the results of the previous pass.
First pass
~~~~~~~~~~
In the first pass, the compiler learns about the known identifiers (variables) and
their scope, being global, local, closed over, etc. In the same pass the emitter
(bytecode or native code) also computes the number of labels needed for the emitted
code.
.. code-block:: c
// Compile pass 1.
comp->emit = emit_bc;
comp->emit_method_table = &emit_bc_method_table;
uint max_num_labels = 0;
for (scope_t *s = comp->scope_head; s != NULL && comp->compile_error == MP_OBJ_NULL; s = s->next) {
if (s->emit_options == MP_EMIT_OPT_ASM) {
compile_scope_inline_asm(comp, s, MP_PASS_SCOPE);
} else {
compile_scope(comp, s, MP_PASS_SCOPE);
// Check if any implicitly declared variables should be closed over.
for (size_t i = 0; i < s->id_info_len; ++i) {
id_info_t *id = &s->id_info[i];
if (id->kind == ID_INFO_KIND_GLOBAL_IMPLICIT) {
scope_check_to_close_over(s, id);
}
}
}
...
}
Second and third passes
~~~~~~~~~~~~~~~~~~~~~~~
The second and third passes involve computing the Python stack size and code size
for the bytecode or native code. After the third pass the code size cannot change,
otherwise jump labels will be incorrect.
.. code-block:: c
for (scope_t *s = comp->scope_head; s != NULL && comp->compile_error == MP_OBJ_NULL; s = s->next) {
...
// Pass 2: Compute the Python stack size.
compile_scope(comp, s, MP_PASS_STACK_SIZE);
// Pass 3: Compute the code size.
if (comp->compile_error == MP_OBJ_NULL) {
compile_scope(comp, s, MP_PASS_CODE_SIZE);
}
...
}
Just before pass two there is a selection for the type of code to be emitted, which can
either be native or bytecode.
.. code-block:: c
// Choose the emitter type.
switch (s->emit_options) {
case MP_EMIT_OPT_NATIVE_PYTHON:
case MP_EMIT_OPT_VIPER:
if (emit_native == NULL) {
emit_native = NATIVE_EMITTER(new)(&comp->compile_error, &comp->next_label, max_num_labels);
}
comp->emit_method_table = NATIVE_EMITTER_TABLE;
comp->emit = emit_native;
break;
default:
comp->emit = emit_bc;
comp->emit_method_table = &emit_bc_method_table;
break;
}
The bytecode option is the default but something unique to note for the native
code option is that there is another option via ``VIPER``. See the
:ref:`Emitting native code <emitting_native_code>` section for more details on
viper annotations.
There is also support for *inline assembly code*, where assembly instructions are
written as Python function calls but are emitted directly as the corresponding
machine code. This assembler has only three passes (scope, code size, emit)
and uses a different implementation, not the ``compile_scope`` function.
See the `inline assembler tutorial <https://docs.micropython.org/en/latest/pyboard/tutorial/assembler.html#pyboard-tutorial-assembler>`_
for more details.
Fourth pass
~~~~~~~~~~~
The fourth pass emits the final code that can be executed, either bytecode in
the virtual machine, or native code directly by the CPU.
.. code-block:: c
for (scope_t *s = comp->scope_head; s != NULL && comp->compile_error == MP_OBJ_NULL; s = s->next) {
...
// Pass 4: Emit the compiled bytecode or native code.
if (comp->compile_error == MP_OBJ_NULL) {
compile_scope(comp, s, MP_PASS_EMIT);
}
}
Emitting bytecode
-----------------
Statements in Python code usually correspond to emitted bytecode, for example ``a + b``
generates "push a" then "push b" then "binary op add". Some statements do not emit
anything but instead affect other things like the scope of variables, for example
``global a``.
The implementation of a function that emits bytecode looks similar to this:
.. code-block:: c
void mp_emit_bc_unary_op(emit_t *emit, mp_unary_op_t op) {
emit_write_bytecode_byte(emit, 0, MP_BC_UNARY_OP_MULTI + op);
}
We use the unary operator expressions for an example here but the implementation
details are similar for other statements/expressions. The method ``emit_write_bytecode_byte()``
is a wrapper around the main function ``emit_get_cur_to_write_bytecode()`` that all
functions must call to emit bytecode.
.. _emitting_native_code:
Emitting native code
---------------------
Similar to how bytecode is generated, there should be a corresponding function in ``py/emitnative.c`` for each
code statement:
.. code-block:: c
STATIC void emit_native_unary_op(emit_t *emit, mp_unary_op_t op) {
vtype_kind_t vtype;
emit_pre_pop_reg(emit, &vtype, REG_ARG_2);
if (vtype == VTYPE_PYOBJ) {
emit_call_with_imm_arg(emit, MP_F_UNARY_OP, op, REG_ARG_1);
emit_post_push_reg(emit, VTYPE_PYOBJ, REG_RET);
} else {
adjust_stack(emit, 1);
EMIT_NATIVE_VIPER_TYPE_ERROR(emit,
MP_ERROR_TEXT("unary op %q not implemented"), mp_unary_op_method_name[op]);
}
}
The difference here is that we have to handle *viper typing*. Viper annotations allow
us to handle more than one type of variable. By default all variables are Python objects,
but with viper a variable can also be declared as a machine-typed variable like a native
integer or pointer. Viper can be thought of as a superset of Python, where normal Python
objects are handled as usual, while native machine variables are handled in an optimised
way by using direct machine instructions for the operations. Viper typing may break
Python equivalence because, for example, integers become native integers and can overflow
(unlike Python integers which extend automatically to arbitrary precision).

19
docs/develop/extendingmicropython.rst
View File

@ -1,19 +0,0 @@
.. _extendingmicropython:
Extending MicroPython in C
==========================
This chapter describes options for implementing additional functionality in C, but from code
written outside of the main MicroPython repository. The first approach is useful for building
your own custom firmware with some project-specific additional modules or functions that can
be accessed from Python. The second approach is for building modules that can be loaded at runtime.
Please see the :ref:`library section <internals_library>` for more information on building core modules that
live in the main MicroPython repository.
.. toctree::
:maxdepth: 3
cmodules.rst
natmod.rst

329
docs/develop/gettingstarted.rst
View File

@ -1,329 +0,0 @@
.. _gettingstarted:
Getting Started
===============
This guide covers a step-by-step process on setting up version control, obtaining and building
a copy of the source code for a port, building the documentation, running tests, and a description of the
directory structure of the MicroPython code base.
Source control with git
-----------------------
MicroPython is hosted on `GitHub <https://github.com/micropython/micropython>`_ and uses
`Git <https://git-scm.com>`_ for source control. The workflow is such that
code is pulled and pushed to and from the main repository. Install the respective version
of Git for your operating system to follow through the rest of the steps.
.. note::
For a reference on the installation instructions, please refer to
the `Git installation instructions <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_.
Learn about the basic git commands in this `Git Handbook <https://guides.github.com/introduction/git-handbook/>`_
or any other sources on the internet.
.. note::
A .git-blame-ignore-revs file is included which avoids the output of git blame getting cluttered
by commits which are only for formatting code but have no functional changes. See `git blame documentation
<https://git-scm.com/docs/git-blame#Documentation/git-blame.txt---ignore-revltrevgt>`_ on how to use this.
Get the code
------------
It is recommended that you maintain a fork of the MicroPython repository for your development purposes.
The process of obtaining the source code includes the following:
#. Fork the repository https://github.com/micropython/micropython
#. You will now have a fork at <https://github.com/<your-user-name>/micropython>.
#. Clone the forked repository using the following command:
.. code-block:: bash
$ git clone https://github.com/<your-user-name>/micropython
Then, `configure the remote repositories <https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes>`_ to be able to
collaborate on the MicroPython project.
Configure remote upstream:
.. code-block:: bash
$ cd micropython
$ git remote add upstream https://github.com/micropython/micropython
It is common to configure ``upstream`` and ``origin`` on a forked repository
to assist with sharing code changes. You can maintain your own mapping but
it is recommended that ``origin`` maps to your fork and ``upstream`` to the main
MicroPython repository.
After the above configuration, your setup should be similar to this:
.. code-block:: bash
$ git remote -v
origin https://github.com/<your-user-name>/micropython (fetch)
origin https://github.com/<your-user-name>/micropython (push)
upstream https://github.com/micropython/micropython (fetch)
upstream https://github.com/micropython/micropython (push)
You should now have a copy of the source code. By default, you are pointing
to the master branch. To prepare for further development, it is recommended
to work on a development branch.
.. code-block:: bash
$ git checkout -b dev-branch
You can give it any name. You will have to compile MicroPython whenever you change
to a different branch.
Compile and build the code
--------------------------
When compiling MicroPython, you compile a specific :term:`port`, usually
targeting a specific :ref:`board <glossary>`. Start by installing the required dependencies.
Then build the MicroPython cross-compiler before you can successfully compile and build.
This applies specifically when using Linux to compile.
The Windows instructions are provided in a later section.
.. _required_dependencies:
Required dependencies
~~~~~~~~~~~~~~~~~~~~~
Install the required dependencies for Linux:
.. code-block:: bash
$ sudo apt-get install build-essential libffi-dev git pkg-config
For the stm32 port, the ARM cross-compiler is required:
.. code-block:: bash
$ sudo apt-get install arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib
See the `ARM GCC
toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm>`_
for the latest details.
Python is also required. Python 2 is supported for now, but we recommend using Python 3.
Check that you have Python available on your system:
.. code-block:: bash
$ python3
Python 3.5.0 (default, Jul 17 2020, 14:04:10)
[GCC 5.4.0 20160609] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
All supported ports have different dependency requirements, see their respective
`readme files <https://github.com/micropython/micropython/tree/master/ports>`_.
Building the MicroPython cross-compiler
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Almost all ports require building ``mpy-cross`` first to perform pre-compilation
of Python code that will be included in the port firmware:
.. code-block:: bash
$ cd mpy-cross
$ make
.. note::
Note that, ``mpy-cross`` must be built for the host architecture
and not the target architecture.
If it built successfully, you should see a message similar to this:
.. code-block:: bash
LINK mpy-cross
text data bss dec hex filename
279328 776 880 280984 44998 mpy-cross
.. note::
Use ``make -C mpy-cross`` to build the cross-compiler in one statement
without moving to the ``mpy-cross`` directory otherwise, you will need
to do ``cd ..`` for the next steps.
Building the Unix port of MicroPython
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Unix port is a version of MicroPython that runs on Linux, macOS, and other Unix-like operating systems.
It's extremely useful for developing MicroPython as it avoids having to deploy your code to a device to test it.
In many ways, it works a lot like CPython's python binary.
To build for the Unix port, make sure all Linux related dependencies are installed as detailed in the
required dependencies section. See the :ref:`required_dependencies`
to make sure that all dependencies are installed for this port. Also, make sure you have a working
environment for ``gcc`` and ``GNU make``. Ubuntu 20.04 has been used for the example
below but other unixes ought to work with little modification:
.. code-block:: bash
$ gcc --version
gcc (Ubuntu 9.3.0-10ubuntu2) 9.3.0
Copyright (C) 2019 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.then build:
.. code-block:: bash
$ cd ports/unix
$ make submodules
$ make
If MicroPython built correctly, you should see the following:
.. code-block:: bash
LINK micropython
text data bss dec hex filename
412033 5680 2496 420209 66971 micropython
Now run it:
.. code-block:: bash
$ ./micropython
MicroPython v1.13-38-gc67012d-dirty on 2020-09-13; linux version
Use Ctrl-D to exit, Ctrl-E for paste mode
>>> print("hello world")
hello world
>>>
Building the Windows port
~~~~~~~~~~~~~~~~~~~~~~~~~
The Windows port includes a Visual Studio project file micropython.vcxproj that you can use to build micropython.exe.
It can be opened in Visual Studio or built from the command line using msbuild. Alternatively, it can be built using mingw,
either in Windows with Cygwin, or on Linux.
See `windows port documentation <https://github.com/micropython/micropython/tree/master/ports/windows>`_ for more information.
Building the STM32 port
~~~~~~~~~~~~~~~~~~~~~~~
Like the Unix port, you need to install some required dependencies
as detailed in the :ref:`required_dependencies` section, then build:
.. code-block:: bash
$ cd ports/stm32
$ make submodules
$ make
Please refer to the `stm32 documentation <https://github.com/micropython/micropython/tree/master/ports/stm32>`_
for more details on flashing the firmware.
.. note::
See the :ref:`required_dependencies` to make sure that all dependencies are installed for this port.
The cross-compiler is needed. ``arm-none-eabi-gcc`` should also be in the $PATH or specified manually
via CROSS_COMPILE, either by setting the environment variable or in the ``make`` command line arguments.
You can also specify which board to use:
.. code-block:: bash
$ cd ports/stm32
$ make submodules
$ make BOARD=<board>
See `ports/stm32/boards <https://github.com/micropython/micropython/tree/master/ports/stm32/boards>`_
for the available boards. e.g. "PYBV11" or "NUCLEO_WB55".
Building the documentation
--------------------------
MicroPython documentation is created using ``Sphinx``. If you have already
installed Python, then install ``Sphinx`` using ``pip``. It is recommended
that you use a virtual environment:
.. code-block:: bash
$ python3 -m venv env
$ source env/bin/activate
$ pip install sphinx
Navigate to the ``docs`` directory:
.. code-block:: bash
$ cd docs
Build the docs:
.. code-block:: bash
$ make html
Open ``docs/build/html/index.html`` in your browser to view the docs locally. Refer to the
documentation on `importing your documentation
<https://docs.readthedocs.io/en/stable/intro/import-guide.html>`_ to use Read the Docs.
Running the tests
-----------------
To run all tests in the test suite on the Unix port use:
.. code-block:: bash
$ cd ports/unix
$ make test
To run a selection of tests on a board/device connected over USB use:
.. code-block:: bash
$ cd tests
$ ./run-tests.py --target minimal --device /dev/ttyACM0
See also :ref:`writingtests`.
Folder structure
----------------
There are a couple of directories to take note of in terms of where certain implementation details
are. The following is a break down of the top-level folders in the source code.
py
Contains the compiler, runtime, and core library implementation.
mpy-cross
Has the MicroPython cross-compiler which pre-compiles the Python scripts to bytecode.
ports
Code for all the versions of MicroPython for the supported ports.
lib
Low-level C libraries used by any port which are mostly 3rd-party libraries.
drivers
Has drivers for specific hardware and intended to work across multiple ports.
extmod
Contains a C implementation of more non-core modules.
docs
Has the standard documentation found at https://docs.micropython.org/.
tests
An implementation of the test suite.
tools
Contains helper tools including the ``upip`` and the ``pyboard.py`` module.
examples
Example code for building MicroPython as a library as well as native modules.

BIN
docs/develop/img/bitmap.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 6.2 KiB

BIN
docs/develop/img/collision.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 3.4 KiB

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