mbse 0.1.0__py3-none-any.whl

mbse/examples/elevator/README.md

@@ -0,0 +1,39 @@
+# Elevator Example
+
+This packaged example models one elevator serving a floor request. It is a
+small, runnable viewer demonstration rather than a production elevator design.
+
+Run it after installing `mbse`:
+
+```bash
+mbse-example-view
+```
+
+Send `Request elevator` with a pickup floor, then `Select destination` once the
+viewer reaches `Awaiting destination`. Follow execution with step into, step
+over, and step out.
+
+## Use Case
+
+The HSM has an `operational` composite state with one nested `servicing` cycle:
+`planning`, `travelling`, and `doors`. The shared `service_phase` Context value
+uses that cycle first for pickup and then for delivery.
+
+The service cycle invokes nested Activities to plan the trip, choose a
+direction, verify movement clearance, travel, and operate the doors.
+Clearance Activities set the shared `result` variable, which their parent
+decisions use. Requests for the current floor open the pickup doors directly;
+selecting the current floor does not start a delivery trip.
+
+`emergency_stop` is handled by `operational`, not by its leaf states. Sending
+it while any operational child is active demonstrates HSM event bubbling to the
+shared parent transition. A blocked door sequence enters `Doorway blocked`.
+`reset` exits either that state or `Emergency stop`.
+
+This demonstrates HSM events, shared Context variables, model executable
+references, nested runtime frames, and viewer model navigation. The authored
+models and handler implementation remain the source of truth.
+
+Related documentation: [Model Layer](../../model/doc/model.md),
+[Runtime Layer](../../runtime/doc/runtime.md), and
+[Viewer Server](../../../../mbse_web_viewer/server/doc/server.md).

mbse/examples/elevator/__init__.py

