# Emulator for the PIO Blocks within the RP2040 Microcontroller (Python Edition)
  [](https://pypi.org/project/rp2040-pio-emulator/)
## Introduction
An emulator for the Programmable Input/Output (PIO) blocks that are present
within the Raspberry Pi Foundation's RP2040 Microcontroller. It is designed
to assist in the analysis of PIO programs and to help you by:
* Enabling unit tests to be written.
* Answering questions such as: How many clock cycles are being consumed?
* Supporting the visualization of GPIO outputs over time.
* Providing alternatives to debugging on real hardware, which can be time consuming.
## Quick Start
Below is a slight variation of the example used within the [Quick Start Guide](./docs/Quick%20Start%20Guide.md).
```python
from pioemu import emulate
program = [0xE029, 0x0041, 0x2080] # Count down from 9 using X register
generator = emulate(program, stop_when=lambda _, state: state.x_register < 0)
for before, after in generator:
print(f"X register: {before.x_register} -> {after.x_register}")
```
## Documentation
A [Tour of pioemu](./docs/Tour%20of%20pioemu.md) provides a more detailed explanation than the
[Quick Start Guide](./docs/Quick%20Start%20Guide.md) offers. In addition, there is a
[FAQ](./docs/FAQ.md) available that might contain an answer to your question. However, if none
of these provides you with the necessary information then please consider creating a
[new issue](https://github.com/NathanY3G/rp2040-pio-emulator/issues) - thanks!
## Additional Examples
Some additional examples are available within the [rp2040-pio-emulator-examples](https://github.com/NathanY3G/rp2040-pio-emulator-examples)
repository, including:
1. [TDD](https://en.wikipedia.org/wiki/Test-driven_development) example for the
[Pimoroni Blinkt!](https://shop.pimoroni.com/products/blinkt)
1. Tool to create Fast Signal Trace (FST) files suitable for analysis by
[GTKWave](https://gtkwave.sourceforge.net/)
1. Visualisation of square wave program using a
[Jupyter Notebook](https://jupyter-notebook.readthedocs.io/en/latest/)
## Supported Instructions
Instruction | Supported | Notes
:-----------| :---------------------------------| :----
JMP | :heavy_check_mark: |
WAIT | :heavy_check_mark: :warning: | IRQ variant is not supported
IN | :heavy_check_mark: |
OUT | :heavy_check_mark: :construction: | EXEC destination not implemented
PUSH | :heavy_check_mark: |
PULL | :heavy_check_mark: |
MOV | :heavy_check_mark: :construction: | Some variants and operations not implemented
IRQ | :heavy_multiplication_x: |
SET | :heavy_check_mark: |
## Known Limitations
This software is under development and currently has limitations - the notable ones are:
1. Not all of the available instructions are supported - please refer to the table above.
1. No support for pin-sets associated with `OUT`, `SET` or `IN`; all pin numbers are with respect to GPIO 0.
1. Pin-sets do not wrap after GPIO 31.
1. `PULL IFEMPTY` and `PUSH IFFULL` do not respect the pull and push thresholds.
1. No direct support for the concurrent running of multiple PIO programs;
a single State Machine is emulated and not an entire PIO block.
## Thanks To
* [aaronjamt](https://github.com/aaronjamt) for contributing features and fixes.
* [Josverl](https://github.com/Josverl) for contributing features.
* [winnylourson](https://github.com/winnylourson) for contributing a bug fix.
Raw data
{
"_id": null,
"home_page": "https://github.com/NathanY3G/rp2040-pio-emulator",
"name": "rp2040-pio-emulator",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.10.13",
"maintainer_email": null,
"keywords": "rp2040, rp2, raspberry-pi-pico, testing, tdd, debugging",
"author": "Nathan Young",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/55/4d/91ec32c4a0edb3244f9bf3025c5b57d5cbe5e6eb78317bfa8648b3b89064/rp2040_pio_emulator-0.84.0.tar.gz",
"platform": null,
"description": "# Emulator for the PIO Blocks within the RP2040 Microcontroller (Python Edition)\n\n  [](https://pypi.org/project/rp2040-pio-emulator/)\n\n## Introduction\nAn emulator for the Programmable Input/Output (PIO) blocks that are present\nwithin the Raspberry Pi Foundation's RP2040 Microcontroller. It is designed\nto assist in the analysis of PIO programs and to help you by:\n\n* Enabling unit tests to be written.\n* Answering questions such as: How many clock cycles are being consumed?\n* Supporting the visualization of GPIO outputs over time.\n* Providing alternatives to debugging on real hardware, which can be time consuming.\n\n## Quick Start\nBelow is a slight variation of the example used within the [Quick Start Guide](./docs/Quick%20Start%20Guide.md).\n\n```python\nfrom pioemu import emulate\n\nprogram = [0xE029, 0x0041, 0x2080] # Count down from 9 using X register\n\ngenerator = emulate(program, stop_when=lambda _, state: state.x_register < 0)\n\nfor before, after in generator:\n print(f\"X register: {before.x_register} -> {after.x_register}\")\n```\n\n## Documentation\nA [Tour of pioemu](./docs/Tour%20of%20pioemu.md) provides a more detailed explanation than the\n[Quick Start Guide](./docs/Quick%20Start%20Guide.md) offers. In addition, there is a\n[FAQ](./docs/FAQ.md) available that might contain an answer to your question. However, if none\nof these provides you with the necessary information then please consider creating a\n[new issue](https://github.com/NathanY3G/rp2040-pio-emulator/issues) - thanks!\n\n## Additional Examples\nSome additional examples are available within the [rp2040-pio-emulator-examples](https://github.com/NathanY3G/rp2040-pio-emulator-examples)\nrepository, including:\n\n1. [TDD](https://en.wikipedia.org/wiki/Test-driven_development) example for the\n [Pimoroni Blinkt!](https://shop.pimoroni.com/products/blinkt)\n\n1. Tool to create Fast Signal Trace (FST) files suitable for analysis by\n [GTKWave](https://gtkwave.sourceforge.net/)\n\n1. Visualisation of square wave program using a\n [Jupyter Notebook](https://jupyter-notebook.readthedocs.io/en/latest/)\n\n## Supported Instructions\n\nInstruction | Supported | Notes\n:-----------| :---------------------------------| :----\nJMP | :heavy_check_mark: | \nWAIT | :heavy_check_mark: :warning: | IRQ variant is not supported\nIN | :heavy_check_mark: |\nOUT | :heavy_check_mark: :construction: | EXEC destination not implemented\nPUSH | :heavy_check_mark: | \nPULL | :heavy_check_mark: | \nMOV | :heavy_check_mark: :construction: | Some variants and operations not implemented\nIRQ | :heavy_multiplication_x: |\nSET | :heavy_check_mark: |\n\n## Known Limitations\nThis software is under development and currently has limitations - the notable ones are:\n\n1. Not all of the available instructions are supported - please refer to the table above.\n\n1. No support for pin-sets associated with `OUT`, `SET` or `IN`; all pin numbers are with respect to GPIO 0.\n\n1. Pin-sets do not wrap after GPIO 31.\n\n1. `PULL IFEMPTY` and `PUSH IFFULL` do not respect the pull and push thresholds.\n\n1. No direct support for the concurrent running of multiple PIO programs;\n a single State Machine is emulated and not an entire PIO block.\n\n## Thanks To\n* [aaronjamt](https://github.com/aaronjamt) for contributing features and fixes.\n* [Josverl](https://github.com/Josverl) for contributing features.\n* [winnylourson](https://github.com/winnylourson) for contributing a bug fix.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "RP2040 emulator for the testing and debugging of PIO programs",
"version": "0.84.0",
"project_urls": {
"Homepage": "https://github.com/NathanY3G/rp2040-pio-emulator",
"Repository": "https://github.com/NathanY3G/rp2040-pio-emulator"
},
"split_keywords": [
"rp2040",
" rp2",
" raspberry-pi-pico",
" testing",
" tdd",
" debugging"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "220006c50713a0e6b1758e7a5b1ef61fd221b9f01156374dc0c86c1a75a61e12",
"md5": "77556155ad5c213b7afc530e747aed56",
"sha256": "074e9f4ccb04fcf59ebf98e7b6eb12238c3689e637b4045e5d4d0726522d136c"
},
"downloads": -1,
"filename": "rp2040_pio_emulator-0.84.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "77556155ad5c213b7afc530e747aed56",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.10.13",
"size": 20536,
"upload_time": "2025-02-02T13:09:34",
"upload_time_iso_8601": "2025-02-02T13:09:34.945026Z",
"url": "https://files.pythonhosted.org/packages/22/00/06c50713a0e6b1758e7a5b1ef61fd221b9f01156374dc0c86c1a75a61e12/rp2040_pio_emulator-0.84.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "554d91ec32c4a0edb3244f9bf3025c5b57d5cbe5e6eb78317bfa8648b3b89064",
"md5": "0f7762c337579d3394c482631dfdae13",
"sha256": "c5569862ab0d0832e0cb7b67ed66c5f61864a2100df2b3d8cbcb7ddce516dcd0"
},
"downloads": -1,
"filename": "rp2040_pio_emulator-0.84.0.tar.gz",
"has_sig": false,
"md5_digest": "0f7762c337579d3394c482631dfdae13",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.10.13",
"size": 15388,
"upload_time": "2025-02-02T13:09:36",
"upload_time_iso_8601": "2025-02-02T13:09:36.194690Z",
"url": "https://files.pythonhosted.org/packages/55/4d/91ec32c4a0edb3244f9bf3025c5b57d5cbe5e6eb78317bfa8648b3b89064/rp2040_pio_emulator-0.84.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-02 13:09:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NathanY3G",
"github_project": "rp2040-pio-emulator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rp2040-pio-emulator"
}
JSON
