### AHTx0 Sensor Quickstart Example

Source: https://github.com/adafruit/circuitpython/blob/main/docs/design_guide.rst

Provides a quickstart guide for using the AHTx0 temperature and humidity sensor. It includes importing necessary libraries, initializing the I2C object, and creating the sensor instance.

```python
import board
import adafruit_ahtx0

i2c = board.I2C()
# uses board.SCL and board.SDA
aht = adafruit_ahtx0.AHTx0(i2c)
```

```python
temperature = aht.temperature
relative_humidity = aht.relative_humidity
```

--------------------------------

### Install dfu-util on Linux

Source: https://github.com/adafruit/circuitpython/blob/main/ports/stm/boards/espruino_wifi/README.MD

Use apt-get to install the dfu-util utility on Linux systems for flashing firmware.

```bash
sudo apt-get install dfu-util
```

--------------------------------

### Install ESP-IDF Tools

Source: https://github.com/adafruit/circuitpython/blob/main/ports/espressif/README.rst

Run this script from the espressif port root to install necessary ESP-IDF tools.

```bash
./esp-idf/install.sh
```

--------------------------------

### Install mpremote Dependency

Source: https://github.com/adafruit/circuitpython/blob/main/tests/circuitpython-manual/audioio/README.md

Install the necessary mpremote library before running the tests. This is a one-time setup.

```bash
# Install the one dependency (if not already present)
pip install mpremote
```

--------------------------------

### Install Documentation Dependencies

Source: https://github.com/adafruit/circuitpython/blob/main/docs/README.md

Install the required Python packages for building documentation within the circuitpython directory.

```bash
pip install -r requirements-doc.txt
```

--------------------------------

### Example settings.toml File

Source: https://github.com/adafruit/circuitpython/blob/main/docs/environment.rst

This is an example of a settings.toml file. Entries consist of a key and value, separated by an = sign. Upper and lower case may both be used in the key name.

```toml
# Example settings.toml file

[serial]
port="/dev/ttyACM0"
baud=115200

[wifi]
ssid="MySSID"
password="MyPassword"

```

--------------------------------

### Install pre-commit hook

Source: https://github.com/adafruit/circuitpython/blob/main/BUILDING.md

Install the pre-commit framework using pip. This should be done once per system to manage code quality checks.

```bash
python3 -mpip install pre-commit
```

--------------------------------

### Start Host Server

Source: https://github.com/adafruit/circuitpython/blob/main/tests/circuitpython-manual/socketpool/client/readme.md

Command to initiate the server script on the host development machine.

```bash
python host-server.py
```

--------------------------------

### Install dfu-util on Mac

Source: https://github.com/adafruit/circuitpython/blob/main/ports/stm/boards/espruino_wifi/README.MD

Use Homebrew to install the dfu-util utility on macOS for flashing firmware.

```bash
brew install dfu-util
```

--------------------------------

### Run Native Simulator

Source: https://github.com/adafruit/circuitpython/blob/main/ports/zephyr-cp/README.md

Starts the native simulator in real-time mode.

```make
make run-sim
```

--------------------------------

### Install Required Python Packages

Source: https://github.com/adafruit/circuitpython/blob/main/BUILDING.md

Install the necessary Python development packages using pip. Ensure you are using pip3 and the requirements-dev.txt file. If 'minify_html' installation fails, you might need to install Rust.

```bash
pip3 install -r requirements-dev.txt
```

--------------------------------

### Example Usage of --disable-i2c Command-Line Option

Source: https://github.com/adafruit/circuitpython/blob/main/ports/zephyr-cp/tests/docs/i2c_emulator_cmdline_control.md

Demonstrates how to use the '--disable-i2c' command-line option to disable specific I2C devices when starting the native simulation. This includes examples for disabling a single device and multiple devices.

```bash
# Disable a sensor at startup
./build/zephyr/zephyr.exe --disable-i2c=bmi160@68

# Disable multiple devices
./build/zephyr/zephyr.exe --disable-i2c=bmi160@68 --disable-i2c=sht4x@44
```

--------------------------------

### sd_ble_l2cap_ch_setup

Source: https://github.com/adafruit/circuitpython/blob/main/ports/nordic/bluetooth/s140_nrf52_7.0.1/s140_nrf52_7.0.1_API/doc/ble_api.dox

Initiates an L2CAP channel setup process.

