Repository navigation
0.3.0
Reference. What this release does, what it does not, and what is simulated.
Released: 2026-10-13. Previous: 0.2.0, on PyPI 2026-09-17.
What 0.3.0 is
A hundred and seventeen pull requests,
#38 to
#163.
The reason to install it rather than read about it is the first paragraph.
A plant on your machine, in two commands
pipx install factorysemantics-mes
fsmes demo bottlingThose two lines, on Linux, macOS or Windows, bring up the six-station ACME
bottling line: an eight-hour shift replayed over a real OPC UA server, a
simulated floor booking lots and naming its stops, and the operator screens
reading it. It prints where the plant is — http://127.0.0.1:8010/dashboard —
and an account to sign in with. fsmes demo bottling stop puts it down;
fsmes demo machining is a second plant on 8020.
0.2.0 could not do this. The plant packs were in the repository and not in the
wheel, so fsmes demo bottling from a PyPI install had no plant to run. They
are in the package now, byte for byte the ones the lab runs, and the wheel grew
3 % for it. First start copies the pack out of the package and generates the
shift from its seed — about 8 seconds on Linux, about 21 on Windows on
GitHub's runners — and after that it starts straight away. Everything it writes
goes to one per-user directory (%LOCALAPPDATA%\fsmes on Windows,
~/.local/share/fsmes on Linux, ~/Library/Application Support/fsmes on
macOS, or wherever FSMES_HOME says); nothing under the installed package is
written to.
A CI job does exactly this on Ubuntu and on Windows on every pull request —
installs the built wheel into an empty directory, starts the plant, signs in,
checks the specifications are there, the OPC port answers, the floor is
watching and a lot has been counted, then stops it and checks both ports came
back. It is the first job in this project's history that starts a plant on
Windows, and it found three faults nothing else could: the Windows console's
code page mangling what the CLI printed, in two places.
You need Python 3.12 or newer on the machine. On a locked-down plant PC
that is the real obstacle, and nothing in this release removes it.
Quality you can click
The SPC tab draws the charts the plant's own specifications ask for: an
individuals-and-moving-range chart where a characteristic is measured one piece
at a time, an X̄/R chart where it is measured n at a time, and a p chart
where an inspector counts a lot rather than measuring it. Western Electric
rules 1 to 5 are drawn and recorded — one row per firing, with the window it
judged — and which of them raise a hold is the plant's choice: rules 1 to 4 do
by default and the moving-range rule does not, because a plant that has run a
year without a moving-range chart should not wake up to a queue of holds about
readings it already lived through. A p chart draws rule 1.
Click a point and a panel opens beside the chart with the reading, the rules
that fired on it, the gauge that took it, the machine's state and tags at that
moment, and the rest of the line. Three more things on the floor screens became
clickable in this release, each opening the records behind what you clicked
rather than a new screen:
- a point on a trend graph — the tag's reading, the machine, and what else
was happening; - a block on a machine's state timeline — what the stop was, how long, why
and who said so, the job that was on either side of it, and whether a
maintenance order covers it (planned work is not a breakdown); - a lot on a p chart — how many pieces were looked at and how many were
sent back, by defect.
A non-conformance is now worked rather than merely closed: open → under
review → dispositioned → closed, where the disposition is use_as_is,
rework, scrap or return and requires a reason. "Closed" never said what
happened to the material, which is the question a non-conformance exists to
answer.
Maintenance that reaches the right person
A maintenance order says which trade it needs, how much it matters, whether the
machine has to be stopped and when the job may be done. A dispatcher reads the
plant's own rules, the crew's skills and the roster, and gives the work to
somebody who can do it; a supervisor's screen shows what is assigned, what is
waiting and why. An SPC signal can raise a maintenance order, and a stop
covered by one reads as planned work on the timeline rather than as a
breakdown.
A chat on the AI tab that explains the chart
Ask the AI tab why a point is out of control and it answers from the plant's
own records, drawing the chart it is talking about. It needs
ANTHROPIC_API_KEY — without one the tab says so and the chat is off; the
rest of the product is unaffected. It costs about $0.12 a question at
current prices, and the plant keeps a row per turn, with the tool calls, the
cost and the outcome, so what the AI did is a record like anything else.
The separate floor assistant — the one that walks an operator through a
screen — runs on a local model through Ollama. Without Ollama on the machine,
that assistant is off and says so. Neither is required to run a plant.
Every floor row knows its shift
A production booking, a state interval, a check and a non-conformance now each
say which shift they fell in, and /analysis/* can be asked for a shift
instead of a number of hours — so how did my shift go is answerable. Three
rules decide which shift a minute belongs to, and an instant no pattern covers
is not attributed rather than filed under the nearest shift.
The lab plays a whole shift, with a chain in it
The simulated bottling line replays an eight-hour shift rather than an hour,
and the shift has a four-link chain of cause in it that the product has to be
able to follow, from production through maintenance and a tag to quality: a
changeover on the filler, a chiller maintenance order raised and never started,
the chiller's outlet temperature climbing all afternoon with the product
reaching the filler walking 8.4 → 6.4 °C behind it, and — half an hour later —
fill-height samples a millimetre and a half low with low_fill going from the
second rarest defect to the commonest in the lots counted in that window. No
limit on the filler is broken at any point: 6.4 °C is an ordinary number for a
cold drink. It is scripted on purpose — that is what makes it a test — and the
MES is not told the answer.
The full record is
CHANGELOG 0.3.0.
What 0.3.0 does not do
- It has not run a real plant. Not one, still. Every number in this
repository comes from a simulated line and says so where it appears. - No plant PC in a real plant has run it. Windows is proven on GitHub's
runner, which has no antivirus, no domain policy, no proxy and no firewall
prompt. A real plant PC may add all four, and the first one to do so will
find something. - The chat needs a key, and it is not free. No
ANTHROPIC_API_KEY, no
chat on the AI tab. No Ollama, no floor assistant. About $0.12 a question is
measured on this project's own usage, not promised. - The AI answers from the records, and the records are simulated. It has
never been asked a question about a real plant's data. - No SAP, Odoo, Oracle or NetSuite connector exists, and ERPNext Job Card
confirmations are still not built. Order-level round trip against a real
ERPNext v15.120.0 in CI is what exists. - No MQTT broker has been on the other end of either direction, so
Node-RED, United Manufacturing Hub and Grafana are untested for the same
reason. - PLC write-back is still a guarded recommendation queue, not a control
loop, and that is deliberate. - The upgrade gate proves one plant's shape, on SQLite. Nobody has
upgraded a populated PostgreSQL plant. Take the backup. See
upgrading.
What is simulated
Everything that produces a number. The plant behind every screenshot, scored
run and CI check is a deterministic line simulator in src/fsmes/sim/,
replayed over a real OPC UA server. The bottling plant's eight-hour shift, its
fill-height samples, its chiller and its chain of cause are all scripted, and
the script's answer key is in labs/multiplant/bottling/. The
largest plant is an 83-station cutlery works that serialises every piece, and
it is the public demo.
Every chart in the product states its coverage, its totals and, where it is
drawing simulated data, that it is simulated. A KPI that cannot be computed
honestly comes back unknown with the reason attached — including, new in this
release, performance and OEE on a machine whose counted work will not fit
inside its run time, which used to print a figure above 100 %.
The ERPNext in CI is real software in a container, not a simulation, but it is a
clean instance seeded by the job — not anybody's books.
Compatibility is the claims table: every row
carries the date it was last checked and what was run on that date, and rows
nothing has ever run against say never.
Upgrading from 0.2.0
fsmes backup --out /mnt/nas/fsmes
# stop the agent and the API
pip install --upgrade factorysemantics-mes
fsmes db-status --pack packs/yourplant
fsmes init-db --pack packs/yourplant
fsmes db-status --pack packs/yourplant
# start them againFifteen migrations, c8b1e40d7a92 to d4e8a1c93b70: twelve new tables and a
set of nullable columns. Two of them write to rows that already exist — the
shift backfill, and a 30-day warning window on every gauge — and both are
described, with what they assume, in
upgrading between versions. That page also
lists the changes that alter what something already deployed will see: an OEE
figure that used to read above 100 % is now null with a sentence, an order no
longer finishes itself, closing a non-conformance takes a disposition first,
and the fleet console's default port moved to 8090.
Thanks
Every one of the hundred and seventeen pull requests in this release was
opened by the maintainer. There are still no outside contributors to thank — the repository
went public on 2026-09-08 and this is its third release. If you are reading
this and you run a plant,
Discussions
is the front door.
Every change in this release: CHANGELOG.