dynos-sim-bridge 0.1.5__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,14 @@
1
+ """Run the DYNOS planner in the loop with an external vehicle simulator.
2
+
3
+ One piece does the whole job:
4
+
5
+ - ``SimHardware`` (in ``bridge.py``): a servant robot class that both drives
6
+ your simulator for the vehicle's motion primitive (``goto``) AND reports the
7
+ vehicle's real position back to the planner through a servant belief
8
+ (``@Belief(fluent=at)``). The backend polls that belief after each step, the
9
+ same way it runs a local ``@Belief``, so the planner always builds on the
10
+ OBSERVED position and replans when the simulator did not end up where it was
11
+ commanded.
12
+
13
+ Example stub, modify as you wish.
14
+ """
@@ -0,0 +1,103 @@
1
+ """Simulator hardware class + a trivially simple stochastic simulator.
2
+
3
+ This is the servant side of the split: the user owns the simulator and the
4
+ ``goto`` action; the backend owns the planner. The vehicle's position reaches
5
+ the planner through a SERVANT BELIEF -- a ``@Belief(fluent=at)`` callback the
6
+ backend calls after each step, exactly like a local ``@Belief`` -- so the
7
+ planner always builds on the observed position, and replans when the simulator
8
+ did not end up where it was commanded.
9
+
10
+ The loop this closes:
11
+
12
+ 1. User sets a goal; backend plans; user triggers the mission.
13
+ 2. Backend dispatches ``goto(x)`` to this servant.
14
+ 3. ``go_to`` commands the simulator to drive to ``x``.
15
+ 4. The backend asks this servant to observe ``at`` -> ``observe_position``
16
+ reports where the simulator ACTUALLY is.
17
+ 5. If that matches the commanded ``x`` the planner continues; if the simulator
18
+ ended up elsewhere, the belief reflects reality and the planner replans.
19
+
20
+ STUB: replace ``StochasticSim`` with a bridge to your real simulator (same
21
+ ``goto``/``position`` shape).
22
+ """
23
+
24
+ import random
25
+ from typing import Optional
26
+
27
+ # vvv Recommended that you don't touch any of this vvv
28
+ from dynos_sentry.sentry import CoordinateGotoParams, at, goto
29
+ from dynos_client.belief import Belief, BeliefResult
30
+
31
+ try:
32
+ from dynos.databases.typed_action import Action
33
+ except ImportError:
34
+ from dynos_client.action import Action # type: ignore
35
+
36
+ # ^^^ Recommended you don't touch any of this ^^^
37
+
38
+ # Edit away down here
39
+
40
+
41
+ class StochasticSim:
42
+ """A trivially simple simulator: you tell it to go to waypoint x, and with
43
+ probability ``p_success`` the vehicle actually ends up there; otherwise it
44
+ stays where it was. That's the whole thing -- enough to exercise the
45
+ observe-and-replan loop. Replace with your real simulator.
46
+ """
47
+
48
+ def __init__(self, start: Optional[str] = None, p_success: float = 0.9,
49
+ rng: Optional[random.Random] = None):
50
+ self._position = start # the waypoint the vehicle is on (or None)
51
+ self._p_success = p_success
52
+ self._rng = rng or random.Random()
53
+
54
+ def goto(self, target: str) -> bool:
55
+ """Command a move to ``target``. Returns whether the vehicle actually
56
+ arrived there (True with probability ``p_success``)."""
57
+ if self._rng.random() < self._p_success:
58
+ self._position = target
59
+ return True
60
+ return False # missed: the vehicle stays put
61
+
62
+ def position(self) -> Optional[str]:
63
+ """The waypoint the vehicle is currently on (or None if unknown)."""
64
+ return self._position
65
+
66
+
67
+ class SimHardware:
68
+ """Servant robot class: drives the simulator for ``goto`` and reports the
69
+ vehicle's real position back through a ``@Belief`` the backend polls.
70
+
71
+ Register it as the servant's hardware; no orchestrator handle is needed --
72
+ the belief flows back through the servant-belief channel, not an out-of-band
73
+ ``set_belief``.
74
+ """
75
+
76
+ def __init__(self, sim: Optional[StochasticSim] = None):
77
+ self._sim = sim or StochasticSim()
78
+
79
+ @Action(transition=goto)
80
+ def go_to(self, params: CoordinateGotoParams, ctx) -> dict:
81
+ """Command the simulator to drive to the leg's endpoint.
82
+
83
+ Returns success if the simulator confirms arrival. Either way the
84
+ backend then polls ``observe_position`` for the truth; on a miss, the
85
+ belief reflects where the vehicle really is and the planner replans.
86
+ """
87
+ target = str(params.end)
88
+ arrived = self._sim.goto(target)
89
+ return {"success": arrived, "telemetry": {"commanded": target, "arrived": arrived}}
90
+
91
+ @Belief(fluent=at)
92
+ def observe_position(self, ctx) -> BeliefResult:
93
+ """Report the vehicle's ACTUAL symbolic position to the planner.
94
+
95
+ This is the servant belief: the backend calls it after a step (the same
96
+ way it runs a local ``@Belief``), and whatever waypoint the simulator
97
+ says the vehicle is on becomes ``at(<waypoint>)`` in the planner's
98
+ world -- the fluent SYMBOL, never a hand-built string.
99
+ """
100
+ waypoint = self._sim.position()
101
+ if waypoint is None:
102
+ return BeliefResult.unchecked() # between waypoints: no symbolic fix
103
+ return BeliefResult.acquired(observed_state=[at(waypoint)])
@@ -0,0 +1,45 @@
1
+ """Example: run a survey with the simulator in the loop.
2
+
3
+ There is no separate "sync the position" step: the vehicle's position reaches
4
+ the planner through ``SimHardware``'s servant belief (``@Belief(fluent=at)``),
5
+ which the backend polls after each step. You just set the goal and execute; the
6
+ planner issues ``goto`` legs, ``SimHardware`` drives the simulator through them,
7
+ and the observed position decides whether the planner continues or replans.
8
+
9
+ Usage::
10
+
11
+ from dynos_sim_bridge.mission import build_sim_survey_mission
12
+ from dynos_sim_bridge.bridge import SimHardware
13
+ from dynos_client import RemoteOrchestrator
14
+
15
+ orch = RemoteOrchestrator.from_config(timeout_s=3600)
16
+ results = orch.execute_blocks(build_sim_survey_mission("site_alpha"))
17
+ """
18
+
19
+ from dynos_client import Mission
20
+ from dynos_sentry.sentry import full_coverage_of
21
+
22
+
23
+ def build_sim_survey_mission(zone_name: str) -> Mission:
24
+ """Build a mission: take over, survey the zone, recover.
25
+
26
+ Args:
27
+ zone_name: name of the survey zone (must already exist as a domain
28
+ object on the backend)
29
+
30
+ Returns:
31
+ A Mission object ready for execution
32
+ """
33
+ mission = Mission(name=f"sim_survey_{zone_name}")
34
+
35
+ # Phase 1: initialize the vehicle
36
+ mission.add_action("takeover_control")
37
+
38
+ # Phase 2: survey the zone (the planner expands this into goto legs that
39
+ # SimHardware executes against the simulator)
40
+ mission.add_plan([full_coverage_of(zone_name)])
41
+
42
+ # Phase 3: recover
43
+ mission.add_action("full_abort") # strings work when you lack the backend symbol import
44
+
45
+ return mission
@@ -0,0 +1,49 @@
1
+ """Runnable for the simulator bridge.
2
+
3
+ This is the entry point for ``dynos connect``. It registers the
4
+ ``SimHardware`` robot class so the backend dispatches vehicle motion to this
5
+ node, which drives the simulator.
6
+
7
+ Usage::
8
+
9
+ dynos connect dynos_sim_bridge.runnable:SimBridgeNode \\
10
+ --to http://backend:8421
11
+ """
12
+
13
+ from typing import List
14
+
15
+
16
+ class SimBridgeNode:
17
+ """Runnable that provides simulator-backed vehicle motion to a backend.
18
+
19
+ This registers ``SimHardware`` so that the ``goto`` transition executes
20
+ against your simulator on this node.
21
+
22
+ This is a standardized format that the backend expects.
23
+ It shouldn't be necessary for you to modify this.
24
+ """
25
+
26
+ @staticmethod
27
+ def register(orchestrator, cli):
28
+ from dynos_sim_bridge.bridge import SimHardware
29
+
30
+ # Registering the class advertises both the ``goto`` action AND the
31
+ # ``at`` servant belief to the backend. No backend handle is needed:
32
+ # the vehicle's real position flows back when the backend polls the
33
+ # ``@Belief(fluent=at)`` callback after each step, so a divergence
34
+ # between commanded and actual is reported through that channel and the
35
+ # planner replans off the observation.
36
+ orchestrator.register_class(SimHardware, auto_construct=False)
37
+ orchestrator.bind_instance(SimHardware())
38
+
39
+ @staticmethod
40
+ def get_start_state(cli) -> List:
41
+ # No initial state; the vehicle's position reaches the planner through
42
+ # SimHardware's servant belief (@Belief(fluent=at)), not a start-state
43
+ # injection.
44
+ return []
45
+
46
+ @staticmethod
47
+ def get_start_goal(cli) -> List:
48
+ # No default goal; the backend sets the mission goal
49
+ return []
@@ -0,0 +1,197 @@
1
+ Metadata-Version: 2.1
2
+ Name: dynos-sim-bridge
3
+ Version: 0.1.5
4
+ Summary: Run the DYNOS planner in the loop with an external vehicle simulator
5
+ License: Apache-2.0
6
+ Requires-Python: >=3.8
7
+ Description-Content-Type: text/markdown
8
+ Requires-Dist: dynos-client >=0.1.5
9
+ Requires-Dist: dynos-sentry-domain ==0.1.5
10
+ Provides-Extra: dev
11
+ Requires-Dist: pytest ; extra == 'dev'
12
+
13
+ # dynos-sim-bridge
14
+
15
+ A worked example: run the DYNOS planner in the loop with an external vehicle
16
+ simulator. This package is scaffolding: it ships a stub `SimHardware` plus a
17
+ trivially simple `StochasticSim` that you replace with calls into your
18
+ simulator, and the wiring (`runnable.py`, `mission.py`) that lets `dynos
19
+ connect` find it.
20
+
21
+ It demonstrates the two channels a simulator needs, both on the one
22
+ `SimHardware` class:
23
+
24
+ - **Motion out** (planner -> simulator): `SimHardware` implements the `goto`
25
+ transition by commanding your simulator, exactly like the real Sentry
26
+ hardware class commands the vehicle.
27
+ - **State in** (simulator -> planner): the vehicle's real position flows back
28
+ through a **servant belief** -- a `@Belief(fluent=at)` callback the backend
29
+ polls after each step, exactly the way it runs a local `@Belief`. Whatever
30
+ waypoint the simulator reports becomes `at(<waypoint>)` in the planner's
31
+ world. If the simulator ended up somewhere other than commanded, the belief
32
+ reflects reality and the planner replans from there.
33
+
34
+ There is no separate position-sync step and no out-of-band `set_belief`: the
35
+ planner always builds on the observed position because the observation is the
36
+ channel.
37
+
38
+ ## Install
39
+
40
+ You will be modifying the source, so install editable:
41
+
42
+ ```bash
43
+ pip install -e dynos-sim-bridge
44
+ ```
45
+
46
+ This pulls in `dynos-client` and `dynos-sentry-domain`.
47
+
48
+ ## What's in this repository
49
+
50
+ ### `bridge.py`
51
+
52
+ Provides `StochasticSim` (the stand-in simulator) and `SimHardware`, which wires
53
+ it to the planner:
54
+
55
+ - `@Action(transition=goto) go_to`: command the simulator to drive to the leg's
56
+ endpoint.
57
+ - `@Belief(fluent=at) observe_position`: report the vehicle's real symbolic
58
+ position back to the planner.
59
+
60
+ Everything above the `Edit away down here` line is plumbing you should leave
61
+ alone; replace `StochasticSim` with a bridge to your real simulator (same
62
+ `goto`/`position` shape).
63
+
64
+ ### `mission.py`
65
+
66
+ Provides `build_sim_survey_mission(zone_name)`. Edit if you want a different
67
+ sequence.
68
+
69
+ ### `runnable.py`
70
+
71
+ Provides `SimBridgeNode`, the `dynos connect`-compatible entry point. You
72
+ probably don't need to edit this.
73
+
74
+ > `SimHardware` claims the `goto` transition. Registering it *replaces* whatever
75
+ > was executing `goto` (e.g. the `sentry-mock` hardware's own `goto`) -- that is
76
+ > the point: your simulator becomes the motion executor. Run the bridge instead
77
+ > of a second motion provider, not alongside one.
78
+
79
+ ## Why a servant belief, not `create_object` + `set_start`
80
+
81
+ The tempting way to tell the planner where the vehicle is each tick is to create
82
+ a `current_location` coordinate and reset the initial state. Don't:
83
+
84
+ - `set_start` re-derives the whole initial state; it is a planning-time input,
85
+ not a per-tick observation channel.
86
+ - Two points at the same lon/lat **and** altitude are the same physical point,
87
+ so a `current_location` that lands on a known waypoint is collapsed onto that
88
+ waypoint by the backend, and you then have to discover the canonical name.
89
+
90
+ A servant belief skips all of that: the backend asks your servant "where is the
91
+ vehicle `at`?" and your `observe_position` answers with the `at` fluent symbol
92
+ over a waypoint the planner already knows.
93
+
94
+ ## How the round-trip works
95
+
96
+ 1. You launch the bridge as a servant: `dynos connect
97
+ dynos_sim_bridge.runnable:SimBridgeNode`. Registering `SimHardware`
98
+ advertises both the `goto` action and the `at` belief, then it idles.
99
+ 2. From a second process you set the goal and execute a mission. No position
100
+ sync is needed first -- the planner learns the position from the belief.
101
+ 3. The planner expands `full_coverage_of(zone)` into `goto` legs and dispatches
102
+ each to your servant.
103
+ 4. `SimHardware.go_to` drives the simulator toward the leg's endpoint `x`. Then
104
+ the backend polls `observe_position`:
105
+ - **Vehicle is at `x`:** the observation confirms the `goto` effect `at(x)`;
106
+ the planner continues to the next leg.
107
+ - **Vehicle ended up at `y`** (current, obstacle, missed move): the
108
+ observation reports `at(y)`; the effect `at(x)` is *not* confirmed, so the
109
+ step gates and the planner replans toward the same goal from `y`. This is
110
+ the planner operating on updated symbolic knowledge -- the point of running
111
+ it in the loop.
112
+ 5. The mission ends with `full_abort` (controlled ascent).
113
+
114
+ The servant belief goes through the client API: `@Belief`/`BeliefResult` are
115
+ exported from `dynos_client`, so a remote servant running with `dynos_client`
116
+ alone reports beliefs exactly as an in-tree robot class does with the
117
+ backend-side `@Belief`.
118
+
119
+ ## Replacing the stub
120
+
121
+ Replace `StochasticSim` with a small adapter over your simulator, keeping the
122
+ same two methods:
123
+
124
+ `goto(target)`: command your simulator to drive to `target` (a waypoint name)
125
+ and return whether it arrived.
126
+
127
+ `position()`: return the name of the waypoint the vehicle is currently on, or
128
+ `None` when it is between waypoints (the belief then reports "unchecked" and the
129
+ planner keeps its prior position).
130
+
131
+ Coordinates follow the project convention: `(longitude, latitude)`, degrees for
132
+ `geographic`, meters for `local_enu`. Altitude is part of a point's identity.
133
+
134
+ ## Test offline
135
+
136
+ Before pointing at the real backend, run the package's own tests:
137
+
138
+ ```bash
139
+ pip install -e "dynos-sim-bridge/[dev]"
140
+ pytest dynos-sim-bridge/tests/ -v
141
+ ```
142
+
143
+ These exercise `StochasticSim`, the `goto` plumbing, and the `at` belief. No
144
+ network or session needed. The end-to-end loop (backend polls the belief and
145
+ continues or replans) is covered by the sentry integration test
146
+ `tests/sentry/test_servant_beliefs.py`.
147
+
148
+ ## Run it for real
149
+
150
+ Two terminals.
151
+
152
+ Terminal 1 is your simulator bridge:
153
+
154
+ ```bash
155
+ dynos login # logins persist across terminals but expire after an hour
156
+ dynos session create --robot sentry-mock
157
+ dynos connect dynos_sim_bridge.runnable:SimBridgeNode
158
+ ```
159
+
160
+ Leave it running. It executes `goto` whenever the backend reaches a leg, and
161
+ answers the `at` belief whenever the backend polls it.
162
+
163
+ Terminal 2 is the mission. Create the survey zone and run:
164
+
165
+ ```bash
166
+ dynos call create zone.json
167
+ ```
168
+
169
+ ```python
170
+ from dynos_client import RemoteOrchestrator
171
+ from dynos_sim_bridge.mission import build_sim_survey_mission
172
+
173
+ orch = RemoteOrchestrator.from_config(timeout_s=3600)
174
+ for r in orch.execute_blocks(build_sim_survey_mission("site_alpha")):
175
+ print(r)
176
+ ```
177
+
178
+ ## Public API
179
+
180
+ | Symbol | From | Purpose |
181
+ |-----------------------------------|-----------------------------|------------------------------------------------------|
182
+ | `SimHardware` | `dynos_sim_bridge.bridge` | The robot class you edit; executes `goto`, observes `at`. |
183
+ | `StochasticSim` | `dynos_sim_bridge.bridge` | The trivial stand-in simulator you replace. |
184
+ | `SimBridgeNode` | `dynos_sim_bridge.runnable` | The `dynos connect` entry point. |
185
+ | `build_sim_survey_mission(zone)` | `dynos_sim_bridge.mission` | Take over, survey, recover. |
186
+
187
+ ## Troubleshooting
188
+
189
+ Bridge never gets an assignment: the mission hasn't reached a `goto` leg. Check
190
+ `dynos call state --scope public`.
191
+
192
+ `at(<name>)` unresolved: the name your `position()` returned isn't a registered
193
+ object. Return the name of a waypoint the planner knows (e.g. the leg's
194
+ endpoint), not an ad-hoc string.
195
+
196
+ For cross-package issues (login, session, connection), see `user_guide.md` or
197
+ `dynos-client`'s README.
@@ -0,0 +1,8 @@
1
+ dynos_sim_bridge/__init__.py,sha256=JxLecrHRuYa3uB5YkNhKgFFjF3afEAGKGAuxp95qrEk,618
2
+ dynos_sim_bridge/bridge.py,sha256=HRBFV0GToL53KNRJ1Q8KuPwB-0xBeqzsfV3x2zovA_k,4330
3
+ dynos_sim_bridge/mission.py,sha256=Qj-sQiu3LGYAx3x5IlyLqJ2-yCvQn8yWJfta2v9bHtU,1616
4
+ dynos_sim_bridge/runnable.py,sha256=JTDpaNMyUqVkqZkx9Qqh40MMmxiuHp5ZGkpyQIYawOc,1742
5
+ dynos_sim_bridge-0.1.5.dist-info/METADATA,sha256=jeWS9xj-NpXCfFQ5NZnWB7rGz-CF8awDvf55VKpY9pg,7890
6
+ dynos_sim_bridge-0.1.5.dist-info/WHEEL,sha256=BNRMDyzLkkcmlv0J8ppDQkk2VED33SesJDynr9ED1gc,91
7
+ dynos_sim_bridge-0.1.5.dist-info/top_level.txt,sha256=xYtHH4gT2fsq7xUtz1J-K-WP-oJd46Uv8yNv3EN-Qow,17
8
+ dynos_sim_bridge-0.1.5.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (75.3.4)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1 @@
1
+ dynos_sim_bridge