dynos-sim-bridge 0.1.5__tar.gz

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,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,185 @@
1
+ # dynos-sim-bridge
2
+
3
+ A worked example: run the DYNOS planner in the loop with an external vehicle
4
+ simulator. This package is scaffolding: it ships a stub `SimHardware` plus a
5
+ trivially simple `StochasticSim` that you replace with calls into your
6
+ simulator, and the wiring (`runnable.py`, `mission.py`) that lets `dynos
7
+ connect` find it.
8
+
9
+ It demonstrates the two channels a simulator needs, both on the one
10
+ `SimHardware` class:
11
+
12
+ - **Motion out** (planner -> simulator): `SimHardware` implements the `goto`
13
+ transition by commanding your simulator, exactly like the real Sentry
14
+ hardware class commands the vehicle.
15
+ - **State in** (simulator -> planner): the vehicle's real position flows back
16
+ through a **servant belief** -- a `@Belief(fluent=at)` callback the backend
17
+ polls after each step, exactly the way it runs a local `@Belief`. Whatever
18
+ waypoint the simulator reports becomes `at(<waypoint>)` in the planner's
19
+ world. If the simulator ended up somewhere other than commanded, the belief
20
+ reflects reality and the planner replans from there.
21
+
22
+ There is no separate position-sync step and no out-of-band `set_belief`: the
23
+ planner always builds on the observed position because the observation is the
24
+ channel.
25
+
26
+ ## Install
27
+
28
+ You will be modifying the source, so install editable:
29
+
30
+ ```bash
31
+ pip install -e dynos-sim-bridge
32
+ ```
33
+
34
+ This pulls in `dynos-client` and `dynos-sentry-domain`.
35
+
36
+ ## What's in this repository
37
+
38
+ ### `bridge.py`
39
+
40
+ Provides `StochasticSim` (the stand-in simulator) and `SimHardware`, which wires
41
+ it to the planner:
42
+
43
+ - `@Action(transition=goto) go_to`: command the simulator to drive to the leg's
44
+ endpoint.
45
+ - `@Belief(fluent=at) observe_position`: report the vehicle's real symbolic
46
+ position back to the planner.
47
+
48
+ Everything above the `Edit away down here` line is plumbing you should leave
49
+ alone; replace `StochasticSim` with a bridge to your real simulator (same
50
+ `goto`/`position` shape).
51
+
52
+ ### `mission.py`
53
+
54
+ Provides `build_sim_survey_mission(zone_name)`. Edit if you want a different
55
+ sequence.
56
+
57
+ ### `runnable.py`
58
+
59
+ Provides `SimBridgeNode`, the `dynos connect`-compatible entry point. You
60
+ probably don't need to edit this.
61
+
62
+ > `SimHardware` claims the `goto` transition. Registering it *replaces* whatever
63
+ > was executing `goto` (e.g. the `sentry-mock` hardware's own `goto`) -- that is
64
+ > the point: your simulator becomes the motion executor. Run the bridge instead
65
+ > of a second motion provider, not alongside one.
66
+
67
+ ## Why a servant belief, not `create_object` + `set_start`
68
+
69
+ The tempting way to tell the planner where the vehicle is each tick is to create
70
+ a `current_location` coordinate and reset the initial state. Don't:
71
+
72
+ - `set_start` re-derives the whole initial state; it is a planning-time input,
73
+ not a per-tick observation channel.
74
+ - Two points at the same lon/lat **and** altitude are the same physical point,
75
+ so a `current_location` that lands on a known waypoint is collapsed onto that
76
+ waypoint by the backend, and you then have to discover the canonical name.
77
+
78
+ A servant belief skips all of that: the backend asks your servant "where is the
79
+ vehicle `at`?" and your `observe_position` answers with the `at` fluent symbol
80
+ over a waypoint the planner already knows.
81
+
82
+ ## How the round-trip works
83
+
84
+ 1. You launch the bridge as a servant: `dynos connect
85
+ dynos_sim_bridge.runnable:SimBridgeNode`. Registering `SimHardware`
86
+ advertises both the `goto` action and the `at` belief, then it idles.
87
+ 2. From a second process you set the goal and execute a mission. No position
88
+ sync is needed first -- the planner learns the position from the belief.
89
+ 3. The planner expands `full_coverage_of(zone)` into `goto` legs and dispatches
90
+ each to your servant.
91
+ 4. `SimHardware.go_to` drives the simulator toward the leg's endpoint `x`. Then
92
+ the backend polls `observe_position`:
93
+ - **Vehicle is at `x`:** the observation confirms the `goto` effect `at(x)`;
94
+ the planner continues to the next leg.
95
+ - **Vehicle ended up at `y`** (current, obstacle, missed move): the
96
+ observation reports `at(y)`; the effect `at(x)` is *not* confirmed, so the
97
+ step gates and the planner replans toward the same goal from `y`. This is
98
+ the planner operating on updated symbolic knowledge -- the point of running
99
+ it in the loop.
100
+ 5. The mission ends with `full_abort` (controlled ascent).
101
+
102
+ The servant belief goes through the client API: `@Belief`/`BeliefResult` are
103
+ exported from `dynos_client`, so a remote servant running with `dynos_client`
104
+ alone reports beliefs exactly as an in-tree robot class does with the
105
+ backend-side `@Belief`.
106
+
107
+ ## Replacing the stub
108
+
109
+ Replace `StochasticSim` with a small adapter over your simulator, keeping the
110
+ same two methods:
111
+
112
+ `goto(target)`: command your simulator to drive to `target` (a waypoint name)
113
+ and return whether it arrived.
114
+
115
+ `position()`: return the name of the waypoint the vehicle is currently on, or
116
+ `None` when it is between waypoints (the belief then reports "unchecked" and the
117
+ planner keeps its prior position).
118
+
119
+ Coordinates follow the project convention: `(longitude, latitude)`, degrees for
120
+ `geographic`, meters for `local_enu`. Altitude is part of a point's identity.
121
+
122
+ ## Test offline
123
+
124
+ Before pointing at the real backend, run the package's own tests:
125
+
126
+ ```bash
127
+ pip install -e "dynos-sim-bridge/[dev]"
128
+ pytest dynos-sim-bridge/tests/ -v
129
+ ```
130
+
131
+ These exercise `StochasticSim`, the `goto` plumbing, and the `at` belief. No
132
+ network or session needed. The end-to-end loop (backend polls the belief and
133
+ continues or replans) is covered by the sentry integration test
134
+ `tests/sentry/test_servant_beliefs.py`.
135
+
136
+ ## Run it for real
137
+
138
+ Two terminals.
139
+
140
+ Terminal 1 is your simulator bridge:
141
+
142
+ ```bash
143
+ dynos login # logins persist across terminals but expire after an hour
144
+ dynos session create --robot sentry-mock
145
+ dynos connect dynos_sim_bridge.runnable:SimBridgeNode
146
+ ```
147
+
148
+ Leave it running. It executes `goto` whenever the backend reaches a leg, and
149
+ answers the `at` belief whenever the backend polls it.
150
+
151
+ Terminal 2 is the mission. Create the survey zone and run:
152
+
153
+ ```bash
154
+ dynos call create zone.json
155
+ ```
156
+
157
+ ```python
158
+ from dynos_client import RemoteOrchestrator
159
+ from dynos_sim_bridge.mission import build_sim_survey_mission
160
+
161
+ orch = RemoteOrchestrator.from_config(timeout_s=3600)
162
+ for r in orch.execute_blocks(build_sim_survey_mission("site_alpha")):
163
+ print(r)
164
+ ```
165
+
166
+ ## Public API
167
+
168
+ | Symbol | From | Purpose |
169
+ |-----------------------------------|-----------------------------|------------------------------------------------------|
170
+ | `SimHardware` | `dynos_sim_bridge.bridge` | The robot class you edit; executes `goto`, observes `at`. |
171
+ | `StochasticSim` | `dynos_sim_bridge.bridge` | The trivial stand-in simulator you replace. |
172
+ | `SimBridgeNode` | `dynos_sim_bridge.runnable` | The `dynos connect` entry point. |
173
+ | `build_sim_survey_mission(zone)` | `dynos_sim_bridge.mission` | Take over, survey, recover. |
174
+
175
+ ## Troubleshooting
176
+
177
+ Bridge never gets an assignment: the mission hasn't reached a `goto` leg. Check
178
+ `dynos call state --scope public`.
179
+
180
+ `at(<name>)` unresolved: the name your `position()` returned isn't a registered
181
+ object. Return the name of a waypoint the planner knows (e.g. the leg's
182
+ endpoint), not an ad-hoc string.
183
+
184
+ For cross-package issues (login, session, connection), see `user_guide.md` or
185
+ `dynos-client`'s README.
@@ -0,0 +1,21 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "dynos-sim-bridge"
7
+ version = "0.1.5"
8
+ requires-python = ">=3.8"
9
+ description = "Run the DYNOS planner in the loop with an external vehicle simulator"
10
+ readme = "README.md"
11
+ license = { text = "Apache-2.0" }
12
+ dependencies = [
13
+ "dynos-client>=0.1.5", # stay locked but assume backwards-compatible
14
+ "dynos-sentry-domain==0.1.5", # stay locked to the domain version
15
+ ]
16
+
17
+ [project.optional-dependencies]
18
+ dev = ["pytest"]
19
+
20
+ [tool.setuptools.packages.find]
21
+ where = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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,12 @@
1
+ README.md
2
+ pyproject.toml
3
+ src/dynos_sim_bridge/__init__.py
4
+ src/dynos_sim_bridge/bridge.py
5
+ src/dynos_sim_bridge/mission.py
6
+ src/dynos_sim_bridge/runnable.py
7
+ src/dynos_sim_bridge.egg-info/PKG-INFO
8
+ src/dynos_sim_bridge.egg-info/SOURCES.txt
9
+ src/dynos_sim_bridge.egg-info/dependency_links.txt
10
+ src/dynos_sim_bridge.egg-info/requires.txt
11
+ src/dynos_sim_bridge.egg-info/top_level.txt
12
+ tests/test_bridge.py
@@ -0,0 +1,5 @@
1
+ dynos-client>=0.1.5
2
+ dynos-sentry-domain==0.1.5
3
+
4
+ [dev]
5
+ pytest
@@ -0,0 +1 @@
1
+ dynos_sim_bridge
@@ -0,0 +1,93 @@
1
+ """Offline tests for the simulator bridge. No network or session needed.
2
+
3
+ Exercise the trivial stochastic simulator, the ``goto`` action plumbing, and
4
+ the ``at`` servant belief. The end-to-end loop (backend polls the belief after
5
+ a step and continues or replans) is covered by the sentry integration test
6
+ ``tests/sentry/test_servant_beliefs.py``.
7
+ """
8
+
9
+ import random
10
+
11
+ from dynos_sentry.sentry import Coordinate, CoordinateGotoParams
12
+
13
+ from dynos_sim_bridge.bridge import SimHardware, StochasticSim
14
+
15
+
16
+ def _params():
17
+ """A goto leg between two waypoints. A bare Coordinate str()s to the type
18
+ name; the real backend passes registered objects whose str() is their
19
+ name, which is what ``go_to`` forwards to the simulator."""
20
+ start = Coordinate(name="wp_start", latitude=41.60, longitude=-70.60,
21
+ coordinate_frame="geographic")
22
+ end = Coordinate(name="wp_x", latitude=41.70, longitude=-70.50,
23
+ coordinate_frame="geographic")
24
+ return CoordinateGotoParams(start=start, end=end)
25
+
26
+
27
+ class _RecordingSim:
28
+ """Records the last commanded target; arrival outcome is fixed at
29
+ construction so ``go_to``'s plumbing can be checked deterministically."""
30
+
31
+ def __init__(self, arrive: bool):
32
+ self.commanded = None
33
+ self._arrive = arrive
34
+ self._pos = "start"
35
+
36
+ def goto(self, target):
37
+ self.commanded = target
38
+ if self._arrive:
39
+ self._pos = target
40
+ return self._arrive
41
+
42
+ def position(self):
43
+ return self._pos
44
+
45
+
46
+ def test_sim_arrives_with_certainty():
47
+ sim = StochasticSim(start="wp_start", p_success=1.0)
48
+ assert sim.goto("wp_x") is True
49
+ assert sim.position() == "wp_x"
50
+
51
+
52
+ def test_sim_miss_leaves_vehicle_where_it_was():
53
+ sim = StochasticSim(start="wp_start", p_success=0.0)
54
+ assert sim.goto("wp_x") is False
55
+ assert sim.position() == "wp_start" # unchanged: the move missed
56
+
57
+
58
+ def test_sim_outcome_is_seeded_and_reproducible():
59
+ # A fixed RNG at p=0.5 produces a mix of hits and misses, deterministically.
60
+ sim = StochasticSim(start=None, p_success=0.5, rng=random.Random(0))
61
+ outcomes = [sim.goto(f"wp_{i}") for i in range(20)]
62
+ assert any(outcomes) and not all(outcomes)
63
+
64
+
65
+ def test_go_to_forwards_endpoint_and_reports_arrival():
66
+ sim = _RecordingSim(arrive=True)
67
+ hw = SimHardware(sim=sim)
68
+ result = SimHardware.go_to.func(hw, _params(), None)
69
+ assert sim.commanded == str(_params().end) # endpoint identifier forwarded
70
+ assert result["success"] is True
71
+ assert result["telemetry"]["arrived"] is True
72
+
73
+
74
+ def test_go_to_miss_reports_failure():
75
+ sim = _RecordingSim(arrive=False)
76
+ hw = SimHardware(sim=sim)
77
+ result = SimHardware.go_to.func(hw, _params(), None)
78
+ assert result["success"] is False
79
+ assert result["telemetry"]["arrived"] is False
80
+
81
+
82
+ def test_observe_position_reports_at_symbol():
83
+ hw = SimHardware(sim=StochasticSim(start="wp_x", p_success=1.0))
84
+ result = hw.observe_position(None)
85
+ assert result.success and not result.is_unchecked
86
+ # The belief carries the fluent SYMBOL at(wp_x); str() only for comparison.
87
+ assert [str(a) for a in result.observed_state] == ["at(wp_x)"]
88
+
89
+
90
+ def test_observe_position_unchecked_between_waypoints():
91
+ hw = SimHardware(sim=StochasticSim(start=None, p_success=1.0))
92
+ result = hw.observe_position(None)
93
+ assert result.is_unchecked # no symbolic fix when on no named waypoint