```APIDOC
## sd_ble_l2cap_ch_setup

### Description
Initiates the setup of an L2CAP channel. This function handles the connection request and manages the SDU buffer.

### Parameters
- **conn_handle** (integer) - Connection handle
- **local_cid** (integer) - Local channel ID (use INVALID to initiate)
- **le_psm** (integer) - LE Protocol/Service Multiplexer
- **rx_mtu** (integer) - Receive MTU
- **rx_mps** (integer) - Receive MPS
- **sdu_buf** (array) - SDU buffer containing length and data pointer

### Response
- **NRF_SUCCESS** (integer) - Function call successful
- **BLE_L2CAP_EVT_CH_SETUP** (event) - Event triggered on successful channel establishment
- **BLE_L2CAP_EVT_CH_SDU_BUF_RELEASED** (event) - Event triggered if setup fails
```

--------------------------------

### Basic Zephyr Project Setup

Source: https://github.com/adafruit/circuitpython/blob/main/ports/zephyr-cp/CMakeLists.txt

Initializes the Zephyr build system and defines the main application source file.

```cmake
cmake_minimum_required(VERSION 3.20.0)

find_package(Zephyr REQUIRED HINTS lib/zephyr)
project(circuitpython)

target_sources(app PRIVATE zephyr_main.c)
```

--------------------------------

### Install Build Dependencies

Source: https://github.com/adafruit/circuitpython/blob/main/ports/unix/README.md

Install necessary build tools and libraries on Debian-based Linux distributions.

```bash
# apt install build-essential git python3 pkg-config libffi-dev
```

--------------------------------

### CircuitPython REPL Hello World

Source: https://github.com/adafruit/circuitpython/blob/main/ports/silabs/README.md

Example of a simple command executed in the CircuitPython REPL. Ensure you are connected to the board and see the '>>>' prompt.

```python
>>> print("Hello world!")
Hello world!
```

--------------------------------

### Install dfu-util via Package Managers

Source: https://github.com/adafruit/circuitpython/blob/main/ports/stm/boards/espruino_pico/README.md

Commands to install the necessary DFU utility on macOS and Linux systems.

```bash
brew install dfu-util
```

```bash
sudo apt-get install dfu-util
```

--------------------------------

### Example benchmark output

Source: https://github.com/adafruit/circuitpython/blob/main/tests/README.md

Sample output format showing runtime and score metrics for various test modules.

```text
N=2000 M=10000 n_average=8
perf_bench/bm_chaos.py: SKIP
perf_bench/bm_fannkuch.py: 94550.38 2.9145 84.68 2.8499
perf_bench/bm_fft.py: 79920.38 10.0771 129269.74 8.8205
perf_bench/bm_float.py: 43844.62 17.8229 353219.64 17.7693
perf_bench/bm_hexiom.py: 32959.12 15.0243 775.77 14.8893
perf_bench/bm_nqueens.py: 40855.00 10.7297 247776.15 11.3647
perf_bench/bm_pidigits.py: 64547.75 2.5609 7751.36 2.5996
perf_bench/core_import_mpy_multi.py: 15433.38 14.2733 33065.45 14.2368
perf_bench/core_import_mpy_single.py: 263.00 11.3910 3858.35 12.9021
perf_bench/core_qstr.py: 4929.12 1.8434 8117.71 1.7921
perf_bench/core_yield_from.py: 16274.25 6.2584 12334.13 5.8125
perf_bench/misc_aes.py: 57425.25 5.5226 17888.60 5.7482
perf_bench/misc_mandel.py: 40809.25 8.2007 158107.00 9.8864
perf_bench/misc_pystone.py: 39821.75 6.4145 100867.62 6.5043
perf_bench/misc_raytrace.py: 36293.75 6.8501 26906.93 6.8402
perf_bench/viper_call0.py: 15573.00 14.9931 19644.99 13.1550
perf_bench/viper_call1a.py: 16725.75 9.8205 18099.96 9.2752
perf_bench/viper_call1b.py: 20752.62 8.3372 14565.60 9.0663
perf_bench/viper_call1c.py: 20849.88 5.8783 14444.80 6.6295
perf_bench/viper_call2a.py: 16156.25 11.2956 18818.59 11.7959
perf_bench/viper_call2b.py: 22047.38 8.9484 13725.73 9.6800
```

--------------------------------

### Start JLinkGDBServer and arm-none-eabi-gdb

Source: https://github.com/adafruit/circuitpython/blob/main/BUILDING.md

Use these commands to start the GDB server and the GDB client for debugging CircuitPython on hardware. Ensure JLink is connected and the correct device is specified.

```bash
JLinkGDBServer -if SWD -device ATSAMD51J19
```

```bash
arm-none-eabi-gdb build-metro_m4_express/firmware.elf -iex "target extended-remote :2331"
```

--------------------------------

### Example Pin Function Check

Source: https://github.com/adafruit/circuitpython/blob/main/ports/silabs/boards/devkit_xg24_brd2601b/README.md

