Metadata-Version: 2.4
Name: picokit
Version: 0.1.0
Summary: Raspberry Pi Pico development helper for installing Pico SDK and ARM GCC toolchain.
Author-email: obviousfancy <jonathanmejoradolopez@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/obviousfancy/picosdk
Project-URL: Source, https://github.com/obviousfancy/picosdk
Project-URL: Issues, https://github.com/obviousfancy/picosdk/issues
Keywords: pico,raspberry-pi-pico,pico-sdk,arm-gcc,picokit,rp2040
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Embedded Systems
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi>=2024.7.4
Requires-Dist: pyocd<0.45,>=0.44.0
Requires-Dist: tomli>=2.0.1; python_version < "3.11"
Dynamic: license-file

# picokit

`picokit` is a Python CLI package for Raspberry Pi Pico development. It installs the
Pico SDK and ARM GCC toolchain for the current operating system, creates Pico C/C++
projects, and runs build/flash commands from `picokit.toml`.

## Install

```bash
pip install picokit
```

For local development from this repository:

```bash
pip install -e .
```

## Commands

```bash
picokit doctor
picokit install
picokit new blink
picokit new hello-world
cd blink
picokit build
picokit clean
picokit flash
```

The CLI can also be invoked through the Python interpreter, including on Windows:

```bash
python -m picokit --help
python -m picokit --version
```

`picokit install` downloads the Pico SDK and ARM GCC toolchain. The installer selects 
the correct toolchain for:

- Linux x64
- Linux arm64  
- macOS x64
- macOS arm64
- Windows x64

The default install location is `~/.picokit`. Set `PICOKIT_HOME` to use a
different directory.

`picokit build` and `picokit flash` automatically run with the installed Pico SDK 
and ARM GCC toolchain environment. You do not need to manually configure paths.
`picokit doctor` checks the tools required by the current platform.

The installed tree layout:

```text
~/.picokit/toolchains/pico-sdk-2.0.0/
  pico-sdk/
~/.picokit/toolchains/arm-none-eabi-gcc-13.2.1/
  bin/
  arm-none-eabi/
```

## Pico SDK and Toolchain Sources

Pico SDK: https://github.com/raspberrypi/pico-sdk

ARM GCC: https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads

Downloaded archives are verified with SHA-256 digests.

## Custom Toolchain Locations

By default, `picokit` uses the toolchains installed in `~/.picokit/toolchains`. You can
override these locations using environment variables:

- **`PICO_SDK_PATH`**: Path to a custom Pico SDK installation
- **`PICO_TOOLCHAIN_PATH`**: Path to a custom ARM GCC toolchain installation

When these variables are set, `picokit build` will automatically:
1. Use the custom toolchain/SDK paths
2. Add the toolchain's `bin` directory to PATH
3. Configure CMake with the correct paths

Example (Windows PowerShell):
```powershell
$env:PICO_TOOLCHAIN_PATH = "$env:USERPROFILE\.picokit\toolchains\arm-gcc-13.2.Rel1-windows-x64"
$env:PICO_SDK_PATH = "$env:USERPROFILE\.picokit\toolchains\pico-sdk-2.0.0"
python -m picokit build
```

Example (Linux/macOS):
```bash
export PICO_TOOLCHAIN_PATH="$HOME/.picokit/toolchains/arm-gcc-13.2.Rel1-linux-x64"
export PICO_SDK_PATH="$HOME/.picokit/toolchains/pico-sdk-2.0.0"
picokit build
```

This is useful when:
- Using a different version of the toolchain or SDK
- Testing with a development version of the Pico SDK
- Sharing a toolchain across multiple projects
- Using system-installed toolchains

## Project Format

`picokit new blink` creates a Pico project:

```text
blink/
  picokit.toml
  CMakeLists.txt
  pico_sdk_import.cmake
  main.c
  .gitignore
```

Use `--board pico_w` to create a Pico W project:

```bash
picokit new my-project --board pico_w
```

Default `picokit.toml`:

```toml
[pico]
board = "pico"

[build]
name = "blink"
build_dir = "build"
sources = ["main.c"]
```

## Build Flow

`picokit build` uses CMake to compile your Pico project:

1. Configures CMake with Pico SDK path
2. Builds the project with ARM GCC toolchain
3. Generates `.uf2` file for flashing

Example:

```bash
cd blink
picokit build
```

