From b905288f5751e6c1549539fc8849579d61920c52 Mon Sep 17 00:00:00 2001 From: scottkalw Date: Sat, 14 Nov 2026 19:35:02 -0600 Subject: [PATCH] Course class 0.2: what an MES is, and what it is not The scene for the second class of draft 2, filmed on a scratch cutlery plant on loopback at 10x: the whiteboard the MES replaces, the three layers (the office system above, the machines below, the MES between), the three things it is not, the four tiles, one stacking order followed from release to its machine and back up to the outbox and the audit trail, and the word Watched as the honest beat. course.toml gets 0.2's three outcomes and its scene, nothing else. The lesson-tree test that used 0.2 as its example of empty outcomes now reads the class's own three lines. Co-Authored-By: Claude Opus 5.5 Signed-off-by: scottkalw --- scripts/course/course.toml | 6 + .../01-02-what-an-mes-is-and-is-not.toml | 376 ++++++++++++++++++ ...he_course_tree_and_touches_nothing_else.py | 4 +- ...mes_between_the_office_and_the_machines.py | 189 +++++++++ 4 files changed, 574 insertions(+), 1 deletion(-) create mode 100644 scripts/scenes/course/01-02-what-an-mes-is-and-is-not.toml create mode 100644 tests/test_class_0_2_places_the_mes_between_the_office_and_the_machines.py diff --git a/scripts/course/course.toml b/scripts/course/course.toml index 4268e6ed..85e75ad7 100644 --- a/scripts/course/course.toml +++ b/scripts/course/course.toml @@ -71,6 +71,12 @@ slug = "what-an-mes-is-and-is-not" title = "What an MES is — and what it is not" one_line = "The layer between the office that says what to make and the machines that make it; it records what happened and says unknown when it did not see." knows_before = ["0.1"] +outcomes = [ + "Place the MES between the office system that says what to make and the machines that make it.", + "Say what it is not: not the ERP, not the historian, not a spreadsheet.", + "Read Watched: a figure that says how little it saw is honest, not broken.", +] +scene = "scripts/scenes/course/01-02-what-an-mes-is-and-is-not.toml" # ------------------------------------------------------------------ tier 1 [[module]] diff --git a/scripts/scenes/course/01-02-what-an-mes-is-and-is-not.toml b/scripts/scenes/course/01-02-what-an-mes-is-and-is-not.toml new file mode 100644 index 00000000..a5da8082 --- /dev/null +++ b/scripts/scenes/course/01-02-what-an-mes-is-and-is-not.toml @@ -0,0 +1,376 @@ +# Class 0.2 of the course, *What an MES is, and what it is not*: the layer +# between the office system that says what to make and the machines that make +# it. It records what actually happened, step by step, and says how much it +# did not see. +# +# Tier 0 is still before the software, so the class shows the MES's place +# rather than its features: where it sits, the three things it is not, the +# four tiles at the top of the floor, and one order followed from the office +# to a machine and back up as a confirmation. The last beat is the coverage +# word: under every figure the MES says how much of the window it watched, and +# a figure resting on a few percent is an honest figure, not a broken one. +# Filmed on a scratch cutlery plant, every screen as the product draws it. + +name = "what-an-mes-is-and-is-not" +title = "What an MES is, and what it is not" +lesson = "0.2" +take_is = "lesson" +part = "hook" +base = "http://127.0.0.1:8040" +badge = "pre-alpha · simulated plant · v{version}" +# Four to six minutes, as the outline says this class runs. +budget_seconds = 360 +gif_skip_seconds = 2.0 +width = 1280 +height = 720 + +notes = [ + "The plant was started a few minutes before the camera rolled, from the cutlery pack, at ten times wall clock, so one stacking order has run from release to completion by the time the lesson follows it. At 1x the same order takes the better part of two hours.", + "The camera waited, off camera, until stacking order WO-STACK07-0001 had completed and made its lot, so the order the class follows has been released, booked and confirmed before the first frame.", + "The order followed is the stacker's, not the mould's: a stacking order is 260 stacks and finishes in minutes at 10x, while a moulding order is 2,778 forks. The class is about the order's road through the systems, not about which product it makes.", + "No office system is connected to this plant. The order was released by the plant's own order book, not sent by an ERP, and the confirmation waits in the outbox with nobody to collect it; the ERP tile reads sending for that reason. The narration says so.", + "At any speed but 1x every 2D page carries the product's REPLAY 10× banner across its top. It is filmed as the product draws it.", + "The Watched figure under each machine is the share of the last eight hours the MES actually observed. On a plant a few minutes old it is a few percent, and the cutlery pack sets no coverage floor, so the OEE beside it is shown, not withheld. The class reads Watched, not the OEE; OEE is class 3.3.", + "The opening whiteboard is a plain card with words on it. There is no artwork of a person or a board.", +] + +honesty = [ + "no office system is connected to this plant: the order book releases its own orders, and the confirmation waits in the outbox with nobody to collect it, which is why the ERP tile says sending", + "the plant is a scratch plant a few minutes old, replaying at ten times wall clock, which is the banner across the top of the 2D pages and why Watched reads a few percent", +] + +[plant] +pack = "labs/cutlery" +speed = 10 +roll_when_timeout_seconds = 1800 + +# One stacking order finished and confirmed: the order the class follows has +# made the whole trip, office to machine and back up. +[[plant.roll_when_order]] +code = "WO-STACK07-0001" +completed = true + +# ----------------------------------------------------------------- the hook + +[[step]] +do = "slide" +name = "the-whiteboard" +title = "Line FORK1, day shift" +lines = [ + "Order: forks, 2,778", + "Good so far: about 1,900?", + "Scrap: ask the operator", + "Mould stopped 10:40 to 11:15, maybe", + "Written up at the end of the shift", +] +hold = 1.5 + +[[step]] +do = "say" +line = "Before software, a plant kept track like this: a whiteboard, a clipboard, a tally at the end of the shift." + +[[step]] +do = "say" +line = "Roughly right, written up late, and nobody can say where each number came from." + +[[step]] +do = "mark" +name = "whiteboard" + +[[step]] +do = "goto" +url = "/dashboard" +settle = 3 + +[[step]] +do = "wait_for" +selector = "#kpi-machines" +text = "/83" + +[[step]] +do = "say" +line = "This is what replaces it. The same plant, right now, counted as it happens." + +# ----------------------------------------------------------------- the idea + +[[step]] +part = "idea" +do = "slide" +name = "three-layers" +title = "Where the MES sits" +lines = [ + "The office system (ERP): what to make, how many, by when", + "The MES: what actually happened, step by step", + "The machines (PLC / SCADA): run the steps and report", +] +hold = 1.5 + +[[step]] +do = "say" +line = "A plant has three layers of systems, and the MES is the one in the middle." + +[[step]] +do = "say" +line = "Above it, the office system, called the ERP. It takes the customer's order and says what to make, how many, and by when." + +[[step]] +do = "say" +line = "Below it, the machines and their controllers, called PLC and SCADA. They run the steps and report what they did." + +[[step]] +do = "say" +line = "In the middle, the MES. It turns the office's order into work on the floor, and the floor's reports into what actually happened." + +[[step]] +do = "mark" +name = "three-layers" + +[[step]] +do = "slide" +name = "what-it-is-not" +title = "What an MES is not" +lines = [ + "Not the ERP: it does not take customer orders or send invoices", + "Not the historian: it does not just store every reading", + "Not a spreadsheet: nobody types the counts in afterwards", +] +hold = 1.5 + +[[step]] +do = "say" +line = "Three things it is not. It is not the ERP: it does not sell, buy or invoice." + +[[step]] +do = "say" +line = "It is not the historian, the store of every temperature and pressure. It keeps what those readings mean for an order." + +[[step]] +do = "say" +line = "And it is not a spreadsheet. Nobody types the counts in at the end of the shift; the machines and the people report them as they happen." + +[[step]] +do = "mark" +name = "what-it-is-not" + +# ------------------------------------------------------------ on the screen + +[[step]] +part = "screen" +do = "goto" +url = "/dashboard" +settle = 3 + +[[step]] +do = "wait_for" +selector = "#kpi-oee-sub" +text = "mean of" + +[[step]] +do = "say" +line = "The top of the floor screen. Four tiles, each one a question the plant asks every day." + +[[step]] +do = "say" +line = "Machines running: how many of the eighty-three are running right now." + +[[step]] +do = "say" +line = "Active orders: how many orders are out on the floor." + +[[step]] +do = "say" +line = "Plant OEE: how well the machines are doing, and underneath, how many machines that average is drawn from." + +[[step]] +do = "mark" +name = "four-tiles" + +[[step]] +do = "say" +line = "And the ERP queue: whether there is news still waiting to go back up to the office." + +[[step]] +do = "goto" +url = "/dashboard/orders?q=WO-STACK07" +settle = 3 + +[[step]] +do = "wait_for" +selector = "#order-list" +text = "WO-STACK07-0001" + +[[step]] +do = "say" +line = "Now one order, all the way round. Stacker line seven: make 260 stacks of a fork, a spoon and a knife." + +[[step]] +do = "click" +selector = "#order-list tbody tr:has-text('WO-STACK07-0001')" + +[[step]] +do = "wait_for" +selector = "#d-status" +text = "completed" +# The click scrolls the row into view and takes the order's figures under the +# sticky header with it; the panel is brought back below the header. +scroll_to = "#detail-panel" +scroll_block = "start" +scroll_offset = 220 + +[[step]] +do = "say" +line = "The order came down from above: released to the floor, with a quantity and a material." + +[[step]] +do = "say" +line = "On this plant there is no real office system connected, so the plant's own order book released it." + +[[step]] +do = "mark" +name = "the-order" + +[[step]] +do = "say" +line = "Its status says completed, and the booked count is what the machine reported, stack by stack." + +[[step]] +do = "goto" +url = "/dashboard/machine/STACK07_Stacker?hours=8" +settle = 3 + +[[step]] +do = "wait_for" +selector = "#m-order" +text = "WO-STACK07" + +[[step]] +do = "say" +line = "The machine that did the work. The stacker took the order, ran it, and counted every stack it made." + +[[step]] +do = "say" +line = "When the last stack was counted the order finished, and the stacker went straight on to the next one." + +[[step]] +do = "mark" +name = "the-machine" + +[[step]] +do = "goto" +url = "/dashboard/ops" +settle = 3 + +[[step]] +do = "wait_for" +selector = "#erp-facts" +text = "pending" +scroll_to = "#erp-section" +scroll_block = "start" +# Below the replay banner and the sticky header, which take the top 205 px. +scroll_offset = 220 + +[[step]] +do = "say" +line = "Then the news goes back up. When an order finishes, the MES writes a confirmation for the office: how many good, how many scrap." + +[[step]] +do = "say" +line = "This is the outbox: every message for the office, the confirmations and the machines' states alike. With no office system connected here, they wait as pending, and the tile said sending." + +[[step]] +do = "mark" +name = "the-outbox" + +[[step]] +do = "goto" +url = "/dashboard/ops?action=workorder.completed" +settle = 3 + +[[step]] +do = "wait_for" +selector = "#activity" +text = "WO-STACK07-0001" +scroll_to = "#activity tr" +scroll_text = "WO-STACK07-0001" +scroll_offset = 300 + +[[step]] +do = "say" +line = "And it is on the audit trail: our order's line says when it was completed, who completed it, and which order it was." + +[[step]] +do = "say" +line = "Who can be a person or a machine's agent. There is a line for every change, so every number can be traced back to where it came from." + +[[step]] +do = "mark" +name = "audit-trail" + +[[step]] +do = "say" +line = "That is the difference from the whiteboard. Not just the number, but a line saying where it came from." + +# -------------------------------------------------------------- it refuses + +[[step]] +part = "refuses" +do = "goto" +url = "/dashboard?line=PAL1LINE" +settle = 3 + +[[step]] +do = "wait_for" +selector = "#machines" +text = "Watched" +scroll_to = "#machines" +scroll_block = "start" +scroll_offset = 220 + +[[step]] +do = "say" +line = "One more word, and it is the most important one: watched." + +[[step]] +do = "say" +line = "Under every machine, the MES says how much of the last eight hours it actually saw." + +[[step]] +do = "mark" +name = "watched" + +[[step]] +do = "say" +line = "This plant is a few minutes old, so it saw only a few percent. It says so, beside the figure, instead of hiding it." + +[[step]] +do = "say" +line = "The rest of the window is unknown. It is not counted as running, and it is not counted as stopped." + +[[step]] +do = "say" +line = "A figure that says how little was seen, or a tile that says no figure, is the MES being honest, not broken." + +# ------------------------------------------------------------ you now know + +[[step]] +part = "know" +do = "slide" +name = "you-now-know" +title = "You now know how to" +lines = [ + "Place the MES between the office system that says what to make and the machines that make it.", + "Say what it is not: not the ERP, not the historian, not a spreadsheet.", + "Read Watched: a figure that says how little it saw is honest, not broken.", +] + +[[step]] +do = "say" +line = "That is where the MES sits, what it is not, and the word that keeps it honest. You now know how to do three things." + +[[step]] +do = "mark" +name = "you-now-know" + +[[step]] +do = "hold" +seconds = 3 diff --git a/tests/test_a_lesson_is_filmed_into_the_course_tree_and_touches_nothing_else.py b/tests/test_a_lesson_is_filmed_into_the_course_tree_and_touches_nothing_else.py index a2ee2595..7166c4f4 100644 --- a/tests/test_a_lesson_is_filmed_into_the_course_tree_and_touches_nothing_else.py +++ b/tests/test_a_lesson_is_filmed_into_the_course_tree_and_touches_nothing_else.py @@ -306,7 +306,9 @@ def test_lesson_json_says_the_lesson_the_files_the_reserved_corner_and_what_it_w "title": "Before the software"} assert document["lesson"]["label"] == "0.2" and document["lesson"]["order"] == 2 assert document["lesson"]["knows_before"] == ["0.1"] - assert document["lesson"]["outcomes"] == [], "an empty list says not written yet" + # The class's own three lines, as course.toml has them; a class whose lines + # are not written yet carries an empty list, never a missing key. + assert document["lesson"]["outcomes"] == lesson["outcomes"] and len(lesson["outcomes"]) == 3 assert (document["lesson"]["duration_seconds"], document["lesson"]["take"]) == (287.4, 3) assert document["files"] == files assert document["frame"] == {"width": 1280, "height": 720, "fps": 20} diff --git a/tests/test_class_0_2_places_the_mes_between_the_office_and_the_machines.py b/tests/test_class_0_2_places_the_mes_between_the_office_and_the_machines.py new file mode 100644 index 00000000..ba1c2ef2 --- /dev/null +++ b/tests/test_class_0_2_places_the_mes_between_the_office_and_the_machines.py @@ -0,0 +1,189 @@ +"""Class 0.2 places the MES between the office and the machines, on a scratch cutlery plant. + +*What an MES is, and what it is not* is the second class of the course: the +whiteboard the MES replaces, the three layers and the three things it is not, +the four tiles, one order followed from the office to a machine and back up, +and the word Watched. This file holds the scene file to what the outline asks +of it. No plant and no browser: the scene is loaded and walked the way the +recorder walks it. +""" + +from __future__ import annotations + +import importlib.util +import re +from pathlib import Path +from urllib.parse import urlparse + +import pytest + +from fsmes import modules + +REPO = Path(__file__).resolve().parents[1] +RUNNER = REPO / "scripts" / "record-scene.py" +SCENE = REPO / "scripts" / "scenes" / "course" / "01-02-what-an-mes-is-and-is-not.toml" + +# The lab fleet, the public demo and the stock demo ports: a class is never +# filmed on a plant somebody else is looking at. +NOT_OURS = {8090, 8110, 8120, 8140, 9030, 5433, 5434, 4944, 4945} + +# What no caption, card or note may carry: a calendar date, a year, a month's +# name. The class is about any plant on any day. +A_DATE = re.compile( + r"\b(19|20)\d\d\b|\b\d{1,2}/\d{1,2}/\d{2,4}\b|" + r"\b(January|February|March|April|May|June|July|August|September|October|November|December)\b" +) + + +@pytest.fixture(scope="module") +def runner(): + """`scripts/record-scene.py`, imported by path because of the hyphen.""" + spec = importlib.util.spec_from_file_location("record_scene_class_0_2", RUNNER) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +@pytest.fixture(scope="module") +def scene(runner): + return runner.load_scene(SCENE) + + +def everything_written(scene: dict) -> list[str]: + """Every sentence a viewer or a reader of the folder will see.""" + written = [scene["title"], *scene["notes"], *scene["honesty"]] + for step in scene["step"]: + if step["do"] == "say": + written.append(step["line"]) + if step["do"] == "slide": + written += [step["title"], *step["lines"]] + return written + + +def test_the_scene_is_a_full_take_of_class_0_2_named_by_its_label_that_runs_four_to_six_minutes(runner, scene): + assert scene["lesson"] == "0.2" and scene["take_is"] == "lesson" + assert (scene["width"], scene["height"]) == (1280, 720) + planned = runner.planned_seconds(scene) + # Page loads and waits add to the plan; the finished take is measured. + assert 240 <= planned <= scene["budget_seconds"] <= 360, planned + print(f"planned {planned} s against a {scene['budget_seconds']} s budget") + + +def test_it_films_into_the_second_folder_of_the_course(runner, scene): + course = runner.load_course(REPO / "scripts" / "course" / "course.toml") + _, lesson = runner.find_lesson(course, scene["lesson"]) + + assert lesson["path"] == "01-before-the-software/02-what-an-mes-is-and-is-not" + assert lesson["scene"] == SCENE.relative_to(REPO).as_posix() + + +def test_the_scene_walks_the_five_parts_in_order(runner, scene): + order = [] + for step in scene["step"]: + if not order or order[-1] != step["part"]: + order.append(step["part"]) + + assert order == list(runner.PARTS) + + +def test_the_hook_is_the_whiteboard_card_then_the_floor_and_is_short_enough_for_the_teaser(runner, scene): + hook = [step for step in scene["step"] if step["part"] == "hook"] + + assert hook[0]["do"] == "slide" and hook[0]["name"] == "the-whiteboard" + assert [step["url"] for step in hook if step["do"] == "goto"] == ["/dashboard"] + assert runner.planned_seconds(dict(scene, step=hook)) - scene["gif_skip_seconds"] <= 30 + + +def test_the_idea_cards_put_the_office_above_the_machines_below_and_say_the_three_nots(scene): + cards = {step["name"]: step for step in scene["step"] if step["do"] == "slide" and step["part"] == "idea"} + + layers = [line.split(":")[0] for line in cards["three-layers"]["lines"]] + nots = [line.split(":")[0] for line in cards["what-it-is-not"]["lines"]] + assert layers == ["The office system (ERP)", "The MES", "The machines (PLC / SCADA)"] + assert nots == ["Not the ERP", "Not the historian", "Not a spreadsheet"] + + +def test_one_order_is_followed_from_the_office_to_its_machine_and_back_up_to_the_audit_trail(scene): + screen = [step["url"] for step in scene["step"] if step["part"] == "screen" and step["do"] == "goto"] + + assert screen == [ + "/dashboard", + "/dashboard/orders?q=WO-STACK07", + "/dashboard/machine/STACK07_Stacker?hours=8", + "/dashboard/ops", + "/dashboard/ops?action=workorder.completed", + ] + assert scene["plant"]["roll_when_order"] == [{"code": "WO-STACK07-0001", "completed": True}] + + +def test_what_it_refuses_is_to_hide_how_little_it_watched(scene): + refuses = [step for step in scene["step"] if step["part"] == "refuses"] + said = " ".join(step["line"] for step in refuses if step["do"] == "say") + + assert any(step.get("text") == "Watched" for step in refuses if step["do"] == "wait_for") + assert "not counted as running, and it is not counted as stopped" in said + assert "no figure" in said + + +def test_the_you_now_know_card_says_the_classs_own_outcomes_word_for_word(runner, scene): + course = runner.load_course(REPO / "scripts" / "course" / "course.toml") + _, lesson = runner.find_lesson(course, scene["lesson"]) + know = [step for step in scene["step"] if step["part"] == "know" and step["do"] == "slide"] + + assert len(lesson["outcomes"]) == 3 + assert len(know) == 1 and know[0]["lines"] == lesson["outcomes"] + + +def test_every_page_it_visits_is_a_screen_the_app_serves(scene): + served = [page.path for module in modules.REGISTRY for page in module.pages] + patterns = [re.compile("^" + re.sub(r"\{[^}]+\}", "[^/]+", path) + "$") for path in served] + visited = {urlparse(step["url"]).path for step in scene["step"] if step["do"] == "goto"} + + unserved = sorted(path for path in visited if not any(p.match(path) for p in patterns)) + assert unserved == [], f"{len(unserved)} of {len(visited)} pages are not served: {unserved}" + + +def test_every_frame_carries_the_pre_alpha_simulated_plant_badge(scene): + assert scene["badge"] == "pre-alpha · simulated plant · v{version}" + + +def test_no_caption_card_or_note_carries_a_date(scene): + dated = [line for line in everything_written(scene) if A_DATE.search(line)] + + assert dated == [], f"{len(dated)} lines carry a date: {dated}" + + +def test_it_is_filmed_on_a_scratch_cutlery_plant_on_loopback_and_never_on_one_somebody_else_runs(scene): + base = urlparse(scene["base"]) + + assert scene["plant"]["pack"] == "labs/cutlery" + assert base.hostname == "127.0.0.1" + assert base.port not in NOT_OURS + assert not scene["allow_writes"] + + +def test_the_missing_office_system_and_the_replay_are_owned_up_to(scene): + honesty = " ".join(scene["honesty"]).lower() + + assert "no office system is connected" in honesty + assert "ten times" in honesty + + +def test_no_screen_of_people_is_filmed(scene): + urls = [step["url"] for step in scene["step"] if step["do"] == "goto"] + + assert not [url for url in urls if "people" in url or "/admin" in url] + + +def test_the_recorder_plays_every_step_of_it(runner, scene): + handed: list[str] = [] + + class Stage: + def __getattr__(self, verb): + return lambda *args: handed.append(verb) + + runner.play(scene, Stage()) + + assert handed.count("goto") == sum(1 for step in scene["step"] if step["do"] == "goto") + assert handed.count("scroll_to") == sum(1 for step in scene["step"] if step.get("scroll_to")) + assert handed.count("slide") == 4 and "terminal" not in handed