@@ -0,0 +1,53 @@
+"""Packaged elevator example for the MBSE web viewer."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from mbse_web_viewer.server.http_server import RunningViewerServer
+from mbse_web_viewer.server.viewer_app import startProjectViewerServerFromProjectPath
+
+
+def getProjectPath() -> Path:
+  """Return the packaged elevator project file."""
+
+  return Path(__file__).with_name("project.json")
+
+
+def startViewer(
+  *,
+  host: str = "127.0.0.1",
+  port: int = 0,
+  open_browser: bool = False,
+) -> RunningViewerServer:
+  """Start the local viewer for the packaged elevator example."""
+
+  return startProjectViewerServerFromProjectPath(
+    getProjectPath(),
+    host=host,
+    port=port,
+    open_browser=open_browser,
+  )
+
+
+def main(argv: list[str] | None = None) -> int:
+  """Launch the packaged elevator example from the command line."""
+
+  parser = argparse.ArgumentParser(description="Launch the MBSE elevator example.")
+  parser.add_argument("--host", default="127.0.0.1")
+  parser.add_argument("--port", default=0, type=int)
+  parser.add_argument("--open-browser", action="store_true")
+  args = parser.parse_args(argv)
+
+  server = startViewer(
+    host=args.host,
+    port=args.port,
+    open_browser=args.open_browser,
+  )
+  print(server.base_url)
+  try:
+    server.waitUntilStopped()
+  except KeyboardInterrupt:
+    server.close()
+  return 0

mbse/examples/elevator/__main__.py

@@ -0,0 +1,6 @@
+"""Run the packaged elevator example as a module."""
+
+from mbse.examples.elevator import main
+
+
+raise SystemExit(main())

mbse/examples/elevator/check_car_clearance.json

@@ -0,0 +1,28 @@
+{
+  "schema_version": "mbse-activity-model-v0",
+  "document_id": "check_car_clearance",
+  "initial": {
+    "target_id": "evaluate_emergency"
+  },
+  "actions": [
+    {
+      "id": "evaluate_emergency",
+      "label": "Evaluate emergency state",
+      "executable": {
+        "kind": "action_language",
+        "module": "mbse.examples.elevator.executables",
+        "name": "isCarClear"
+      },
+      "transition": {
+        "target_id": "clearance_checked"
+      }
+    }
+  ],
+  "decisions": [],
+  "finals": [
+    {
+      "id": "clearance_checked",
+      "label": "Clearance checked"
+    }
+  ]
+}

mbse/examples/elevator/choose_direction.json

@@ -0,0 +1,56 @@
+{
+  "schema_version": "mbse-activity-model-v0",
+  "document_id": "choose_direction",
+  "initial": {
+    "target_id": "target_is_above"
+  },
+  "actions": [
+    {
+      "id": "set_direction_up",
+      "label": "Set direction up",
+      "executable": {
+        "kind": "action_language",
+        "module": "mbse.examples.elevator.executables",
+        "name": "setDirectionUp"
+      },
+      "transition": {
+        "target_id": "direction_selected"
+      }
+    },
+    {
+      "id": "set_direction_down",
+      "label": "Set direction down",
+      "executable": {
+        "kind": "action_language",
+        "module": "mbse.examples.elevator.executables",
+        "name": "setDirectionDown"
+      },
+      "transition": {
+        "target_id": "direction_selected"
+      }
+    }
+  ],
+  "decisions": [
+    {
+      "id": "target_is_above",
+      "label": "Target is above current floor",
+      "condition": {
+        "kind": "action_language",
+        "module": "mbse.examples.elevator.executables",
+        "name": "targetIsAboveCurrent"
+      },
+      "true_transition": {
+        "target_id": "set_direction_up"
+      },
+      "false_transition": {
+        "target_id": "set_direction_down"
+      }
+    }
+  ],
+  "finals": [
+    {
+      "id": "direction_selected",
+      "label": "Direction selected"
+    }
+  ]
+}

mbse/examples/elevator/context.json

@@ -0,0 +1,76 @@
+{
+  "schema_version": "mbse-context-model-v0",
+  "document_id": "elevator_context",
+  "enums": [
+    {
+      "id": "direction",
+      "values": ["up", "down"]
+    },
+    {
+      "id": "service_phase",
+      "values": ["pickup", "delivery"]
+    }
+  ],
+  "variables": [
+    {
+      "name": "current_floor",
+      "type": "unsigned",
+      "min": 0,
+      "max": 10,
+      "default_value": 0
+    },
+    {
+      "name": "target_floor",
+      "type": "unsigned",
+      "min": 0,
+      "max": 10,
+      "default_value": 0
+    },
+    {
+      "name": "pickup_floor",
+      "type": "unsigned",
+      "min": 0,
+      "max": 10,
+      "default_value": 0
+    },
+    {
+      "name": "destination_floor",
+      "type": "unsigned",
+      "min": 0,
+      "max": 10,
+      "default_value": 0
+    },
+    {
+      "name": "direction",
+      "type": "enum",
+      "enum_id": "direction",
+      "default_value": "up"
+    },
+    {
+      "name": "service_phase",
+      "type": "enum",
+      "enum_id": "service_phase",
+      "default_value": "pickup"
+    },
+    {
+      "name": "doorway_clear",
+      "type": "bool",
+      "default_value": true
+    },
+    {
+      "name": "doors_open",
+      "type": "bool",
+      "default_value": false
+    },
+    {
+      "name": "emergency_active",
+      "type": "bool",
+      "default_value": false
+    },
+    {
+      "name": "result",
+      "type": "bool",
+      "default_value": false
+    }
+  ]
+}

mbse/examples/elevator/elevator_hsm.json

@@ -0,0 +1,294 @@
+{
+  "schema_version": "mbse-hsm-model-v0",
+  "document_id": "elevator_hsm",
+  "events": [
+    {
+      "id": "request_elevator",
+      "label": "Request elevator",
+      "parameters": [
+        {
+          "name": "floor",
+          "type": "unsigned",
+          "min": 0,
+          "max": 10
+        }
+      ]
+    },
+    {
+      "id": "select_destination",
+      "label": "Select destination",
+      "parameters": [
+        {
+          "name": "floor",
+          "type": "unsigned",
+          "min": 0,
+          "max": 10
+        }
+      ]
+    },
+    {
+      "id": "trip_ready",
+      "label": "Trip ready"
+    },
+    {
+      "id": "arrived",
+      "label": "Arrived"
+    },
+    {
+      "id": "doors_ready",
+      "label": "Doors ready"
+    },
+    {
+      "id": "doorway_blocked",
+      "label": "Doorway blocked"
+    },
+    {
+      "id": "emergency_stop",
+      "label": "Emergency stop"
+    },
+    {
+      "id": "reset",
+      "label": "Reset"
+    }
+  ],
+  "initial_transition": {
+    "target_id": "operational"
+  },
+  "states": [
+    {
+      "id": "operational",
+      "label": "Operational",
+      "initial_transition": {
+        "target_id": "idle"
+      },
+      "external_transitions": [
+        {
+          "event_id": "emergency_stop",
+          "target_id": "emergency",
+          "activities": [
+            {
+              "kind": "action_language",
+              "module": "mbse.examples.elevator.executables",
+              "name": "activateEmergency"
+            }
+          ]
+        }
+      ],
+      "states": [
+        {
+          "id": "idle",
+          "label": "Idle",
+          "external_transitions": [
+            {
+              "event_id": "request_elevator",
+              "guard_condition": {
+                "guard_activity": {
+                  "kind": "action_language",
+                  "module": "mbse.examples.elevator.executables",
+                  "name": "requestedFloorIsCurrent"
+                },
+                "true_branch": {
+                  "target_id": "doors",
+                  "activities": [
+                    {
+                      "kind": "action_language",
+                      "module": "mbse.examples.elevator.executables",
+                      "name": "capturePickupFloor"
+                    },
+                    {
+                      "kind": "action_language",
+                      "module": "mbse.examples.elevator.executables",
+                      "name": "setPickupPhase"
+                    }
+                  ]
+                },
+                "false_branch": {
+                  "target_id": "servicing",
+                  "activities": [
+                    {
+                      "kind": "action_language",
+                      "module": "mbse.examples.elevator.executables",
+                      "name": "capturePickupFloor"
+                    },
+                    {
+                      "kind": "action_language",
+                      "module": "mbse.examples.elevator.executables",
+                      "name": "setPickupPhase"
+                    }
+                  ]
+                }
+              }
+            }
+          ]
+        },
+        {
+          "id": "servicing",
+          "label": "Service trip",
+          "initial_transition": {
+            "target_id": "planning"
+          },
+          "states": [
+            {
+              "id": "planning",
+              "label": "Planning trip",
+              "hooks": {
+                "on_entry": [
+                  {
+                    "kind": "model",
+                    "model_id": "plan_trip"
+                  },
+                  {
+                    "kind": "action_language",
+                    "module": "mbse.examples.elevator.executables",
+                    "name": "queueTripReady"
+                  }
+                ]
+              },
+              "external_transitions": [
+                {
+                  "event_id": "trip_ready",
+                  "target_id": "travelling"
+                }
+              ]
+            },
+            {
+              "id": "travelling",
+              "label": "Travelling",
+              "hooks": {
+                "on_entry": [
+                  {
+                    "kind": "model",
+                    "model_id": "travel_to_target"
+                  },
+                  {
+                    "kind": "action_language",
+                    "module": "mbse.examples.elevator.executables",
+                    "name": "queueArrival"
+                  }
+                ]
+              },
+              "external_transitions": [
+                {
+                  "event_id": "arrived",
+                  "target_id": "doors"
+                }
+              ]
+            },
+            {
+              "id": "doors",
+              "label": "Door cycle",
+              "hooks": {
+                "on_entry": [
+                  {
+                    "kind": "model",
+                    "model_id": "operate_doors"
+                  },
+                  {
+                    "kind": "action_language",
+                    "module": "mbse.examples.elevator.executables",
+                    "name": "queueDoorResult"
+                  }
+                ]
+              },
+              "external_transitions": [
+                {
+                  "event_id": "doors_ready",
+                  "guard_condition": {
+                    "guard_activity": {
+                      "kind": "action_language",
+                      "module": "mbse.examples.elevator.executables",
+                      "name": "isPickupPhase"
+                    },
+                    "true_branch": {
+                      "target_id": "awaiting_destination"
+                    },
+                    "false_branch": {
+                      "target_id": "idle"
+                    }
+                  }
+                },
+                {
+                  "event_id": "doorway_blocked",
+                  "target_id": "blocked"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "id": "awaiting_destination",
+          "label": "Awaiting destination",
+          "external_transitions": [
+            {
+              "event_id": "select_destination",
+              "guard_condition": {
+                "guard_activity": {
+                  "kind": "action_language",
+                  "module": "mbse.examples.elevator.executables",
+                  "name": "requestedFloorIsCurrent"
+                },
+                "true_branch": {
+                  "target_id": "awaiting_destination",
+                  "activities": [
+                    {
+                      "kind": "action_language",
+                      "module": "mbse.examples.elevator.executables",
+                      "name": "captureDestinationFloor"
+                    },
+                    {
+                      "kind": "action_language",
+                      "module": "mbse.examples.elevator.executables",
+                      "name": "setDeliveryPhase"
+                    }
+                  ]
+                },
+                "false_branch": {
+                  "target_id": "servicing",
+                  "activities": [
+                    {
+                      "kind": "action_language",
+                      "module": "mbse.examples.elevator.executables",
+                      "name": "captureDestinationFloor"
+                    },
+                    {
+                      "kind": "action_language",
+                      "module": "mbse.examples.elevator.executables",
+                      "name": "setDeliveryPhase"
+                    }
+                  ]
+                }
+              }
+            }
+          ]
+        },
+        {
+          "id": "blocked",
+          "label": "Doorway blocked",
+          "external_transitions": [
+            {
+              "event_id": "reset",
+              "target_id": "idle"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "emergency",
+      "label": "Emergency stop",
+      "external_transitions": [
+        {
+          "event_id": "reset",
+          "target_id": "idle",
+          "activities": [
+            {
+              "kind": "action_language",
+              "module": "mbse.examples.elevator.executables",
+              "name": "clearEmergency"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

mbse/examples/elevator/executables.py

@@ -0,0 +1,119 @@
+"""Action-language handlers for the packaged elevator example."""
+
+from __future__ import annotations
+
+
+def capturePickupFloor(ctx) -> None:
+  """Store the floor where the passenger requested service."""
+
+  ctx.pickup_floor = ctx.event_parameters["floor"]
+  ctx.target_floor = ctx.pickup_floor
+
+
+def captureDestinationFloor(ctx) -> None:
+  """Store the floor selected from inside the elevator."""
+
+  ctx.destination_floor = ctx.event_parameters["floor"]
+  ctx.target_floor = ctx.destination_floor
+
+
+def requestedFloorIsCurrent(ctx) -> bool:
+  """Return whether an event requests the elevator's current floor."""
+
+  return ctx.event_parameters["floor"] == ctx.current_floor
+
+
+def setPickupPhase(ctx) -> None:
+  """Mark the shared service cycle as a passenger pickup."""
+
+  ctx.service_phase = "pickup"
+
+
+def setDeliveryPhase(ctx) -> None:
+  """Mark the shared service cycle as a passenger delivery."""
+
+  ctx.service_phase = "delivery"
+
+
+def isPickupPhase(ctx) -> bool:
+  """Return whether the completed door cycle belongs to a pickup."""
+
+  return ctx.service_phase == "pickup"
+
+
+def queueTripReady(ctx) -> None:
+  """Continue from trip planning to travel."""
+
+  ctx.send_event("trip_ready")
+
+
+def queueArrival(ctx) -> None:
+  """Continue from travel to the door cycle."""
+
+  ctx.send_event("arrived")
+
+
+def queueDoorResult(ctx) -> None:
+  """Advance or block the HSM according to the nested door Activity result."""
+
+  ctx.send_event("doors_ready" if ctx.result else "doorway_blocked")
+
+
+def targetIsAboveCurrent(ctx) -> bool:
+  """Return whether the elevator must travel upward."""
+
+  return ctx.target_floor > ctx.current_floor
+
+
+def setDirectionUp(ctx) -> None:
+  """Record upward travel."""
+
+  ctx.direction = "up"
+
+
+def setDirectionDown(ctx) -> None:
+  """Record downward travel."""
+
+  ctx.direction = "down"
+
+
+def isCarClear(ctx) -> None:
+  """Return whether movement is permitted through the shared result variable."""
+
+  ctx.result = not ctx.emergency_active
+
+
+def moveToTargetFloor(ctx) -> None:
+  """Complete the simulated movement."""
+
+  ctx.current_floor = ctx.target_floor
+
+
+def isDoorwayClear(ctx) -> None:
+  """Return whether the door sequence may run."""
+
+  ctx.result = ctx.doorway_clear
+
+
+def openDoors(ctx) -> None:
+  """Record an open-door phase."""
+
+  ctx.doors_open = True
+
+
+def closeDoors(ctx) -> None:
+  """Record a completed door cycle."""
+
+  ctx.doors_open = False
+
+
+def activateEmergency(ctx) -> None:
+  """Stop future movement until reset."""
+
+  ctx.emergency_active = True
+
+
+def clearEmergency(ctx) -> None:
+  """Return the controller to normal operation."""
+
+  ctx.emergency_active = False