This example demonstrates how to check if a specific pin can be assigned to a peripheral function using the generated header file. A return value of 1 indicates the function is supported, while 255 means it is not.

```c
pin_pa0_functions[FN_EUSART0_RX] == 1 //   Can assign pin pa0 for EUSART0_RX
             pin_pa0_functions[FN_EUSART0_RX] == 255 // Can't assign pin pa0 for EUSART0_RX
```

--------------------------------

### Run OpenOCD

Source: https://github.com/adafruit/circuitpython/blob/main/ports/espressif/README.rst

Start the OpenOCD server using the specified interface and target configuration files.

```bash
openocd -f interface/jlink.cfg -f SOMEPATH/copied-esp32s2-saola-1.cfg
```

--------------------------------

### Install Build Dependencies

Source: https://github.com/adafruit/circuitpython/blob/main/ports/silabs/README.md

Required packages for building the port on Linux systems.

```bash
sudo apt install default-jre gcc-arm-none-eabi wget python3 python3-pip git git-lfs gettext uncrustify
sudo python -m pip install --upgrade pip
```

--------------------------------

### Manage Packages with mip

Source: https://github.com/adafruit/circuitpython/blob/main/ports/unix/README.md

Install packages using the built-in mip manager via command line or REPL.

```bash
$ ./build-standard/micropython -m mip install hmac
```

```bash
$ ./build-standard/micropython
>>> import mip
>>> mip.install("hmac")
```

--------------------------------

### GET /cp/version.json

Source: https://github.com/adafruit/circuitpython/blob/main/docs/workflows.md

Returns information about the device and firmware version.

```APIDOC
## GET /cp/version.json

### Description
Returns metadata about the device, including firmware version and network details.

### Method
GET

### Endpoint
/cp/version.json

### Response
#### Success Response (200)
- **web_api_version** (integer) - API version.
- **version** (string) - CircuitPython build version.
- **build_date** (string) - CircuitPython build date.
- **board_name** (string) - Human readable name of the board.
- **mcu_name** (string) - Human readable name of the microcontroller.
- **board_id** (string) - Board id.
- **creator_id** (integer) - Creator ID.
- **creation_id** (integer) - Creation ID.
- **hostname** (string) - MDNS hostname.
- **port** (integer) - Port of CircuitPython Web Service.
- **ip** (string) - IP address.
```

--------------------------------

### Define Method with Parameters

Source: https://github.com/adafruit/circuitpython/blob/main/docs/design_guide.rst

Example of documenting a method and its parameters using reStructuredText format.

```python
def turn_right(self, degrees):
    """Turns the bot ``degrees`` right.

       :param float degrees: Degrees to turn right
    """
```

--------------------------------

### Install CircuitPython via dfu-util

Source: https://github.com/adafruit/circuitpython/blob/main/ports/litex/README.rst

Use this command to flash the CircuitPython DFU file to the Fomu device. Ensure the bootloader is updated before execution.

```shell
dfu-util -D adafruit-circuitpython-fomu-en_US-<version>.dfu
```

--------------------------------

### Customize Documentation Build Options

Source: https://github.com/adafruit/circuitpython/blob/main/docs/README.md

Examples of overriding default Makefile variables to control rebuild behavior, verbosity, and Sphinx options.

```bash
# will turn OFF the force rebuild
make html FORCE=

# will turn OFF the verbosity
make html VERBOSE=

# will turn OFF the force rebuild and make it doubly verbose when running
make html FORCE= VERBOSE="-v -v"
```

```bash
make html SPHINXOPTS="-T"
```

--------------------------------

### Example Allocation Tree Output

Source: https://github.com/adafruit/circuitpython/blob/main/tools/gc_activity.md

A sample representation of the block allocation tree generated by the analysis script.