Output will be in `build/blink.uf2`.

To remove all generated build files and start from a clean configuration:

```bash
picokit clean
```

The command only removes the `build_dir` configured in `picokit.toml` and refuses
to delete the project root or a directory outside the project.

## Flashing

`picokit flash` programs the ELF firmware over SWD using pyOCD:

1. Connect a CMSIS-DAP compatible debug probe to the Pico SWD pins
2. Connect the probe over USB
3. Run `picokit flash`

The command selects `rp2040` for Pico/Pico W and `rp2350` for Pico 2, then
programs `build/<project>.elf`. Use `--probe <ID>` when multiple probes are connected.

```bash
picokit flash
```

To list the debug probes detected by pyOCD:

```bash
picokit flash --detect
```

## Supported Boards

- `pico` - Raspberry Pi Pico (RP2040)
- `pico_w` - Raspberry Pi Pico W (RP2040 with WiFi)
- `pico2` - Raspberry Pi Pico 2 (RP2350)
- `pulsar_rp` - UNIT Pulsar RP (RP2350; uses the Pico 2 SDK definition)
- `dualmcu_rp` - UNIT DualMCU RP (RP2040; uses the Pico SDK definition)

For example:

```bash
picokit new pulsar-project --board pulsar_rp
picokit new dualmcu-project --board dualmcu_rp
```

## Example Project

Default blink project (`main.c`):

```c
#include <stdio.h>
#include "pico/stdlib.h"

int main() {
    stdio_init_all();
    
    const uint LED_PIN = 25;
    gpio_init(LED_PIN);
    gpio_set_dir(LED_PIN, GPIO_OUT);

    while (true) {
        gpio_put(LED_PIN, 1);
        sleep_ms(500);
        gpio_put(LED_PIN, 0);
        sleep_ms(500);
    }
}
```

For Pico W, the LED control uses the CYW43 wireless chip:

```c
#include <stdio.h>
#include "pico/stdlib.h"
#include "pico/cyw43_arch.h"

int main() {
    stdio_init_all();
    
    if (cyw43_arch_init()) {
        printf("Wi-Fi init failed\n");
        return -1;
    }

    while (true) {
        cyw43_arch_gpio_put(CYW43_WL_GPIO_LED_PIN, 1);
        sleep_ms(500);
        cyw43_arch_gpio_put(CYW43_WL_GPIO_LED_PIN, 0);
        sleep_ms(500);
    }
}
```

## Development Workflow

1. Install toolchains:
   ```bash
   picokit install
   ```

2. Create a project:
   ```bash
   picokit new my-project
   cd my-project
   ```

3. Edit `main.c` with your code

4. Build:
   ```bash
   picokit build
   ```

5. Clean generated build files when needed:
   ```bash
   picokit clean
   ```

6. Flash to Pico over SWD:
   ```bash
   picokit flash
   ```

7. Your code runs immediately after flashing!

## Requirements

- Python 3.9+
- CMake 3.20 or newer (install separately)
- Ninja on Windows (installed by `picokit install`)
- picotool on Windows (installed by `picokit install`)
- Git (optional, for submodule initialization)

See the [CMake installation guide](docs/install-cmake.md) for detailed Windows,
Ubuntu/Debian, and macOS instructions, including `PATH` troubleshooting.

On Ubuntu/Debian:
```bash
sudo apt install cmake git
```

On macOS:
```bash
brew install cmake git
```

On Windows:
```powershell
winget install --exact --id Kitware.CMake --source winget
```

Alternatively, download the installer from https://cmake.org/download/ and make
sure its option to add CMake to `PATH` is selected.

If pip warns that `picokit.exe` was installed in a directory that is not on
`PATH`, the module form remains available without changing `PATH`:

```powershell
python -m picokit doctor
python -m picokit install
```

To use the shorter `picokit` command, print the Scripts directory with the
following command and add that directory to your user `PATH`:

```powershell
python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
```

## Support

For documentation, bug reports, and feature requests, visit the
[obviousfancy/picosdk](https://github.com/obviousfancy/picosdk)
repository. Report problems through
[GitHub Issues](https://github.com/obviousfancy/picosdk/issues).

`picokit` is a fork of [`picodev`](https://pypi.org/project/picodev/), published
independently under a new name. See `LICENSE` and `CHANGELOG.md` for attribution.

## License

MIT
