Skip to content

Start a deck

A deck is one edge server process with a set of instrument objects. There are three ways to make one; they all run the same server.

Create the instruments as module-level objects and hand the module to run():

my_bench.py
import os
import ivoryos_edge
from my_lab import SyringePump, Reactor
pump_1 = SyringePump(port=os.environ.get("PUMP_PORT", "COM3"))
reactor = Reactor(port="COM4")
ivoryos_edge.run(__name__)
Terminal window
python my_bench.py # http://localhost:8080

Every module-level object becomes an instrument, by the rules in What IvoryOS reads. Objects that are yours but not instruments go in exclude_names:

ivoryos_edge.run(__name__, port=8090, exclude_names=["CONFIG"], logger="my_lab")

logger names one or more loggers whose records go to the deck’s output (the Log tab in the desktop app). plugins takes a list of Python plugins.

A script written for IvoryOS Classic (import ivoryos) stops at that import. The desktop app offers to convert it, or run python -m ivoryos_edge.classic script.py --write: it changes the import and the run() arguments, keeps every changed line above as a comment, and names anything it could not carry over.

VariableDefaultWhat it does
IVORYOS_PORT8080the port, when the script does not pass one to run()
IVORYOS_HOST0.0.0.0the interface to listen on
IVORYOS_DATA_DIRthe legacy locationswhere the database, saved workflows, safety config, Cloud pairing and the schema dump are kept. The desktop app always sets it, one folder per deck.
IVORYOS_ALLOWED_HOSTSthis computer’s namesextra host names the page may be opened by (a lab hostname, a reverse proxy); * disables the check
IVORYOS_SUPERVISEDunsetset by the desktop app; a restart then exits with code 75 for the app to start it again
IVORYOS_CLOUD_URLthe hosted Clouda lab’s own Cloud to pair with

--data-dir, --port and --host on the command line set the first three.

FileWhat
ivoryos_edge.dbevery run, step and result (SQLite)
workflows/saved workflows: <name>.json is the current version, .versions/<name>/<n>.json every save, .meta.json the tags
safety.json, safety_state.jsonthe safety guard and what it last knew of each deck state
.env, .certs/the Cloud pairing
ivoryos_schema.jsonthe schema read at startup
optimizer_data/files an optimizer backend keeps on disk

A restart is always a new process: Python cannot reliably let go of a serial port otherwise. The Instruments page’s Restart (POST /api/system/restart) is refused while a run is going unless you confirm. Under the desktop app the process exits with code 75 and the app starts it again; from a terminal it replaces itself with the same command line (on Windows, ivoryos-edge --deck runs a small restart loop to make this work; a script cannot, and says so).