```text
main.c:298 main 5 blocks
 main.c:159 reset_mp 2 blocks
   ../py/runtime.c:81 mp_init 2 blocks
     ../py/objmodule.c:227 mp_module_init 2 blocks
       ../py/objdict.c:595 mp_obj_dict_init 2 blocks
         ../py/map.c:79 mp_map_init 2 blocks
 main.c:160 reset_mp 1 blocks
   ../py/objlist.c:458 mp_obj_list_init 1 blocks
 main.c:164 reset_mp 1 blocks
   ../py/objlist.c:458 mp_obj_list_init 1 blocks
 main.c:166 reset_mp 1 blocks
   ../py/objexcept.c:297 mp_obj_new_exception 1 blocks
     ../py/objexcept.c:307 mp_obj_new_exception_args 1 blocks
       ../py/objexcept.c:130 mp_obj_exception_make_new 1 blocks
main.c:311 main 289 blocks
 main.c:211 start_mp 14 blocks
   main.c:196 maybe_run 14 blocks
     ../shared/runtime/pyexec.c:501 pyexec_file 14 blocks
       main.c:352 mp_lexer_new_from_file 14 blocks
         ../py/../extmod/vfs_fat_lexer.c:80 fat_vfs_lexer_new_from_file 14 blocks
           ../py/qstr.c:184 qstr_from_str 14 blocks
             ../py/qstr.c:216 qstr_from_strn 8 blocks
             ../py/qstr.c:240 qstr_from_strn 6 blocks
               ../py/qstr.c:146 qstr_add 6 blocks
 main.c:220 start_mp 275 blocks
   main.c:196 maybe_run 275 blocks
     ../shared/runtime/pyexec.c:508 pyexec_file 275 blocks
       ../shared/runtime/pyexec.c:82 parse_compile_execute 4 blocks
         ../py/compile.c:3511 mp_compile 3 blocks
           ../py/compile.c:3451 mp_compile_to_raw_code 3 blocks
             ../py/compile.c:3092 compile_scope 3 blocks
               ../py/emitbc.c:419 mp_emit_bc_end_pass 3 blocks
         ../py/compile.c:3513 mp_compile 1 blocks
           ../py/emitglue.c:131 mp_make_function_from_raw_code 1 blocks
             ../py/objfun.c:364 mp_obj_new_fun_bc 1 blocks
       ../shared/runtime/pyexec.c:88 parse_compile_execute 271 blocks
         ../py/runtime.c:551 mp_call_function_0 271 blocks
           ../py/runtime.c:577 mp_call_function_n_kw 271 blocks
             ../py/objfun.c:275 fun_bc_call 271 blocks
               ../py/vm.c:1161 mp_execute_bytecode 269 blocks
                 ../py/runtime.c:1315 mp_import_name 269 blocks
                   ../py/builtinimport.c:442 mp_builtin___import__ 2 blocks
                     ../py/objmodule.c:113 mp_obj_new_module 1 blocks
                     ../py/objmodule.c:115 mp_obj_new_module 1 blocks
                       ../py/objdict.c:599 mp_obj_new_dict 1 blocks
                   ../py/builtinimport.c:473 mp_builtin___import__ 267 blocks
                     ../py/builtinimport.c:230 do_load 140 blocks
                       ../py/emitglue.c:469 mp_raw_code_load_file 140 blocks
                         ../py/emitglue.c:356 mp_raw_code_load 140 blocks
                           ../py/emitglue.c:320 load_raw_code 8 blocks
                             ../py/emitglue.c:295 load_bytecode_qstrs 8 blocks
                               ../py/emitglue.c:265 load_qstr 8 blocks
                                 ../py/qstr.c:216 qstr_from_strn 8 blocks
                           ../py/emitglue.c:331 load_raw_code 2 blocks
                             ../py/emitglue.c:277 load_obj 1 blocks
                               ../py/vstr.c:53 vstr_init_len 1 blocks
                                 ../py/vstr.c:46 vstr_init 1 blocks
                             ../py/emitglue.c:280 load_obj 1 blocks
                               ../py/objstr.c:2001 mp_obj_new_str_from_vstr 1 blocks
                           ../py/emitglue.c:334 load_raw_code 130 blocks
                             ../py/emitglue.c:306 load_raw_code 6 blocks
                             ../py/emitglue.c:325 load_raw_code 4 blocks
                             ../py/emitglue.c:328 load_raw_code 19 blocks
                               ../py/emitglue.c:265 load_qstr 19 blocks
                                 ../py/qstr.c:216 qstr_from_strn 8 blocks
                                 ../py/qstr.c:240 qstr_from_strn 11 blocks
```

--------------------------------

### Initialize Zephyr Development Environment

Source: https://github.com/adafruit/circuitpython/blob/main/ports/zephyr-cp/README.md

Commands to install dependencies and initialize the Zephyr workspace.

```sh
pip install west
west init -l zephyr-config
west update
west zephyr-export
pip install -r zephyr/scripts/requirements.txt
west sdk install
```

--------------------------------

### L2CAP Channel Setup - Locally Initiated, Success

Source: https://github.com/adafruit/circuitpython/blob/main/ports/nordic/bluetooth/s140_nrf52_6.1.0/s140_nrf52_6.1.0_API/doc/ble_api.dox

Details the message sequence for establishing an L2CAP channel initiated by the local device, resulting in a successful connection.

