medre-adapter-meshtastic 0.1.0__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.
Files changed (113) hide show
  1. medre_adapter_meshtastic-0.1.0/LICENSE +21 -0
  2. medre_adapter_meshtastic-0.1.0/MANIFEST.in +1 -0
  3. medre_adapter_meshtastic-0.1.0/PKG-INFO +231 -0
  4. medre_adapter_meshtastic-0.1.0/README.md +211 -0
  5. medre_adapter_meshtastic-0.1.0/docs/schemas/README.md +41 -0
  6. medre_adapter_meshtastic-0.1.0/docs/schemas/examples/meshtastic-native-metadata-example.json +36 -0
  7. medre_adapter_meshtastic-0.1.0/docs/schemas/meshtastic-native-metadata.schema.json +246 -0
  8. medre_adapter_meshtastic-0.1.0/docs/schemas/v0.1.0.freeze.json +7 -0
  9. medre_adapter_meshtastic-0.1.0/pyproject.toml +84 -0
  10. medre_adapter_meshtastic-0.1.0/setup.cfg +4 -0
  11. medre_adapter_meshtastic-0.1.0/setup.py +75 -0
  12. medre_adapter_meshtastic-0.1.0/src/medre/adapters/fakes/meshtastic.py +561 -0
  13. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/__init__.py +12 -0
  14. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/adapter.py +2041 -0
  15. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/attribution.py +67 -0
  16. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/codec.py +282 -0
  17. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/compat.py +75 -0
  18. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/errors.py +50 -0
  19. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/event_shape.py +111 -0
  20. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/guarded.py +71 -0
  21. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/packet_classifier.py +668 -0
  22. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/packet_snapshot.py +68 -0
  23. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/plugin.py +87 -0
  24. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/py.typed +0 -0
  25. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/queue.py +990 -0
  26. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/renderer.py +594 -0
  27. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/routing_observations.py +234 -0
  28. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/sample.py +11 -0
  29. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/send_correlation.py +369 -0
  30. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/session.py +1695 -0
  31. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/startup_backlog.py +77 -0
  32. medre_adapter_meshtastic-0.1.0/src/medre/adapters/meshtastic/stopped_declaration.py +69 -0
  33. medre_adapter_meshtastic-0.1.0/src/medre/config/adapters/meshtastic.py +401 -0
  34. medre_adapter_meshtastic-0.1.0/src/medre/config/adapters/meshtastic_errors.py +7 -0
  35. medre_adapter_meshtastic-0.1.0/src/medre/config/adapters/meshtastic_runtime.py +20 -0
  36. medre_adapter_meshtastic-0.1.0/src/medre_adapter_meshtastic.egg-info/PKG-INFO +231 -0
  37. medre_adapter_meshtastic-0.1.0/src/medre_adapter_meshtastic.egg-info/SOURCES.txt +111 -0
  38. medre_adapter_meshtastic-0.1.0/src/medre_adapter_meshtastic.egg-info/dependency_links.txt +1 -0
  39. medre_adapter_meshtastic-0.1.0/src/medre_adapter_meshtastic.egg-info/entry_points.txt +2 -0
  40. medre_adapter_meshtastic-0.1.0/src/medre_adapter_meshtastic.egg-info/requires.txt +10 -0
  41. medre_adapter_meshtastic-0.1.0/src/medre_adapter_meshtastic.egg-info/top_level.txt +1 -0
  42. medre_adapter_meshtastic-0.1.0/tests/test_discovery_meshtastic.py +19 -0
  43. medre_adapter_meshtastic-0.1.0/tests/test_distribution_license.py +29 -0
  44. medre_adapter_meshtastic-0.1.0/tests/test_guarded_multipart.py +673 -0
  45. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_adapter.py +1186 -0
  46. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_adapter_coverage.py +268 -0
  47. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_adapter_delivery.py +1264 -0
  48. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_adapter_delivery_extra.py +425 -0
  49. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_adapter_startup.py +311 -0
  50. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_attribution.py +314 -0
  51. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_behavior_reference.py +337 -0
  52. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_boundaries.py +767 -0
  53. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_classifier_metadata.py +1295 -0
  54. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_codec.py +583 -0
  55. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_config.py +603 -0
  56. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_cross_radio_reactions.py +264 -0
  57. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_default_prefix.py +96 -0
  58. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_delayed_outbound_ref.py +186 -0
  59. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_env_first.py +275 -0
  60. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_evidence_diagnostics.py +377 -0
  61. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_fake_adapter.py +505 -0
  62. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_fake_bridge.py +1035 -0
  63. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_fake_bridge_errors.py +373 -0
  64. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_fake_bridge_session.py +289 -0
  65. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_fallback_text.py +322 -0
  66. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_hardware_soak.py +90 -0
  67. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_identity_enrichment.py +541 -0
  68. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_ingress_pressure.py +824 -0
  69. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_live.py +1005 -0
  70. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_native_health.py +168 -0
  71. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_nosdk.py +832 -0
  72. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_outbound_gate.py +636 -0
  73. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_outbound_ref.py +1087 -0
  74. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_packet_classifier.py +647 -0
  75. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_packet_snapshot.py +204 -0
  76. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_pair_live.py +403 -0
  77. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_pipeline.py +802 -0
  78. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_process_lifetime_ingress.py +475 -0
  79. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_public_facts.py +136 -0
  80. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_queue_evidence.py +527 -0
  81. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_queue_pressure.py +127 -0
  82. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_queue_retry.py +822 -0
  83. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_reaction_prefix_parity.py +194 -0
  84. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_reaction_preview.py +392 -0
  85. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_relay_prefix_truncation.py +188 -0
  86. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_renderer.py +822 -0
  87. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_renderer_channel_default.py +271 -0
  88. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_routing_observations.py +233 -0
  89. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_run_session.py +199 -0
  90. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_runtime_resilience.py +834 -0
  91. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_sdk_contract.py +174 -0
  92. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_send_correlation.py +597 -0
  93. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_session_coverage.py +1101 -0
  94. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_shared_policy_boundaries.py +224 -0
  95. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_shutdown_callbacks.py +1127 -0
  96. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_startup_backlog.py +732 -0
  97. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_startup_backlog_extract.py +154 -0
  98. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_storage_roundtrip.py +366 -0
  99. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_sustained_ingress.py +732 -0
  100. medre_adapter_meshtastic-0.1.0/tests/test_meshtastic_target_selection_rules.py +344 -0
  101. medre_adapter_meshtastic-0.1.0/tests/test_native_metadata_schema_constraints.py +31 -0
  102. medre_adapter_meshtastic-0.1.0/tests/test_native_setup.py +75 -0
  103. medre_adapter_meshtastic-0.1.0/tests/test_offline_sample.py +31 -0
  104. medre_adapter_meshtastic-0.1.0/tests/test_offline_startup.py +483 -0
  105. medre_adapter_meshtastic-0.1.0/tests/test_pin_literal_hygiene.py +124 -0
  106. medre_adapter_meshtastic-0.1.0/tests/test_plugin_api_version.py +10 -0
  107. medre_adapter_meshtastic-0.1.0/tests/test_provider_contract.py +53 -0
  108. medre_adapter_meshtastic-0.1.0/tests/test_queued_text_validation.py +29 -0
  109. medre_adapter_meshtastic-0.1.0/tests/test_recovery_cadence.py +56 -0
  110. medre_adapter_meshtastic-0.1.0/tests/test_schema_freeze_010.py +86 -0
  111. medre_adapter_meshtastic-0.1.0/tests/test_schema_wheel_resources.py +151 -0
  112. medre_adapter_meshtastic-0.1.0/tests/test_sdk_cancellation.py +116 -0
  113. medre_adapter_meshtastic-0.1.0/tests/test_stopped_declaration.py +103 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jeremiah K.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ recursive-include docs/schemas *
