Portrayal 0.2.0

Portrayal is network hardware as data. Each device is a declarative YAML manifest that places reusable component contracts, and the compiler turns it into one SVG in real millimetres with every port, supply, lamp and bay addressable.

0.2.0 adds power, rack furniture and the rules for laying cable in a rack.

What's in it

• 256 devices from 22 vendors, 86 more than 0.1.0, none removed. New vendors: Amphenol Network Solutions (11 breaker panels), AurCore (10 DIN-rail switches), Eaton (4 rack PDUs), Supermicro (4 servers), Fibrain (1 patch panel) and HPE (1 server). FS.com gains 47: cable managers, vertical ducts, blanking panels, fan trays, shelves and DIN rail brackets.
• 1,485 component majors, 524 of them new.
• 105 NOS listings, up from 29: 42 OcNOS (IP Infusion), 13 DNOS (DriveNets) and 21 SONiC join the 29 ArcOS listings.
• Connectors and plugs. AC inlets and outlets, USB, D-sub, DC barrel, terminal blocks and headers, ground studs with ring and two-hole lugs, MRJ21, VHDCI and RJ11 are connector slots, and a cable plug seats in each.
• More optics. CFP, CFP2, CFP4, CXP, OSFP and XFP cages offer generic optics. MPO, BiDi and SC PON generics are new.
• Rack PDUs and power panels. Outlets, breakers, lines and the input rating are data. The DCIM exports write power outlets, and a PDU's class is derived from what it meters and switches.
• Rack furniture. chassis.mount says how a part is installed: rack, rack-face, rack-side, din-rail, wall or desktop. Sheet bodies, bevels, overhang, ear positions and rail kits (kind: kit) are new.
• Cable lay in the kit. The rack command core, bundles, trays, rings, solid bodies, cable types and bend radii. A routed length follows the path a cable would take. The kit in the tree is 0.18.0.
• New build files. rack.json, kits.json, cable-types.json, lint-rules.json, and an elements.json beside every compiled face.
• Diagram exports in the kit: draw.io and OmniGraffle, with cables.
• 173 lint rules, 48 of them new (L125 to L172), and a suite of more than 8,600 tests.

What broke

format is still 1 and the published build is still contract: 2. The 0.2.0 section of CHANGELOG.md lists every change. An entry that needs action is marked BREAKING or ONE-WAY.

• Removed component majors. 66 majors that 0.1.0 shipped are gone. Each is under Removed with the ref that replaces it. Most are Juniper MX cards: the 22 horizontal cards moved to a new major, and the MX960 vertical twins were replaced by the horizontal card turned 90 degrees.
• Device majors. 34 of the 170 devices in 0.1.0 took at least one major: a placement id changed, or a slot moved. The causes are ground points that became stud pairs, re-measured MX card slots and re-measured port strips.
• DCIM renames. Telco Systems is exported as BATM/Telco Systems. The Edgecore DCS510 AC types are renamed. A box that is not racked exports u_height: 0, and the Dell R740xd exports 2U. USB storage and service jacks on 26 cards no longer export as consoles. Several Juniper module types and MIC ports are renamed. Nautobot module types carry their own bays, and ports under them take the parent bay in their names. NetBox nested module bays need NetBox 4.5.7 or later.
• Schemas. The device schema types ten keys under attrs.power and attrs.management that took any scalar at 0.1.0. A manifest outside the library that used one of these names with another spelling of the value is refused. No key was removed from any schema, and every manifest of the 0.1.0 library validates under both versions.
• Lint. A manifest outside the library that passed at 0.1.0 can fail one of the 48 new rules.
• Saved-rack lengths. The rack file is version 3, and routed lengths changed with each step of the cable lay. The rack modules are new in this release, so this concerns a page built from main, not a consumer of 0.1.0.

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

The NetBox and Nautobot types are already built under library/exports/.

Known limits

• @portrayal/kit on npm is still 0.2.0. It is published separately from this release and has none of the rack modules. Use the kit from a clone to get 0.18.0.
• The compiled library is going to npm one package per device, a batch a day. @portrayal/index is not on npm yet, so nothing loads the library from a CDN.
• Three devices are marked draft: dell/r660, dell/r740xd and celestica/ds6001.
• No rail kit (kind: kit) is in the library yet. The format and the lint rules for one are in place.
• The Python package is not on PyPI. Install from a clone.

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).

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.