```APIDOC
## L2CAP Channel Setup - Locally Initiated, Success

### Description
This sequence chart illustrates the process of setting up an L2CAP channel when the local application initiates the connection, and the establishment is successful.

### Method
N/A (Sequence Chart)

### Endpoint
N/A (Sequence Chart)

### Request Example
```
APP=>SD [label = "sd_ble_l2cap_ch_setup(conn_handle, local_cid=INVALID, le_psm, rx_mtu, rx_mps, sdu_buf: [len, p_data1])"]
```

### Response Example
```
APP<<SD [label = "NRF_SUCCESS"]
SD:>PEER [label = "L2CAP LE Credit Based Connection Request"]
SD<:PEER [label = "L2CAP LE Credit Based Connection Response: Connection successful"]
APP<<=SD [label = "BLE_L2CAP_EVT_CH_SETUP {conn_handle, local_cid, tx_mtu, tx_mps, credits}"]
```
```

--------------------------------

### GET /fs/

Source: https://github.com/adafruit/circuitpython/blob/main/docs/workflows.md

Retrieves a directory listing of the root file system or a JSON representation if `Accept: application/json` is provided. Requires authentication.

```APIDOC
## GET /fs/

### Description

The `/fs/` endpoint provides access to the CircuitPython file system. By default, it returns an HTML page for directory browsing. If the `Accept: application/json` header is included in the request, it returns a JSON representation of the root directory.

### Method

GET

### Endpoint

`/fs/`

### Parameters

#### Query Parameters

- `Accept` (string) - Optional - Set to `application/json` to receive a JSON response instead of HTML.

#### Request Headers

- `Authorization` (string) - Required - HTTP Basic Authentication header. Format: `Basic <base64_encoded_username:password>`. The username should be empty.

### Request Example (HTML)

```bash
curl -v -u :passw0rd http://circuitpython.local/fs/
```

### Request Example (JSON)

```bash
curl -v -u :passw0rd -H "Accept: application/json" http://circuitpython.local/fs/
```

### Response

#### Success Response (200 OK)

- **Content-Type**: `text/html` or `application/json`
- **Body**: HTML directory listing or JSON object representing the file system structure.

#### Response Example (JSON)

```json
{
  "name": "/",
  "size": 0,
  "mtime": 1678886400.0,
  "type": "directory",
  "children": [
    {
      "name": "code.py",
      "size": 1024,
      "mtime": 1678886400.0,
      "type": "file"
    },
    {
      "name": "lib",
      "size": 0,
      "mtime": 1678886400.0,
      "type": "directory",
      "children": []
    }
  ]
}
```

#### Error Responses

- **401 Unauthorized**: Missing or incorrect credentials.
- **403 Forbidden**: API password not configured.
```

--------------------------------

### Get Help for mpy-cross

Source: https://github.com/adafruit/circuitpython/blob/main/mpy-cross/README.md

Display the help message for the mpy-cross compiler to see all available options. This is useful for understanding advanced configurations.

```bash
./mpy-cross -h
```

--------------------------------

### Initialize submodules

Source: https://github.com/adafruit/circuitpython/blob/main/ports/cxd56/README.md

Download all required submodules for the repository.

```bash
$ git submodule update --init --recursive
```

--------------------------------

### Clone and Prepare Source

Source: https://github.com/adafruit/circuitpython/blob/main/ports/silabs/README.md

Commands to clone the repository and initialize necessary submodules.

```bash
$  git clone https://github.com/SiliconLabs/circuitpython.git
$  cd circuitpython/ports/silabs
$  make fetch-port-submodules
```

--------------------------------

### Build Documentation

Source: https://github.com/adafruit/circuitpython/blob/main/docs/README.md

Execute the build command to generate HTML documentation files.

```bash
make html
```

--------------------------------

### Class Initialization Documentation

Source: https://github.com/adafruit/circuitpython/blob/main/docs/design_guide.rst

Standard format for documenting class constructors and parameters.

```python
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
```

--------------------------------

### Build and Manage Project

Source: https://github.com/adafruit/circuitpython/blob/main/ports/silabs/README.md

Standard commands for building, debugging, and cleaning the project.

```bash
make BOARD=explorerkit_xg24_brd2703a
```

```bash
make BOARD=explorerkit_xg24_brd2703a DEBUG=1
```

```bash
make BOARD=explorerkit_xg24_brd2703a clean
```

--------------------------------

### Install adafruit-nrfutil

Source: https://github.com/adafruit/circuitpython/blob/main/ports/nordic/README.md

Install the adafruit-nrfutil package from PyPi to manage DFU operations. This is required for DFU targets.

```bash
$ pip3 install --user adafruit-nrfutil
```

--------------------------------

### Building with Device Tree Overlay

