Portrayal 0.1.0

Portrayal is network hardware as data. Each device is a declarative YAML manifest, versioned in Git, that places reusable component contracts. The compiler turns it into one SVG in real millimetres, where every port, PSU, fan, LED, bay and label is an addressable element with a stable id. Then drive it: colour a port from telemetry, highlight a failed supply, route a cable, open it in 3D, or export the device to NetBox or Nautobot.

This is the first public release.

What's in it

• 170 devices from 16 vendors, drawn front and rear from vendor datasheets, guides and photographs, with every figure's source recorded: UfiSpace 44, Edgecore 39, Juniper 15, BATM (Telco Systems) 14, Celestica 13, Cisco 11, Nokia 10, FS.com 7, Smartoptics 5, Oscilloquartz 4, and more.
• 1,027 component contracts: cages, jacks, PSUs, fans, line cards, optics and cables that devices compose, each versioned on its own.
• NetBox and Nautobot device and module types for every device and module (library/exports/): one device type per manufacturer that sells a box.
• NOS listings: a NOS vendor lists the hardware it supports, with its own port names and part numbers. 29 ArcOS listings from the Arrcus HCL ship in this release.
• The explorer and 3D viewer (kit/): browse the library, inspect any part, swap modules and optics into bays and cages, and view any device extruded in 3D with its cables routed.
• @portrayal/kit, the JavaScript consumer: draw, inspect, swap and export from the compiled artifacts, with no YAML reading.
• 125 lint rules and a suite of more than 5,000 tests: geometry, provenance, power, airflow, naming and the DCIM exports, so a new device is checked the same way as the existing ones.

Getting started

git clone https://github.com/roc-ops/Portrayal.git && cd Portrayal
python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[test]"
./build.sh                      # lint, then compile every device into library/dist/
python3 tools/serve.py 8931     # then open http://localhost:8931/kit/index.html

For DCIM, the NetBox and Nautobot types are already built under library/exports/, and nothing needs compiling. For JavaScript, use npm install @portrayal/kit. To add a device, see CONTRIBUTING.md and docs/modelling-a-device.md.

What 0.1.0 promises

Read docs/format-stability.md for the full text. The short version:

• Format 1. Every manifest, contract and listing declares format: 1. The schemas are published at https://portrayal.dev/schemas/v1/.
• The published build is contract: 2. The contract number goes up when a field a consumer reads is removed, renamed or changes meaning. Adding a field does not raise it.
• At 0.x, the format may still change. Every change to the format or contract is announced in CHANGELOG.md, with a minor version bump.
• Component majors. A superseded component major (name@1 when @2 exists) may be removed at 0.x, and every removal is listed in the changelog with the ref that replaces it. From 1.0, a retired major is deprecated for at least one release first.
• Lint codes are never renumbered or reused, so a device that waives a rule by code keeps meaning the same rule.
• DCIM exports announce any change that would affect data already imported.

Known limits

• Two devices are still marked draft: dell/r740xd and celestica/ds6001. Servers are supported but not the current focus.
• The library ships no populated configurations. Optics and cables are offered by the explorer, and a downstream tool fills bays.
• The Python package is not on PyPI yet; install from a clone. Built artifacts as release downloads are planned (#64).

Thanks

Portrayal is sponsored by RocNet Supply. Vendor and product names belong to their owners, and Portrayal is not affiliated with any vendor it models; see NOTICE.

Apache-2.0. Contributions are welcome under the Developer Certificate of Origin (git commit -s). The full pre-release history is in CHANGELOG.md.