@@ -0,0 +1,231 @@
1
+ Metadata-Version: 2.4
2
+ Name: medre-adapter-meshtastic
3
+ Version: 0.1.0
4
+ Summary: meshtastic transport adapter for MEDRE
5
+ License-Expression: MIT
6
+ Classifier: Typing :: Typed
7
+ Requires-Python: >=3.11
8
+ Description-Content-Type: text/markdown
9
+ License-File: LICENSE
10
+ Requires-Dist: medre<0.2.0,>=0.1.0
11
+ Requires-Dist: mtjk==2.7.11.post14
12
+ Requires-Dist: PyPubSub==4.0.7
13
+ Provides-Extra: test
14
+ Requires-Dist: pytest==9.2.0; extra == "test"
15
+ Requires-Dist: pytest-asyncio==1.5.0; extra == "test"
16
+ Requires-Dist: pytest-timeout==2.4.0; extra == "test"
17
+ Requires-Dist: jsonschema==4.26.0; extra == "test"
18
+ Requires-Dist: packaging==26.3; extra == "test"
19
+ Dynamic: license-file
20
+
21
+ # medre-adapter-meshtastic
22
+
23
+ **Meshtastic provider for MEDRE.** This separately installed distribution owns its
24
+ transport SDK, configuration, native codec and offline fake. MEDRE core owns
25
+ routing, storage, lifecycle and delivery evidence.
26
+
27
+ ## Install from Git
28
+
29
+ Use [uv](https://docs.astral.sh/uv/getting-started/installation/) and Git. For
30
+ a first trial, MEDRE can manage this provider in its persistent tool environment:
31
+
32
+ ```bash
33
+ uv tool install 'git+https://github.com/jeremiah-k/medre.git@main'
34
+ medre adapters install meshtastic
35
+ medre adapters
36
+ ```
37
+
38
+ On Windows, the package-changing command prints a uv command to run **after**
39
+ `medre.exe` exits, rather than replacing an executable still in use.
40
+ The `main` branch is useful for trials; pin exact core and adapter commits for
41
+ repeatable operation. Use the [MEDRE Getting Started guide](https://github.com/jeremiah-k/medre/blob/main/docs/ops/getting-started.md)
42
+ for fake smoke, guided route creation and native setup. Use the
43
+ [adapter-source guide](https://github.com/jeremiah-k/medre/blob/main/docs/ops/adapter-installation.md)
44
+ for a locked uv deployment project, private Git, local checkouts, index sources,
45
+ and the same-environment requirement. Neither MEDRE nor the provider installs
46
+ packages during runtime startup.
47
+
48
+ ## Packaging and provenance
49
+
50
+ This distribution registers the `medre.adapters` entry point and retains the
51
+ import namespace `medre.adapters.meshtastic`. Its original adapter source history
52
+ was extracted from MEDRE commit `e59c29dd31a95860d1cdbc19e531896616627a68`;
53
+ Git author and committer identities remain preserved. Runtime configuration and
54
+ adapter discovery do not depend on this repository's distribution name.
55
+
56
+ ## Ownership and imports
57
+
58
+ This distribution owns Meshtastic's transport implementation, configuration models,
59
+ runtime wrapper, fake adapter, native addressing behavior, SDK requirements,
60
+ and protocol/SDK tests. MEDRE core owns generic events, routing, lifecycle,
61
+ storage, evidence, configuration orchestration, and installed-package discovery.
62
+
63
+ | Surface | Adapter-owned import |
64
+ | --------------- | ------------------------------------------------------------------ |
65
+ | Config models | `medre.config.adapters.meshtastic` |
66
+ | Runtime wrapper | `medre.config.adapters.meshtastic_runtime.MeshtasticRuntimeConfig` |
67
+ | SDK-free fake | `medre.adapters.fakes.meshtastic.FakeMeshtasticAdapter` |
68
+
69
+ Import the runtime wrapper from this distribution directly. Core has no named
70
+ wrapper compatibility bridge or transport SDK extras. The supported MEDRE
71
+ interface range and native SDK pins are declared in this project's
72
+ `pyproject.toml`; use a matching core revision during pre-release development.
73
+ Community adapter authors can use their own distribution names, import packages,
74
+ and hosting sources with the same `medre.adapters` entry-point contract.
75
+
76
+ MEDRE-authored adapter source is [MIT-licensed](LICENSE). This grant does
77
+ not relicense installed dependencies. Their license terms still apply to any
78
+ combined deployment or redistribution. See [dependency license notes](DEPENDENCY_LICENSES.md).
79
+
80
+ ## Offline samples and diagnostics
81
+
82
+ This distribution contributes native fake values and an opaque conversation
83
+ address to `medre config sample`. Core includes only installed contributors;
84
+ a single contributor gets two fake instances for offline routing. Native
85
+ packet simulation methods remain adapter-specific. Run-session canonical
86
+ callback injection uses `AdapterContract.publish_inbound(event)`.
87
+
88
+ `medre adapters check --config bridge.yaml` distinguishes missing distributions
89
+ from broken/conflicting entry points. Basic CLI help and unrelated healthy
90
+ providers remain available when another provider fails discovery.
91
+
92
+ ## Tests
93
+
94
+ Protocol and SDK contract tests live in this repository with adapter-owned
95
+ helpers. Cross-adapter routing and lifecycle tests remain in MEDRE. Run the
96
+ following from this repository in a fresh virtual environment, with a matching
97
+ MEDRE checkout at any location. Set `MEDRE_CORE` to that checkout path.
98
+
99
+ ```bash
100
+ # SDK-free fake tier: core dev supplies test tooling; skip this adapter's SDK deps.
101
+ python -m pip install -e "${MEDRE_CORE:?Set MEDRE_CORE to the core checkout}[dev]"
102
+ python -m pip install --no-deps -e .
103
+ python -m pytest -q
104
+
105
+ # Native SDK tier: this distribution supplies its own SDK pins.
106
+ python -m pip install -e '.[test]'
107
+ python -m pytest -v -m "meshtastic_sdk and not local_integration and not soak and not live and not hardware and not docker"
108
+ ```
109
+
110
+ The default pytest selection excludes SDK, service, hardware, local integration,
111
+ and soak tiers. Installing SDKs afterward leaves the same environment SDK-enabled;
112
+ use a fresh environment for a new SDK-free proof.
113
+
114
+ ## Fake smoke sources
115
+
116
+ The fake provides a synchronous `make_event(text=..., event_kind=...)` returning
117
+ a canonical event with its own adapter instance ID. After installing all
118
+ providers referenced by a fake bridge config, exercise a source with:
119
+
120
+ ```bash
121
+ medre smoke --config bridge.yaml --source-adapter ADAPTER_ID --json
122
+ ```
123
+
124
+ Use the configured instance ID, which may differ from the transport name. Each
125
+ normal smoke tests one source; inspect `source_candidates` and
126
+ `coverage_scope: single_source` in its report. Eligible sources must have started
127
+ and provide the helper. A pass requires delivery for every matched configured
128
+ route target, including targets unavailable after construction or startup.
129
+ Factory errors fail the smoke and trigger runtime cleanup. The result proves
130
+ fake direct-pipeline behavior; native callbacks and recipient delivery have
131
+ separate qualification tiers.
132
+
133
+ ## Coordinated CI
134
+
135
+ The repository CI installs MEDRE core and this adapter. Its fake job omits
136
+ native SDK dependencies; its SDK job installs this distribution's declared pins.
137
+ CI resolves MEDRE `main` once per run by default. Keep the repository Actions variable
138
+ `MEDRE_CORE_REF` unset so pull-request checks retain that baseline. Qualify a
139
+ candidate pair with a one-run dispatch and a full core commit SHA:
140
+
141
+ ```bash
142
+ gh workflow run test.yml --ref ADAPTER_BRANCH -f core_ref=FULL_CORE_COMMIT_SHA
143
+ ```
144
+
145
+ Record both revisions with the result. The candidate run does not replace the
146
+ adapter PR's checks against core `main`. Follow the
147
+ [coordinated-change policy](https://github.com/jeremiah-k/medre/blob/main/docs/dev/coordinated-changes.md)
148
+ for dependency order and merged compatibility pins.
149
+
150
+ Core's compatibility matrix tests each selected adapter at the exact commit
151
+ recorded in its manifest, along with cross-adapter behavior. In a coordinated
152
+ checkout containing the selected sibling repos, run from MEDRE:
153
+
154
+ ```bash
155
+ python scripts/ci/adapter_matrix.py --check-local
156
+ # Once all adapter changes are committed:
157
+ python scripts/ci/adapter_matrix.py --sync-local
158
+ ```
159
+
160
+ The helper validates clean sibling checkouts and their entry points, and compares
161
+ Python distribution names using normalized case/separator spelling. Synchronizing
162
+ updates the manifest atomically without fetching or installing packages. Review
163
+ the manifest diff, merge adapter commits into their default branches first, then publish
164
+ the core pin update and run `python scripts/ci/adapter_matrix.py --check-merged`. A failed write preserves the original manifest and cleans up the temporary
165
+ file. Deployment projects should separately lock their chosen complete
166
+ package graph.
167
+
168
+ Standalone CI records the exact core and adapter SHAs tested against its
169
+ configured core baseline. MEDRE core CI qualifies the pinned compatibility
170
+ pair; a standalone green result does not qualify another core revision.
171
+ SDK qualification extras come from the selected core compatibility manifest,
172
+ while SDK versions remain authoritative in this adapter's package metadata.
173
+
174
+ ## Provider contract and quality
175
+
176
+ The [registration reference](https://github.com/jeremiah-k/medre/blob/main/docs/dev/adapter-registration.md)
177
+ documents every hook, its loading phase, and the minimal fake constructor/event
178
+ calls. Shared native-metadata helpers are public under `medre.adapters.metadata`.
179
+ Conformance tests use `medre.testing`; SDK pin checks read this distribution's
180
+ installed metadata while this repository chooses its SDK qualification extras.
181
+ The fake constructor and explicit-keyword event factory are checked in the
182
+ SDK-free tier. Native schemas and validated examples live in `docs/schemas` here.
183
+
184
+ This repository declares its own Ruff/Black policy. CI checks all Python source
185
+ and tests, plus commit whitespace, alongside the fake/native qualification tiers.
186
+ The native adapter package includes its own `py.typed` marker.
187
+
188
+ ## Outbound pacing
189
+
190
+ The default message_delay_seconds is 2.2 seconds, leaving a margin above
191
+ current firmware's two-second phone-originated text limit. Shorter configured
192
+ intervals can cause RATE_LIMIT_EXCEEDED even when the SDK returns a packet ID.
193
+ Use a lower interval only with separately qualified firmware. A local transport
194
+ handoff is not proof of RF reception; verify delivery on an independent node.
195
+ The firmware rule is implemented in
196
+ [PhoneAPI.cpp](https://github.com/meshtastic/firmware/blob/master/src/mesh/PhoneAPI.cpp).
197
+
198
+ ## Default relay attribution
199
+
200
+ Matrix messages sent to Meshtastic default to `Alice[M]: message`, using the
201
+ first five display-name characters. The prefix shares the 227-byte UTF-8 budget
202
+ with the body. Other source platforms retain generic short-name attribution.
203
+ Set `relay_prefix: ""` to disable it or supply a custom generic template;
204
+ omitted/null selects the source-aware default.
205
+
206
+ Templates use generic variables such as `{sender}` and `{sender_short}`.
207
+ Because radio displays are constrained, the label variables `sender`,
208
+ `sender_short`, and `origin_label` also accept truncation suffixes:
209
+ `{sender3}` renders the first three Unicode code points of the sender
210
+ label (N must be at least 1). A numeric suffix on any other variable
211
+ passes through unchanged.
212
+
213
+ ## Offline startup and recovery
214
+
215
+ An offline radio no longer holds up the runtime for the SDK's multi-minute
216
+ connection defaults. The existing sync_timeout_ms setting defaults to 30000:
217
+ MEDRE waits up to 30 seconds for that instance's initial connection, then starts
218
+ it degraded and proceeds with the remaining adapters. Each offline instance has
219
+ its own budget; startup still visits adapter instances in order.
220
+
221
+ Routes involving a started, degraded radio remain available. Recovery retains
222
+ one connection attempt at a time and retries with capped backoff until the radio
223
+ returns or MEDRE stops. Use `medre diagnostics --refresh-health` to inspect the
224
+ live connection state. A connection returning after shutdown is closed.
225
+
226
+ Set sync_timeout_ms on the Meshtastic instance to change the initial wait and
227
+ native SDK phase limits. It must be a positive integer in milliseconds. Invalid
228
+ configuration and missing dependencies still fail startup. The async deadline
229
+ does not forcibly terminate a blocking SDK thread; see the
230
+ [connection lifecycle contract](docs/spec/connection-lifecycle.md) for ownership
231
+ and shutdown limits. Native handoff still requires independent RF qualification.
@@ -0,0 +1,211 @@
1
+ # medre-adapter-meshtastic
2
+
3
+ **Meshtastic provider for MEDRE.** This separately installed distribution owns its
4
+ transport SDK, configuration, native codec and offline fake. MEDRE core owns
5
+ routing, storage, lifecycle and delivery evidence.
6
+
7
+ ## Install from Git
8
+
9
+ Use [uv](https://docs.astral.sh/uv/getting-started/installation/) and Git. For
10
+ a first trial, MEDRE can manage this provider in its persistent tool environment:
11
+
12
+ ```bash
13
+ uv tool install 'git+https://github.com/jeremiah-k/medre.git@main'
14
+ medre adapters install meshtastic
15
+ medre adapters
16
+ ```
17
+
18
+ On Windows, the package-changing command prints a uv command to run **after**
19
+ `medre.exe` exits, rather than replacing an executable still in use.
20
+ The `main` branch is useful for trials; pin exact core and adapter commits for
21
+ repeatable operation. Use the [MEDRE Getting Started guide](https://github.com/jeremiah-k/medre/blob/main/docs/ops/getting-started.md)
22
+ for fake smoke, guided route creation and native setup. Use the
23
+ [adapter-source guide](https://github.com/jeremiah-k/medre/blob/main/docs/ops/adapter-installation.md)
24
+ for a locked uv deployment project, private Git, local checkouts, index sources,
25
+ and the same-environment requirement. Neither MEDRE nor the provider installs
26
+ packages during runtime startup.
27
+
28
+ ## Packaging and provenance
29
+
30
+ This distribution registers the `medre.adapters` entry point and retains the
31
+ import namespace `medre.adapters.meshtastic`. Its original adapter source history
32
+ was extracted from MEDRE commit `e59c29dd31a95860d1cdbc19e531896616627a68`;
33
+ Git author and committer identities remain preserved. Runtime configuration and
34
+ adapter discovery do not depend on this repository's distribution name.
35
+
36
+ ## Ownership and imports
37
+
38
+ This distribution owns Meshtastic's transport implementation, configuration models,
39
+ runtime wrapper, fake adapter, native addressing behavior, SDK requirements,
40
+ and protocol/SDK tests. MEDRE core owns generic events, routing, lifecycle,
41
+ storage, evidence, configuration orchestration, and installed-package discovery.
42
+
43
+ | Surface | Adapter-owned import |
44
+ | --------------- | ------------------------------------------------------------------ |
45
+ | Config models | `medre.config.adapters.meshtastic` |
46
+ | Runtime wrapper | `medre.config.adapters.meshtastic_runtime.MeshtasticRuntimeConfig` |
47
+ | SDK-free fake | `medre.adapters.fakes.meshtastic.FakeMeshtasticAdapter` |
48
+
49
+ Import the runtime wrapper from this distribution directly. Core has no named
50
+ wrapper compatibility bridge or transport SDK extras. The supported MEDRE
51
+ interface range and native SDK pins are declared in this project's
52
+ `pyproject.toml`; use a matching core revision during pre-release development.
53
+ Community adapter authors can use their own distribution names, import packages,
54
+ and hosting sources with the same `medre.adapters` entry-point contract.
55
+
56
+ MEDRE-authored adapter source is [MIT-licensed](LICENSE). This grant does
57
+ not relicense installed dependencies. Their license terms still apply to any
58
+ combined deployment or redistribution. See [dependency license notes](DEPENDENCY_LICENSES.md).
59
+
60
+ ## Offline samples and diagnostics
61
+
62
+ This distribution contributes native fake values and an opaque conversation
63
+ address to `medre config sample`. Core includes only installed contributors;
64
+ a single contributor gets two fake instances for offline routing. Native
65
+ packet simulation methods remain adapter-specific. Run-session canonical
66
+ callback injection uses `AdapterContract.publish_inbound(event)`.
67
+
68
+ `medre adapters check --config bridge.yaml` distinguishes missing distributions
69
+ from broken/conflicting entry points. Basic CLI help and unrelated healthy
70
+ providers remain available when another provider fails discovery.
71
+
72
+ ## Tests
73
+
74
+ Protocol and SDK contract tests live in this repository with adapter-owned
75
+ helpers. Cross-adapter routing and lifecycle tests remain in MEDRE. Run the
76
+ following from this repository in a fresh virtual environment, with a matching
77
+ MEDRE checkout at any location. Set `MEDRE_CORE` to that checkout path.
78
+
79
+ ```bash
80
+ # SDK-free fake tier: core dev supplies test tooling; skip this adapter's SDK deps.
81
+ python -m pip install -e "${MEDRE_CORE:?Set MEDRE_CORE to the core checkout}[dev]"
82
+ python -m pip install --no-deps -e .
83
+ python -m pytest -q
84
+
85
+ # Native SDK tier: this distribution supplies its own SDK pins.
86
+ python -m pip install -e '.[test]'
87
+ python -m pytest -v -m "meshtastic_sdk and not local_integration and not soak and not live and not hardware and not docker"
88
+ ```
89
+
90
+ The default pytest selection excludes SDK, service, hardware, local integration,
91
+ and soak tiers. Installing SDKs afterward leaves the same environment SDK-enabled;
92
+ use a fresh environment for a new SDK-free proof.
93
+
94
+ ## Fake smoke sources
95
+
96
+ The fake provides a synchronous `make_event(text=..., event_kind=...)` returning
97
+ a canonical event with its own adapter instance ID. After installing all
98
+ providers referenced by a fake bridge config, exercise a source with:
99
+
100
+ ```bash
101
+ medre smoke --config bridge.yaml --source-adapter ADAPTER_ID --json
102
+ ```
103
+
104
+ Use the configured instance ID, which may differ from the transport name. Each
105
+ normal smoke tests one source; inspect `source_candidates` and
106
+ `coverage_scope: single_source` in its report. Eligible sources must have started
107
+ and provide the helper. A pass requires delivery for every matched configured
108
+ route target, including targets unavailable after construction or startup.
109
+ Factory errors fail the smoke and trigger runtime cleanup. The result proves
110
+ fake direct-pipeline behavior; native callbacks and recipient delivery have
111
+ separate qualification tiers.
112
+
113
+ ## Coordinated CI
114
+
115
+ The repository CI installs MEDRE core and this adapter. Its fake job omits
116
+ native SDK dependencies; its SDK job installs this distribution's declared pins.
117
+ CI resolves MEDRE `main` once per run by default. Keep the repository Actions variable
118
+ `MEDRE_CORE_REF` unset so pull-request checks retain that baseline. Qualify a
119
+ candidate pair with a one-run dispatch and a full core commit SHA:
120
+
121
+ ```bash
122
+ gh workflow run test.yml --ref ADAPTER_BRANCH -f core_ref=FULL_CORE_COMMIT_SHA
123
+ ```
124
+
125
+ Record both revisions with the result. The candidate run does not replace the
126
+ adapter PR's checks against core `main`. Follow the
127
+ [coordinated-change policy](https://github.com/jeremiah-k/medre/blob/main/docs/dev/coordinated-changes.md)
128
+ for dependency order and merged compatibility pins.
129
+
130
+ Core's compatibility matrix tests each selected adapter at the exact commit
131
+ recorded in its manifest, along with cross-adapter behavior. In a coordinated
132
+ checkout containing the selected sibling repos, run from MEDRE:
133
+
134
+ ```bash
135
+ python scripts/ci/adapter_matrix.py --check-local
136
+ # Once all adapter changes are committed:
137
+ python scripts/ci/adapter_matrix.py --sync-local
138
+ ```
139
+
140
+ The helper validates clean sibling checkouts and their entry points, and compares
141
+ Python distribution names using normalized case/separator spelling. Synchronizing
142
+ updates the manifest atomically without fetching or installing packages. Review
143
+ the manifest diff, merge adapter commits into their default branches first, then publish
144
+ the core pin update and run `python scripts/ci/adapter_matrix.py --check-merged`. A failed write preserves the original manifest and cleans up the temporary
145
+ file. Deployment projects should separately lock their chosen complete
146
+ package graph.
147
+
148
+ Standalone CI records the exact core and adapter SHAs tested against its
149
+ configured core baseline. MEDRE core CI qualifies the pinned compatibility
150
+ pair; a standalone green result does not qualify another core revision.
151
+ SDK qualification extras come from the selected core compatibility manifest,
152
+ while SDK versions remain authoritative in this adapter's package metadata.
153
+
154
+ ## Provider contract and quality
155
+
156
+ The [registration reference](https://github.com/jeremiah-k/medre/blob/main/docs/dev/adapter-registration.md)
157
+ documents every hook, its loading phase, and the minimal fake constructor/event
158
+ calls. Shared native-metadata helpers are public under `medre.adapters.metadata`.
159
+ Conformance tests use `medre.testing`; SDK pin checks read this distribution's
160
+ installed metadata while this repository chooses its SDK qualification extras.
161
+ The fake constructor and explicit-keyword event factory are checked in the
162
+ SDK-free tier. Native schemas and validated examples live in `docs/schemas` here.
163
+
164
+ This repository declares its own Ruff/Black policy. CI checks all Python source
165
+ and tests, plus commit whitespace, alongside the fake/native qualification tiers.
166
+ The native adapter package includes its own `py.typed` marker.
167
+
168
+ ## Outbound pacing
169
+
170
+ The default message_delay_seconds is 2.2 seconds, leaving a margin above
171
+ current firmware's two-second phone-originated text limit. Shorter configured
172
+ intervals can cause RATE_LIMIT_EXCEEDED even when the SDK returns a packet ID.
173
+ Use a lower interval only with separately qualified firmware. A local transport
174
+ handoff is not proof of RF reception; verify delivery on an independent node.
175
+ The firmware rule is implemented in
176
+ [PhoneAPI.cpp](https://github.com/meshtastic/firmware/blob/master/src/mesh/PhoneAPI.cpp).
177
+
178
+ ## Default relay attribution
179
+
180
+ Matrix messages sent to Meshtastic default to `Alice[M]: message`, using the
181
+ first five display-name characters. The prefix shares the 227-byte UTF-8 budget
182
+ with the body. Other source platforms retain generic short-name attribution.
183
+ Set `relay_prefix: ""` to disable it or supply a custom generic template;
184
+ omitted/null selects the source-aware default.
185
+
186
+ Templates use generic variables such as `{sender}` and `{sender_short}`.
187
+ Because radio displays are constrained, the label variables `sender`,
188
+ `sender_short`, and `origin_label` also accept truncation suffixes:
189
+ `{sender3}` renders the first three Unicode code points of the sender
190
+ label (N must be at least 1). A numeric suffix on any other variable
191
+ passes through unchanged.
192
+
193
+ ## Offline startup and recovery
194
+
195
+ An offline radio no longer holds up the runtime for the SDK's multi-minute
196
+ connection defaults. The existing sync_timeout_ms setting defaults to 30000:
197
+ MEDRE waits up to 30 seconds for that instance's initial connection, then starts
198
+ it degraded and proceeds with the remaining adapters. Each offline instance has
199
+ its own budget; startup still visits adapter instances in order.
200
+
201
+ Routes involving a started, degraded radio remain available. Recovery retains
202
+ one connection attempt at a time and retries with capped backoff until the radio
203
+ returns or MEDRE stops. Use `medre diagnostics --refresh-health` to inspect the
204
+ live connection state. A connection returning after shutdown is closed.
205
+
206
+ Set sync_timeout_ms on the Meshtastic instance to change the initial wait and
207
+ native SDK phase limits. It must be a positive integer in milliseconds. Invalid
208
+ configuration and missing dependencies still fail startup. The async deadline
209
+ does not forcibly terminate a blocking SDK thread; see the
210
+ [connection lifecycle contract](docs/spec/connection-lifecycle.md) for ownership
211
+ and shutdown limits. Native handoff still requires independent RF qualification.
@@ -0,0 +1,41 @@
1
+ # Meshtastic native contract freeze
2
+
3
+ Git attributes disable line-ending translation for this schema tree so frozen SHA-256
4
+ digests and installed wheel resources remain identical on Windows and Unix.
5
+
6
+ Source distributions include this directory. Wheels include the same schema
7
+ bundle, freeze manifest, and examples under `medre/adapters/meshtastic/_schemas`.
8
+ Installed consumers can read it with
9
+ `importlib.resources.files("medre.adapters.meshtastic").joinpath("_schemas")`.
10
+
11
+ The schema's `$id` uses this repository's `raw.githubusercontent.com` namespace,
12
+ matching core's identifier ownership policy. It replaces the earlier `medre.dev`
13
+ identifier before the first tag; editor mappings should use the included
14
+ schema's `$id`. The identifier does not require network retrieval.
15
+
16
+ `v0.1.0.freeze.json` records the pre-first-tag 0.1.0 schema baseline.
17
+ The compatibility tests reject unreviewed schema additions and edits; changes
18
+ after the first release require an explicit compatibility/version decision.
19
+ The schema is owned by the Meshtastic adapter, not MMRelay or MEDRE core.
20
+ This release guard does not require MMRelay to install the Meshtastic adapter.
21
+
22
+ A producer can explicitly publish the already-observed source portnum under
23
+ `meshtastic.public_facts.portnum`. MEDRE's transport-neutral bridge context
24
+ copies only this bounded, opted-in projection, not raw packets or keys. The
25
+ `MeshtasticSourceObservation` schema variant describes an embedding consumer
26
+ (such as MMRelay) that has native source identity, display labels and public
27
+ facts but does not instantiate the Meshtastic adapter or claim to have decoded
28
+ a full SDK packet. It is distinct from the complete native packet shape.
29
+
30
+ ## Public portnum facts
31
+
32
+ The source-owned `public_facts.portnum` MUST carry the numeric Meshtastic
33
+ protocol port number when known. Internal classifier labels MUST NOT become
34
+ public portnum values. Unknown or malformed values MUST NOT be guessed.
35
+
36
+ ## Git checkout line endings
37
+
38
+ A main-to-candidate Git checkout may retain unchanged CRLF files. Packaging
39
+ MUST emit the exact frozen bytes. LF reconstruction is permitted only when
40
+ its digest matches the freeze manifest; every other byte change MUST fail
41
+ the build. Fresh checkouts retain the explicit `-text` attribute policy.
@@ -0,0 +1,36 @@
1
+ {
2
+ "meshtastic": {
3
+ "schema_version": 1,
4
+ "packet_id": 123456,
5
+ "from_id": "!a1b2c3d4",
6
+ "channel": 0,
7
+ "portnum": "TEXT_MESSAGE_APP",
8
+ "to_id": "^all",
9
+ "is_direct_message": false,
10
+ "longname": "Field Node",
11
+ "shortname": "FN",
12
+ "reply_id": null,
13
+ "emoji": null,
14
+ "emoji_flag": null,
15
+ "packet": {
16
+ "id": 123456,
17
+ "fromId": "!a1b2c3d4"
18
+ },
19
+ "decoded": {
20
+ "text": "hello",
21
+ "portnum": "TEXT_MESSAGE_APP"
22
+ },
23
+ "classification": {
24
+ "action": "relay",
25
+ "category": "text",
26
+ "reason": "text_message",
27
+ "is_reply": false,
28
+ "is_reaction": false,
29
+ "emoji_flag": null,
30
+ "reaction_key": null,
31
+ "is_encrypted": false,
32
+ "is_detection_sensor": false,
33
+ "routeable": true
34
+ }
35
+ }
36
+ }