Source: https://github.com/adafruit/circuitpython/blob/main/ports/zephyr-cp/tests/docs/i2c_emulator_cmdline_control.md

Provides the command to build the native simulation with a specified device tree overlay file, enabling compile-time configuration of hardware emulation.

```bash
west build -b native_sim -- -DDTC_OVERLAY_FILE=boards/native_sim_no_bmi160.overlay
```

--------------------------------

### GET File Contents with curl

Source: https://github.com/adafruit/circuitpython/blob/main/docs/workflows.md

Retrieve the raw content of a file using the GET method. The Content-Type header will be set based on the file extension.

```sh
curl -v -u :passw0rd -L --location-trusted http://circuitpython.local/fs/lib/hello/world.txt
```

--------------------------------

### Build and Run MicroPython

Source: https://github.com/adafruit/circuitpython/blob/main/ports/unix/README.md

Standard commands to initialize the build environment, compile the executable, and launch the REPL.

```bash
$ cd ports/unix
$ make -C ../../mpy-cross
$ make submodules
```

```bash
$ make
```

```bash
$ ./build-standard/micropython
>>> list(5 * x + y for x in range(10) for y in [4, 2, 1])
```

--------------------------------

### Start Renode GDB Server

Source: https://github.com/adafruit/circuitpython/blob/main/ports/renode/README.md

Starts a GDB server on port 3333 for debugging the emulator. Set the second argument to 'false' to disable the server.

```renode
machine StartGdbServer 3333 true
```

--------------------------------

### Interpreting pin_functions.h Example

Source: https://github.com/adafruit/circuitpython/blob/main/ports/silabs/boards/explorerkit_xg24_brd2703a/README.md

This example from `pin_functions.h` demonstrates how to check if a specific pin can be assigned to a particular function. A value of 1 indicates it can be assigned, while 255 means it cannot.

```c
pin_pa0_functions[FN_EUSART0_RX] == 1 //   Can assign pin pa0 for EUSART0_RX
pin_pa0_functions[FN_EUSART0_RX] == 255 // Can't assign pin pa0 for EUSART0_RX
```

--------------------------------

### L2CAP Channel Setup Sequence

Source: https://github.com/adafruit/circuitpython/blob/main/ports/nordic/bluetooth/s140_nrf52_6.1.0/s140_nrf52_6.1.0_API/doc/ble_api.dox

Demonstrates a successful L2CAP channel setup initiated locally. This includes the API call, success event, and the L2CAP LE Credit Based Connection Request/Response.

```msc
hscale = "1.5"
APP,SD,PEER;
|||;
APP rbox PEER [label="Connection Established"];
|||;
--- [label = " Variant #1 Locally initiated, Establishment success "];
APP=>SD [label = "sd_ble_l2cap_ch_setup(conn_handle, local_cid=INVALID, le_psm, rx_mtu, rx_mps, sdu_buf: [len, p_data1])"];
APP<<SD [label = "NRF_SUCCESS"];
SD:>PEER [label = "L2CAP LE Credit Based Connection Request", textcolor="#000080", linecolor="#000080"];
SD<:PEER [label = "L2CAP LE Credit Based Connection Response: Connection successful", textcolor="#000080", linecolor="#000080"];
APP<<=SD [label = "BLE_L2CAP_EVT_CH_SETUP {conn_handle, local_cid, tx_mtu, tx_mps, credits}"];
|||;
APP rbox PEER [label="L2CAP Channel Established"];
|||;
```

--------------------------------

### Build with Debug and Bootloader Flags

Source: https://github.com/adafruit/circuitpython/blob/main/ports/stm/README.md

Compile with debug symbols enabled and configuration for a pre-flashed UF2 bootloader.

```bash
$ make BOARD=feather_stm32f405_express DEBUG=1 UF2_BOOTLOADER=1
```

--------------------------------

### GET /cp/diskinfo.json

Source: https://github.com/adafruit/circuitpython/blob/main/docs/workflows.md

Returns information about the attached disk(s).

```APIDOC
## GET /cp/diskinfo.json

### Description
Returns information about the attached disk(s) as a list of objects.

### Method
GET

### Endpoint
/cp/diskinfo.json

### Response
#### Success Response (200)
- **root** (string) - Filesystem path to the root of the disk.
- **free** (integer) - Count of free blocks on the disk.
- **total** (integer) - Total blocks that make up the disk.
- **block_size** (integer) - Size of a block in bytes.
- **writable** (boolean) - True when CircuitPython and the web workflow can write to the disk.
```

--------------------------------

### sd_ble_gap_scan_start

