Skip to content

Decks and profiles

The desktop app is a manager and a window. Underneath, each deck is the same Python edge server you could start from a terminal; the app starts it, watches it, captures its output, and shows its page in a tab. The sidebar lists your decks: click a running one to open its page, a stopped one to reach its launcher page, and the gear on any row for its instruments, log and settings. Drag rows to reorder them; Ctrl+B hides the sidebar from anywhere.

Deck profilePython script profile
What startspython -m ivoryos_edge --deck deck.json …python your_script.py …
Instruments come froma deck file (data), edited in the app’s Instruments tabyour script’s own code
Change a COM portInstruments → Edit → change portan environment variable (below), or edit the script in the Code tab
One broken instrumentthe others still load; the broken one is listed with its errorthe script stops, unless it handles the error itself
Add a driver from the Hubyesno; install it and edit the script
Runs and workflowsits own data folderthe script’s own data folder, if one is set

Several profiles run at the same time, each on its own port.

Start checks the Python environment (the first time it downloads Python and installs the edge), checks the port is free, starts the process and waits until it answers /api/status. The deck then opens in a tab on its own, unless you have moved on to something else meanwhile; a deck whose instruments did not all load opens on its Instruments tab instead, with the failures in red.

Open shows the page in a tab; the arrow beside it opens the same page in your normal browser. Closing a tab does not stop the deck. Other computers on your network can open it too, at http://<this computer's address>:<port>: a profile’s Reachable from other computers setting is on unless you turn it off. Anyone who can reach the port can drive the instruments, so turn it off for a deck only this computer should open.

Stop asks the process to shut down and forces it after a few seconds. Restart is always a new process (Python cannot reliably let go of a serial port otherwise): it re-reads the deck file, re-imports the drivers and reconnects every instrument. Restart on the deck’s Instruments page does the same through the deck itself, and is refused while a run is going unless you confirm.

A script profile needs its Python file and nothing else. The rest is under Advanced in its Configuration tab, and can stay empty:

  • Python interpreter. Empty, the script runs in the app’s own Python, which has IvoryOS and every driver installed from the Hub. A script from a project of your own usually needs that project’s packages: choose the project’s interpreter (its .venv/bin/python, or .venv\Scripts\python.exe on Windows). The line under the field says whether IvoryOS is installed there, and offers to install it when it is not.
  • Working folder. Where the script runs, its own folder by default. Imports are found in the script’s folder, the working folder, and the project above the script (the folders holding pyproject.toml, setup.py, requirements.txt, .git or .idea, and their src/), as PyCharm does.
  • Environment variables. For changing something, usually a port, without editing the script:
import os
pump_1 = SyringePump(port=os.environ.get("PUMP_PORT", "COM3")) # COM3 unless set

Add PUMP_PORT = COM4 and restart. The same script can have two profiles, Bench A with COM3 and Bench B with COM4. A PYTHONPATH variable adds a folder to the imports. The app also sets IVORYOS_PORT, IVORYOS_HOST and IVORYOS_DATA_DIR for the script, which ivoryos_edge.run(__name__) reads; that is how a script lands on its profile’s port without being changed.

A script written for IvoryOS Classic (import ivoryos) is offered a conversion when started; the changed lines are kept above as comments so going back is uncommenting.

Everything the process prints: driver output, the deck’s own messages (which instrument loaded, which optimizer failed to import and why), Python tracebacks. Log file opens the file that holds every session’s output. When a deck would not start or stopped unexpectedly, Send to IvoryOS on its banner packages this log for the team; see When something goes wrong.

Path (macOS: ~/Library/Application Support/IvoryOS/; Windows: %APPDATA%\IvoryOS; Linux: ~/.config/IvoryOS)What
profiles.jsonyour profiles and the app’s settings
profiles/<id>/deck.jsona deck profile’s instruments (Settings → Show deck file)
profiles/<id>/data/that deck’s runs, workflows, safety config and Cloud pairing
runtime/venv/the Python environment all decks share, managed by uv
logs/<id>.logeach profile’s output

Deleting runtime/ is safe; it is rebuilt on the next start. Deleting profiles/<id>/data/ deletes that deck’s run history.

The app’s Settings, under Python, shows the interpreter the app’s decks run in, with Copy path. Point your editor at it and it has the same packages (IvoryOS and every driver installed from the Hub): in PyCharm, Settings → Python Interpreter → Add → Existing; in VS Code, “Python: Select Interpreter” → Enter path. The other way round, a script profile can run in your project’s own interpreter (above).