Metadata-Version: 2.4
Name: jig-dsl
Version: 0.1.0a1
Summary: A test language and harness for firmware running on the Renode emulator
Author: Graham Power
License-Expression: MIT
Project-URL: Homepage, https://github.com/GNPower/Jig
Project-URL: Documentation, https://jig-dsl.readthedocs.io
Project-URL: Repository, https://github.com/GNPower/Jig
Project-URL: Issues, https://github.com/GNPower/Jig/issues
Project-URL: Changelog, https://github.com/GNPower/Jig/blob/main/CHANGELOG.md
Keywords: renode,emulation,firmware,testing,embedded,zynq,stm32,csp
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: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Emulators
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textX<5,>=4
Requires-Dist: PyYAML<7,>=6
Requires-Dist: platformdirs<5,>=4
Requires-Dist: packaging>=23
Provides-Extra: test
Requires-Dist: pytest<10,>=8; extra == "test"
Requires-Dist: pytest-cov<8,>=6; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx<10,>=8.2; extra == "docs"
Requires-Dist: sphinx-rtd-theme<4,>=3.0; extra == "docs"
Requires-Dist: myst-parser<6,>=4.0; extra == "docs"
Provides-Extra: lint
Requires-Dist: ruff==0.17.0; extra == "lint"
Requires-Dist: pymarkdownlnt==0.9.40; extra == "lint"
Requires-Dist: zizmor==1.30.1; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: jig-dsl[test]; extra == "typecheck"
Requires-Dist: mypy==2.4.0; extra == "typecheck"
Requires-Dist: types-PyYAML==6.0.12.20260906; extra == "typecheck"
Requires-Dist: nox==2026.8.17; extra == "typecheck"
Provides-Extra: release
Requires-Dist: build==1.6.1; extra == "release"
Requires-Dist: twine==7.0.0; extra == "release"
Requires-Dist: bump-my-version==1.5.1; extra == "release"
Provides-Extra: audit
Requires-Dist: pip-audit==2.10.1; extra == "audit"
Provides-Extra: dev
Requires-Dist: jig-dsl[lint,release,test,typecheck]; extra == "dev"
Dynamic: license-file

# Jig

[![PyPI version](https://img.shields.io/pypi/v/jig-dsl.svg)](https://pypi.org/project/jig-dsl/)
[![Python versions](https://img.shields.io/pypi/pyversions/jig-dsl.svg)](https://pypi.org/project/jig-dsl/)
[![Tests](https://github.com/GNPower/Jig/actions/workflows/ci.yml/badge.svg)](https://github.com/GNPower/Jig/actions/workflows/ci.yml)
[![Coverage](https://codecov.io/gh/GNPower/Jig/branch/main/graph/badge.svg)](https://codecov.io/gh/GNPower/Jig)
[![Documentation](https://readthedocs.org/projects/jig-dsl/badge/?version=latest)](https://jig-dsl.readthedocs.io/en/latest/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/GNPower/Jig/blob/main/LICENSE)

**A test language and harness for firmware running on the Renode
emulator.**

Full documentation: <https://jig-dsl.readthedocs.io>

## Overview

Jig runs test plans, written as `.jig` files, against a users firmware
on [Renode](https://renode.io). A plan declares the boards it needs, the
buse interfaces between them and the communication protocols the harness uses, then
drives the system over those interfaces in simulated time:

```jig
import "zed.jig"

system "two ZedBoards and a host computer" {
    board a: "zed-a"
    board b: "zed-b"
    bus can0: can(bitrate: 1 Mbit/s, members: [a.can, b.can])
    node host: csp(address: 10, link: a.kiss)
}

setup {
    parallel {
        task zed_a { booted(a, 1) }
        task zed_b { booted(b, 2) }
    }
}

test "the host computer reaches zed-b through zed-a" {
    check host.ping(b) < 50 ms
    check can0.traffic().routes["10->2:1"] >= 1
}
```

This is the start of `examples/zedboard/plans/multiboard.jig`. The setup
waits, on both boards at once, for the boot banner and the first prompt
(`booted` comes from the example's plan library, `lib/zed.jig`). The test
then pings zed-b from the host computer through zed-a using the lightweight
network protocol [LibCSP](https://github.com/libcsp/libcsp).

Every check's result is printed in a report with the simulated time it ran
at. Each run gets a fingerprint, a SHA-256 digest of everything it decided
and measured in simulated time, so `jig run --repeat 3` proves a plan gives
the same result three times, on any host.

Boards are data: a `board.yaml` names the platform (in this case the
[ZedBoard][zedboard], running a Zynq-7020 SoC), the Renode platform
description, the firmware and the interfaces plans use. Users must bring
their own C# models and Python plugins for any peripherals not directly
supported by Jig.

[zedboard]: https://www.avnet.com/americas/products/avnet-boards/avnet-board-families/zedboard/

## Requirements

- Python 3.11 or later.
- Renode 1.17.0. Jig finds an installed copy, or `jig renode install`
  downloads the release from Renode's GitHub page after you agree, and
  checks its size and SHA-256 digest.
- For the ZedBoard example's firmware, `arm-none-eabi-gcc`.
- For RTL co-simulation, Linux with Verilator.

## Installation

```bash
python -m pip install jig-dsl
jig renode install
jig doctor
```

## Quick Start

The repository's ZedBoard example runs two Zynq-7020 boards on one CAN
bus, with a host computer on a serial link to the first:

```bash
git clone https://github.com/GNPower/Jig.git
cd Jig
python examples/zedboard/firmware/build.py
jig run examples/zedboard/plans/multiboard.jig --html out/report.html
```

`build.py` needs `arm-none-eabi-gcc` on the `PATH`. The tutorials in the
documentation build plans like this one step by step.

## Features

- **A plan language for firmware tests**: consoles, network requests, checks,
  waits, loops, parallel tasks, timelines and recorded values, all in
  simulated time.
- **Several boards in one emulation**, on bus interfaces the harness carries
  and watches, with repeatable timing between them.
- **Zynq-7000 and STM32 drivers**: JTAG-style and Quad-SPI boots through
  Jig's Zynq-7000 models, and ELF boots on Renode's STM32 platforms.
- **CSP in libcsp 1.6's wire format**: KISS and CAN links, RDP
  connections, and a bus observer that reassembles every packet.
- **Board plugins** through `jig.plugin`, a versioned API for plan
  functions, board members, decoders and device drivers.
- **C# models compiled by Renode at start-up**, with interfaces that board
  chip models implement so plans can drive them.
- **Reports for people and CI**: an HTML page with plots, JUnit XML, a JSON
  summary, run directories with every console transcript and packet, and
  exit codes that differentiate failed tests from broken setups.
- **RTL co-simulation** of programmable-logic blocks with Verilator.
- **A localhost bridge to Renode** with a token per run, in place of
  Renode's network-facing Robot Framework server.

## License

MIT: see [LICENSE](https://github.com/GNPower/Jig/blob/main/LICENSE).