Source: https://github.com/adafruit/circuitpython/blob/main/ports/nordic/bluetooth/s140_nrf52_6.1.0/s140_nrf52_6.1.0_API/doc/ble_api.dox

Starts the scanning procedure for BLE advertisers.

```APIDOC
## sd_ble_gap_scan_start

### Description
Initiates the scanning process to discover advertisers. Supports both legacy and extended advertising modes.

### Parameters
- **params** (ble_gap_scan_params_t) - Required - Configuration parameters including extended mode and active scanning flags.
- **adv_report_buffer** (ble_data_t) - Required - Buffer to store incoming advertisement reports.

### Response
- **NRF_SUCCESS** (uint32_t) - Scanning started successfully.
- **BLE_GAP_EVT_ADV_REPORT** (event) - Event triggered when an advertisement is received.
- **BLE_GAP_EVT_TIMEOUT** (event) - Event triggered when the scan duration expires.
```

--------------------------------

### Configure Wi-Fi and Web Workflow in settings.toml

Source: https://github.com/adafruit/circuitpython/blob/main/docs/workflows.md

Set these keys in `settings.toml` to enable automatic Wi-Fi connection on boot and to activate the web workflow. The web API password is required for the web workflow.

```bash
# To auto-connect to Wi-Fi
CIRCUITPY_WIFI_SSID="scottswifi"
CIRCUITPY_WIFI_PASSWORD="secretpassword"

# To enable the web workflow. Change this too!
# Leave the User field blank in the browser.
CIRCUITPY_WEB_API_PASSWORD="passw0rd"

CIRCUITPY_WEB_API_PORT=80
CIRCUITPY_WEB_INSTANCE_NAME=""
```

--------------------------------

### Build CircuitPython for Nordic Board

Source: https://github.com/adafruit/circuitpython/blob/main/BUILDING.md

Example of building CircuitPython for a board supported by the Nordic port. Change directory to 'ports/nordic' and specify the desired BOARD. Consult the 'boards' subdirectory for available board names.

```bash
cd ports/nordic
make BOARD=circuitplayground_bluefruit
```

--------------------------------

### SPI Device Initialization and Usage

Source: https://github.com/adafruit/circuitpython/blob/main/docs/design_guide.rst

Shows how to initialize an SPIDevice with a custom baudrate and perform SPI read/write operations. The chip_select argument should be a pin reference.

```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]
```

--------------------------------

### Access Help and Test Suite

Source: https://github.com/adafruit/circuitpython/blob/main/ports/unix/README.md

Commands for viewing command-line options and executing the test suite.

```bash
$ ./build-standard/micropython -h
```

```bash
$ make test
```

```bash
$ make test//int       # Run all tests matching the pattern "int"
$ make test/ports/unix # Run all tests in ports/unix
$ make test-failures   # Re-run only the failed tests
$ make print-failures  # print the differences for failed tests
$ make clean-failures  # delete the .exp and .out files from failed tests
```

--------------------------------

### sd_ble_gap_scan_start

Source: https://github.com/adafruit/circuitpython/blob/main/ports/nordic/bluetooth/s140_nrf52_7.0.1/s140_nrf52_7.0.1_API/doc/ble_api.dox

Starts the BLE scanning procedure for legacy or extended advertising.

```APIDOC
## sd_ble_gap_scan_start

### Description
Starts the scanning procedure to discover advertisers. Supports legacy and extended advertising modes.

### Parameters
- **params** (ble_gap_scan_params_t*) - Required - Scanning parameters including extended mode and active scanning flags.
- **adv_report_buffer** (ble_data_t*) - Required - Buffer to store advertisement reports.

### Response
- **NRF_SUCCESS** (uint32_t) - Successfully started scanning.
- **BLE_GAP_EVT_ADV_REPORT** (event) - Event triggered when an advertisement is received.
- **BLE_GAP_EVT_TIMEOUT** (event) - Event triggered when the scan times out.
```

--------------------------------

### Initialize Tracing

Source: https://github.com/adafruit/circuitpython/blob/main/ports/zephyr-cp/docs/perfetto-tracing.md

Ensure perfetto_start is called before emitting trace events to maintain correct incremental state.

```c
if (!started) {
    perfetto_start();
}
```

--------------------------------

### Define Datetime Property

Source: https://github.com/adafruit/circuitpython/blob/main/docs/design_guide.rst

Example of documenting a property with both a getter and a setter.

```python
@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
```

--------------------------------

### Test boot.py and code.py execution order

Source: https://github.com/adafruit/circuitpython/blob/main/ports/zephyr-cp/tests/TEST_IDEAS.md

Verifies that boot.py runs before code.py. Ensure boot.py and code.py are in the root directory.

```python
# boot.py
print("boot.py ran")

# code.py
print("code.py ran")
```

--------------------------------

### GET /cp/devices.json

Source: https://github.com/adafruit/circuitpython/blob/main/docs/workflows.md

Returns information about other devices found on the network using MDNS.

```APIDOC
## GET /cp/devices.json

### Description
Returns a list of discovered devices on the network.

### Method
GET

### Endpoint
/cp/devices.json

### Response
#### Success Response (200)
- **total** (integer) - Total MDNS response count.
- **devices** (array) - List of discovered devices.
  - **hostname** (string) - MDNS hostname
  - **instance_name** (string) - MDNS instance name
  - **port** (integer) - Port of CircuitPython Web API
  - **ip** (string) - IP address
```

--------------------------------

### Web Server Configuration

Source: https://github.com/adafruit/circuitpython/blob/main/docs/workflows.md

Configure Wi-Fi connection and enable the web workflow by setting specific keys in `settings.toml`.

```APIDOC
## Web Server Configuration

To enable Wi-Fi connectivity and the web workflow, configure the following settings in your `settings.toml` file:

### `settings.toml` Example

```bash
# To auto-connect to Wi-Fi
CIRCUITPY_WIFI_SSID="your_ssid"
CIRCUITPY_WIFI_PASSWORD="your_password"

# To enable the web workflow. Change this too!
# Leave the User field blank in the browser.
CIRCUITPY_WEB_API_PASSWORD="your_api_password"

# Optional: Override default port (80)
# CIRCUITPY_WEB_API_PORT=8080

# Optional: Override MDNS instance name
# CIRCUITPY_WEB_INSTANCE_NAME="my-circuitpython-board"
```

### Configuration Details

- `CIRCUITPY_WIFI_SSID`: The SSID of the Wi-Fi network.
- `CIRCUITPY_WIFI_PASSWORD`: The password for the Wi-Fi network.
- `CIRCUITPY_WEB_API_PASSWORD`: Sets the password for accessing the web API. If not set, the web workflow will not start.
- `CIRCUITPY_WEB_API_PORT` (Optional): The port for the HTTP server. Defaults to 80.
- `CIRCUITPY_WEB_INSTANCE_NAME` (Optional): The name advertised on the network via MDNS. Defaults to a name derived from the MAC address.
```

--------------------------------

### Flash Firmware

Source: https://github.com/adafruit/circuitpython/blob/main/ports/silabs/README.md

Flash the compiled binary to the target board using Simplicity Commander.

```bash
make BOARD=explorerkit_xg24_brd2703a flash
```

--------------------------------

### python_compiler() - Get Compiler Information

Source: https://github.com/adafruit/circuitpython/blob/main/docs/library/platform.rst

Returns a string identifying the compiler used for compiling MicroPython.

```APIDOC
## python_compiler()

### Description
Returns a string identifying the compiler used for compiling MicroPython.

### Method
GET

### Endpoint
/python_compiler

### Returns
- **compiler_info** (string) - The name of the compiler used.
```

--------------------------------

### Configure PicoDVI Display Initialization

Source: https://github.com/adafruit/circuitpython/blob/main/docs/environment.rst

Control PicoDVI display initialization at board startup. Options are 'detect' (default), 'always', or 'never'.

```text
CIRCUITPY_PICODVI_ENABLE="detect"
```

```text
CIRCUITPY_PICODVI_ENABLE="always"
```

```text
CIRCUITPY_PICODVI_ENABLE="never"
```

--------------------------------

### Define RWBit Data Descriptor

Source: https://github.com/adafruit/circuitpython/blob/main/docs/design_guide.rst

Example of documenting a data descriptor using a docstring after the definition.

```python
lost_power = i2c_bit.RWBit(0x0f, 7)
"""True if the device has lost power since the time was set."""
```

--------------------------------

### Define Read-Only Temperature Property

Source: https://github.com/adafruit/circuitpython/blob/main/docs/design_guide.rst

Example of documenting a read-only property that may require calibration.

```python
@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)
```

--------------------------------

### Match Regex from Start of String

Source: https://github.com/adafruit/circuitpython/blob/main/docs/library/re.rst

Compiles a regular expression and attempts to match it against the beginning of a given string.

```python
re.match(regex_str, string)
```

--------------------------------

### Build CircuitPython for Atmel SAMD Board

Source: https://github.com/adafruit/circuitpython/blob/main/BUILDING.md

Navigate to the specific port directory (e.g., ports/atmel-samd) and use 'make' to build CircuitPython for a particular board. Replace 'circuitplayground_express' with your target board name.

```bash
cd ports/atmel-samd
make BOARD=circuitplayground_express
```