python-mobius 0.2.0__tar.gz → 0.3.0__tar.gz

python_mobius-0.3.0/.forgejo/scripts/extract_changelog_section.py

@@ -0,0 +1,42 @@
+"""
+Extracts the section of CHANGELOG.md under the heading matching a given
+version (e.g. version "0.3.0" -> the content under "## 0.3.0", up to the
+next "## " heading or end of file), and writes it to release_notes.md.
+
+Used by .forgejo/workflows/release.yml to source Forgejo release notes
+from CHANGELOG.md directly, rather than letting Forgejo auto-generate
+notes from commits. Takes the tag name (e.g. "v0.3.0") as its one
+argument and strips the leading "v" itself, since tags use that prefix
+but CHANGELOG.md's own headings don't.
+
+Exits with a clear error (nonzero exit code) if no matching section is
+found, rather than silently producing an empty or wrong release.
+"""
+
+import re
+import sys
+
+
+def main() -> None:
+    if len(sys.argv) != 2:
+        raise SystemExit(f"usage: {sys.argv[0]} <tag-name>")
+
+    version = sys.argv[1].lstrip("v")
+    text = open("CHANGELOG.md", encoding="utf-8").read()
+    pattern = re.compile(
+        r"^## " + re.escape(version) + r"\s*$\n(.*?)(?=^## |\Z)",
+        re.MULTILINE | re.DOTALL,
+    )
+    match = pattern.search(text)
+    if not match:
+        raise SystemExit(
+            f"No CHANGELOG.md section found for version {version!r} "
+            f"(looked for a line starting with '## {version}')"
+        )
+
+    with open("release_notes.md", "w", encoding="utf-8") as f:
+        f.write(match.group(1).strip() + "\n")
+
+
+if __name__ == "__main__":
+    main()

python_mobius-0.3.0/.forgejo/workflows/release.yml

@@ -0,0 +1,110 @@
+name: Release
+
+# Triggers on any tag matching v* (e.g. v0.3.0) -- confirmed to match every
+# tag this project has used so far -- or manually via workflow_dispatch
+# (Forgejo's web UI / API "Run workflow" button) for testing/debugging the
+# workflow itself. Does NOT trigger on regular pushes.
+# "on" is quoted deliberately -- unquoted, some YAML parsers (YAML 1.1)
+# interpret the bare word as the boolean `true` instead of the literal
+# key GitHub/Forgejo Actions expects.
+"on":
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch: {}
+
+jobs:
+  release:
+    # ubuntu-22.04 label -> catthehacker/ubuntu:act-22.04, the only one of
+    # this runner's three labels with a full, GitHub-Actions-compatible
+    # environment (Python, Node, glibc). The "docker" label maps to a bare
+    # Alpine image, which lacks the glibc most published actions expect.
+    runs-on: ubuntu-22.04
+    steps:
+      # NOT using actions/checkout here -- it's broken for SHA256 repos
+      # (this one is): it initializes the local git repo before fetching
+      # without specifying --object-format=sha256, so the real 64-char
+      # SHA256 ref it then tries to fetch gets rejected by the freshly
+      # (SHA1-defaulting) initialized local repo, failing with "couldn't
+      # find remote ref". Confirmed via real testing on this exact
+      # workflow, and a known, still-open, ~1-year-old bug, tracked both
+      # upstream (actions/checkout#1843) and in Forgejo itself
+      # (forgejo/forgejo#9431) -- not something specific to this workflow.
+      # A plain `git clone` doesn't have this problem: cloning negotiates
+      # the object format with the remote from the start, rather than
+      # assuming SHA1 and fetching into it after the fact. Auth uses the
+      # same http.extraheader bearer-token approach actions/checkout
+      # itself uses internally (confirmed working in the earlier failed
+      # run -- "Setting up auth" succeeded; only the later fetch failed).
+      - name: Checkout
+        env:
+          FORGEJO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git -c http.extraheader="Authorization: Bearer ${FORGEJO_TOKEN}" \
+            clone --depth 1 --branch "${{ github.ref_name }}" \
+            https://code.r3pek.org/r3pek/python-mobius.git .
+
+      - name: Set up Python
+        uses: https://code.forgejo.org/actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build and test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pip install build twine
+
+      # Gate: the rest of this job (build, PyPI publish, release creation)
+      # only runs if this step succeeds.
+      - name: Run tests
+        run: pytest -q
+
+      - name: Build package
+        run: python -m build
+
+      - name: Validate built package
+        run: python -m twine check dist/*
+
+      - name: Publish to PyPI
+        # Only on a real tag push -- a workflow_dispatch run (manual, for
+        # testing/debugging this workflow itself) has no version tag to
+        # publish under and shouldn't attempt to.
+        if: github.event_name == 'push'
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: python -m twine upload dist/*
+
+      # Pulls the section of CHANGELOG.md under the heading matching this
+      # tag's version (tag v0.3.0 -> "## 0.3.0") for the Forgejo release
+      # notes, rather than letting Forgejo auto-generate notes from commits.
+      # Fails the job (on purpose) if no matching section is found, rather
+      # than silently publishing a release with empty/wrong notes.
+      # Same event-gating reason as the PyPI step -- github.ref_name on a
+      # manual run is whatever branch was picked, not a version, so there's
+      # no matching CHANGELOG.md section to find at all.
+      - name: Extract changelog section for this version
+        if: github.event_name == 'push'
+        run: python3 .forgejo/scripts/extract_changelog_section.py "${{ github.ref_name }}"
+
+      # direction: upload with no release-dir set -- no wheel/sdist attached
+      # to the Forgejo release itself (PyPI is the source of truth for the
+      # built artifacts); this step only creates the release entry with the
+      # extracted changelog section as its notes. Worth confirming on the
+      # first real run that omitting release-dir doesn't pick up dist/ by
+      # some other default -- the action's own docs only show examples with
+      # release-dir explicitly set, so this specific "notes only" case
+      # isn't directly demonstrated there.
+      # Same event-gating reason as the two steps above -- nothing to
+      # release against on a manual, non-tag run.
+      - name: Create Forgejo release
+        if: github.event_name == 'push'
+        uses: https://code.forgejo.org/actions/forgejo-release@v2
+        with:
+          direction: upload
+          url: https://code.r3pek.org
+          repo: r3pek/python-mobius
+          token: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ github.ref_name }}
+          release-notes-file: release_notes.md

{python_mobius-0.2.0 → python_mobius-0.3.0}/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## 0.3.0
+
+- **Fixed a real, high-impact bug in `is_night_segment()`: the condition
+  deciding whether to apply lunar-phase reduction had its first check
+  inverted**, confirmed directly from raw smali bytecode after JADX's
+  own decompiled Java carried a "Code duplicated" warning on this exact
+  method that turned out to be a real signal -- the decompiler had
+  produced `!point.has(NIGHT)` where the actual bytecode requires
+  `point.has(NIGHT)`. In practice this meant lunar reduction was applied
+  only during the single dusk-transition segment (and only if the query
+  time exactly matched a night-flagged point), while every other
+  night-to-night segment -- the bulk of an actual night -- silently used
+  the schedule-intensity scalar instead. Found via real hardware
+  testing: a light in a `23:00[NIGHT,SUNSET] -> 23:27[NIGHT]` segment
+  produced a value consistent with schedule-intensity-only scaling from
+  this library, while the real app displayed a noticeably lower,
+  lunar-consistent value at the same moment -- mathematically impossible
+  to explain by schedule-intensity alone within that segment's raw-value
+  range. 4 tests fixed/rewritten to match the confirmed correct
+  semantics (including one reproducing the exact real-world schedule and
+  moment this was found from), plus 2 more updated in
+  `test_light_intensity_branching.py` whose fixture schedule needed to
+  actually be a night-to-night segment rather than the (no longer
+  qualifying) dusk-transition segment it used before.
+
+- **Fixed a real bug, the same class of gap this project has hit before:
+  `get_hardware_info()` was never wired into `get_device_summary()`,**
+  meaning it worked correctly in isolation (with its own passing tests)
+  but was silently missing from the CLI's output and any other "give me
+  everything" caller built on the summary entrypoint -- see
+  `get_device_summary()`'s own "BUG NOTE" docstring, which describes the
+  exact same thing having happened to `get_group_info()`/
+  `get_calibration_info()`/etc. previously. Added `info["hardware_info"]
+  = await self.get_hardware_info()` alongside the existing
+  `firmware_versions` line. The CLI needed no changes at all -- its
+  summary printing is a generic loop over whatever `get_device_summary()`
+  returns, so this alone was the actual fix. 2 tests extended (not just
+  `"key" in summary`, but the actual decoded value) specifically so this
+  field can't silently regress the way it silently went missing.
+
+- **`get_hardware_info()` now decodes `Color`/`ProductType`/`RadioType`/
+  `MotorType` into confirmed display labels**, instead of returning raw
+  bytes. Each is itself a confirmed enum with confirmed labels
+  (`M.Color`/`M.ProductType`/`M.RadioType`/`M.MotorType` in the
+  decompile) -- added `Color`, `RadioType`, `MotorType`, `ProductType`
+  enums plus their `*_LABELS` dicts to `mobius.constants`. An
+  unrecognized value falls back to `"Unknown (N)"` rather than raising.
+  `Revision`/`Segments` still have no confirmed enum meaning -- returned
+  as plain integers (previously raw bytes) rather than formatted.
+  Several `MotorType`/`ProductType` labels were base64-string-obfuscated
+  in the decompile rather than plain literals (apparently to avoid
+  casual discovery of unannounced product names in a simple APK string
+  dump) -- decoded and included regardless, since it's plain base64, not
+  any actual protection. 3 new tests. **Breaking change** for any caller
+  relying on `get_hardware_info()`'s previous raw-bytes return shape.
+
+## 0.2.1
+
+- **Fixed a real bug found via real hardware testing: some "get all
+  elements" responses were silently truncated to their first block.**
+  `get_attribute_raw()` returned only the first matching
+  `(attrId, index, count, values)` block in a response and discarded any
+  others -- a Radion light showing 8 firmware components in the official
+  app came back as only 5 via `get_firmware_versions()`, because that
+  light's `FirmwareVersion` response genuinely splits across two
+  separate blocks (one covering `MainMicroOS`/`MainMicroBootloader`,
+  another covering the `QCA4020`-prefixed types), not one block covering
+  every element. Added `get_attribute_raw_all()`/`get_attribute_all()`
+  (`MobiusDevice`, with a matching `RelayedMobiusDevice` override --
+  without one, callers built on these would have silently fallen through
+  to `MobiusDevice`'s own non-relay implementation when called on a
+  relayed device) -- return every matching block instead of just the
+  first. `get_firmware_versions()`, `get_hardware_info()`,
+  `get_channel_power_info()`, and `get_supported_channels()` are now
+  built on these rather than the single-block versions, merging every
+  block's values, each interpreted using its own block's starting index.
+  5 new tests, including ones that specifically reproduce the two-block
+  scenario found on real hardware, both directly and through relay.
+
 ## 0.2.0
 
 Thread/CoAP device relay -- see

{python_mobius-0.2.0 → python_mobius-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mobius
-Version: 0.2.0
+Version: 0.3.0
 Summary: Reverse-engineered Python client for the Mobius BLE protocol (EcoTech Marine VorTech/Radion, AquaIllumination, Neptune Systems, NYOS)
 Project-URL: Homepage, https://code.r3pek.org/r3pek/python-mobius
 Project-URL: Documentation, https://code.r3pek.org/r3pek/python-mobius/src/branch/main/documentation

{python_mobius-0.2.0 → python_mobius-0.3.0}/documentation/00-overview.md

@@ -49,7 +49,7 @@ Interface conventions, extended by EcoTech).
 | [06-light-schedule.md](./06-light-schedule.md) | Light point-schedule format + client-side interpolation |
 | [07-pump-schedule.md](./07-pump-schedule.md) | Pump primitive format, mode/parameter tables, block lookup |
 | [08-manufacturer-data.md](./08-manufacturer-data.md) | BLE advertisement format (no-connection discovery) |
-| [09-thread-coap-relay.md](./09-thread-coap-relay.md) | How the official app relays to devices without direct BLE (not implemented here) |
+| [09-thread-coap-relay.md](./09-thread-coap-relay.md) | Relaying requests to devices without a direct BLE connection, through another connected device |
 | [10-known-gaps-and-open-questions.md](./10-known-gaps-and-open-questions.md) | Everything not yet confirmed or implemented |
 | [11-device-status-attributes.md](./11-device-status-attributes.md) | Flow range, override mode, battery backup, group/sync, calibration (light-only), maintenance |
 | [12-device-identity-and-address-stability.md](./12-device-identity-and-address-stability.md) | Why device identity is serial-number-based, not address-based |

{python_mobius-0.2.0 → python_mobius-0.3.0}/documentation/06-light-schedule.md

@@ -8,18 +8,12 @@ There's no attribute you can `Get` that tells you what a light is currently
 displaying. Instead, the app fetches the entire programmed point-schedule
 and computes the current intensity **client-side**, by linearly
 interpolating between the two points that bracket the current time, then
-applying a schedule-level master intensity scalar on top (see below), plus
-acclimation-ramp and lunar-cycle modifiers this library still doesn't
-implement.
+applying a schedule-level master intensity scalar (see below), plus
+lunar-cycle and acclimation-ramp modifiers under specific conditions.
 
 This library's `get_current_light_intensities()` replicates that
-client-side computation. **Correction to an earlier version of this doc**:
-this was previously described as "confirmed correct by validating against
-real fetched schedules" -- that validation only checked the per-channel
-interpolation curve, not the schedule-level scalar below, which was
-missing entirely at the time and silently returned values that didn't
-match the app's real displayed numbers. Caught by direct comparison
-against real app screenshots. Fixed; see below.
+client-side computation, including the master intensity scalar and the
+lunar/acclimation modifiers.
 
 ## Schedule-level master intensity (`Schedule1Intensity`, attribute 511)
 
@@ -34,13 +28,13 @@ regular per-channel value some models expose, not this).
 `get_schedule_intensity()` fetches this (a plain `Get` on
 `Schedule1Intensity`/`Schedule2Intensity`, no special indexing -- a short,
 0-1000, default 500/50% per the app's own initialization code).
-`get_current_light_intensities()` now applies it automatically.
+`get_current_light_intensities()` applies it automatically.
 
-**Update**: lunar-phase and acclimation-ramp reductions, which are layered
-on top of this same scalar under specific conditions (night + lunar phases
-enabled; an active, incomplete acclimation period), are now also
-implemented -- see "Lunar phase and acclimation ramp" below. "Insolation"
-(a separate, rarer modifier) is still not.
+Lunar-phase and acclimation-ramp reductions layer on top of this same
+scalar under specific conditions (night + lunar phases enabled; an
+active, incomplete acclimation period) -- see "Lunar phase and
+acclimation ramp" below. "Insolation" (a separate, rarer modifier) is
+not implemented.
 
 ## Wire format
 
@@ -76,10 +70,8 @@ Repeating triplets, one per channel the point defines:
 VisualID (u8) + intensity (u16 LE, 0-1000 = 0.0-100.0%)
 ```
 
-Confirmed via a full 9-point schedule fetched live from two real XR15
-lights (identical schedules on both — a deliberately symmetric setup, not a
-parsing artifact, confirmed by the two lights having different serial
-numbers).
+Confirmed against a full 9-point schedule fetched live from real XR15
+lights.
 
 ## Interpolation algorithm
 
@@ -94,45 +86,60 @@ Ported from `PointSchedule.getIntensitiesAtTime()`:
 4. Channels absent from a point default to `0` (off).
 
 Verified against a synthetic two-point schedule (exact endpoint values,
-midpoint blending, and midnight-wraparound blending all behave correctly —
-see `tests/test_light_schedule.py`) and against a real 9-point schedule
-fetched live, which produced a coherent daily light-intensity curve
-(dim moonlight overnight → ramp to full blues/UV midday → wind back down).
+midpoint blending, and midnight-wraparound blending -- see
+`tests/test_light_schedule.py`) and against a real 9-point schedule
+fetched live, which produces a coherent daily light-intensity curve (dim
+moonlight overnight → ramp to full blues/UV midday → wind back down).
 
 ## `SupportedColorChannels` (attribute 901)
 
-A static list of `VisualID` values (channel identities) a given light has —
-this is capability metadata, not live state. Confirmed via `Get` with
-`index=0, count=0xFFFF` against real hardware; both test lights reported
-the same 13-channel set (`Violet, CoolWhite, WarmWhite, Blue, UV, RoyalBlue,
-Green, Red, MoonlightBlue, MoonlightWhite, Brightness, StormProbability,
-CloudProbability`).
+A static list of `VisualID` values (channel identities) a given light has
+-- this is capability metadata, not live state. Confirmed via `Get` with
+`index=0, count=0xFFFF` against real hardware.
 
 ## Lunar phase and acclimation ramp
 
-Both now implemented, on top of the schedule-level master intensity above.
+Both implemented, on top of the schedule-level master intensity above.
 Ported from `LunarInfo.java`/`AcclimationInfo.java` in the decompiled app.
 
 **Lunar phase** (`lunar_percent_reduction(date)`): a simplified moon-phase
 model -- a Julian-Day-based calculation (`julian_day_from_date()`, the
 standard Fliegel-Van Flandern conversion) feeding a 16-entry lookup table
 (`LUNAR_CYCLE_SCALERS`), returning `0.0` at new moon ramping to `1.0` at
-full moon. Verified against real, independently-confirmed 2026 moon phase
-dates (full moon Jan 3 2026, new moon Jan 18 2026) -- the ported algorithm
-matches exactly.
+full moon. Verified against independently-confirmed real 2026 moon phase
+dates (full moon Jan 3 2026, new moon Jan 18 2026) -- the ported
+algorithm matches exactly.
 
-This replaces the normal schedule-intensity scalar specifically during the
-**dusk-to-night segment** of the schedule (see `is_night_segment()` below),
-and only when `LunarPhasesEnabled` (attribute 907) is set on the device --
-otherwise that segment just uses a flat `1.0` (full/unreduced) scalar,
-matching the app's own fallback.
+This replaces the normal schedule-intensity scalar for any segment
+where `is_night_segment()` is true (see below), and only when
+`LunarPhasesEnabled` (attribute 907) is set on the device -- otherwise
+that segment just uses a flat `1.0` (full/unreduced) scalar, matching
+the app's own fallback.
 
 **`is_night_segment()`**: ported from the boolean half of
 `PointSchedule.getIntensitiesAtTime()`'s return value. This is *not*
-simply "is it night" -- confirmed by reading the Java source directly, it's
-specifically true for the segment whose start point is NOT flagged `NIGHT`
-or `SUNRISE` and whose end point IS flagged `NIGHT` (the dusk-transition
-segment), or when the query time exactly matches a `NIGHT`-flagged point.
+simply "is it night" as a general concept -- it's specifically true for
+the segment whose **start** point IS flagged `NIGHT` (but not also
+`SUNRISE`) and whose end point is ALSO flagged `NIGHT` -- i.e. once
+already into the night portion of the schedule, through to the sunrise
+transition -- or when the query time exactly matches a `NIGHT`-flagged
+point. In practice this covers essentially the whole night, *except*
+the two transition segments themselves: dusk (start point not yet
+night-flagged) and the sunrise segment (start point flagged `SUNRISE`).
+
+**Confirmed directly from raw smali bytecode, not the decompiled Java.**
+JADX's decompiler carried its own "Code duplicated" warning on this
+exact method -- a real signal, not noise: its decompiled Java had this
+condition's first check inverted (`!point.has(NIGHT)` instead of the
+actual `point.has(NIGHT)`), which an earlier version of this port
+carried forward uncorrected. Found via real hardware testing: a light
+in a `23:00[NIGHT,SUNSET] -> 23:27[NIGHT]` segment showed a value
+consistent with the schedule-intensity scalar from this library, while
+the real app displayed a noticeably lower, lunar-consistent value at
+the same moment -- mathematically impossible to explain by
+schedule-intensity alone within that segment's raw-value range, which
+is what prompted re-examining the raw bytecode instead of trusting the
+decompiled Java a second time.
 
 **Acclimation ramp** (`AcclimationInfo`): a linear intensity ramp from
 `start_intensity` (0-1000 permille) up to full (1000) over `period_days`,
@@ -147,8 +154,8 @@ automatically -- no separate calls needed for the common case.
 ## Insolation detection (flagged, not implemented)
 
 Insolation itself is not implemented (see below), but
-`get_current_light_intensities()` does cheaply detect whether it's active
-and flag it, via `LightIntensityResult` -- the return value is a real
+`get_current_light_intensities()` cheaply detects whether it's active
+and flags it, via `LightIntensityResult` -- the return value is a real
 dict (fully backward compatible with code that indexes/iterates it like a
 plain dict), with an added `.diagnostics` attribute:
 
@@ -165,18 +172,15 @@ wrong-but-present value is often more useful than nothing, and the
 severity depends on how different the real Insolation-derived schedule is
 from the manually-programmed one on a given day.
 
-## Debugging diagnostics: which branch/scalar was actually used
+## Diagnostics: which branch/scalar was actually used
 
 `.diagnostics` also includes `"is_night_segment"`, `"lunar_enabled"`,
 `"scalar_source"` (one of `"lunar"`/`"night_no_lunar"`/
 `"schedule_intensity"`), and `"scalar"` (the actual final multiplier
-applied). Added specifically because a mismatch between this library's
-computed value and the app's own displayed value could stem from either
-`is_night_segment()` misjudging a specific schedule's point structure, or
-`get_lunar_enabled()` reading incorrectly -- and those need to be told
-apart with real data rather than guessed at. If you ever see a value that
-doesn't match the app, check these fields first before assuming which
-piece is wrong:
+applied) -- useful for telling apart which branch/scalar produced a given
+value, e.g. when a computed value doesn't match the app's own displayed
+one and it isn't obvious whether `is_night_segment()` misjudged a
+schedule's point structure or `get_lunar_enabled()` read incorrectly:
 
 ```python
 result = await device.get_current_light_intensities()
@@ -198,26 +202,19 @@ intensity values above `1000` permille (100%) on the wire, up to `2000`
 percentage is wrong once it's above 1000 -- the true percentage depends on
 how much headroom that specific channel actually has.
 
-`get_current_light_intensities()` (and `interpolate_light_schedule()`
-underneath it) already handled boosted raw values correctly all along --
-nothing was capped or clamped, so the interpolation itself was never
-wrong. What was missing was converting a boosted raw value to an accurate
-*percentage* for display.
-
-`get_current_light_percentages()` is the corrected alternative: it fetches
+`get_current_light_percentages()` accounts for this: it fetches
 `MaxPower`/`NormalPower` (`get_channel_power_info()`, attributes `1504`/
 `1513`) and applies `channel_percent_value()` (`mobius.power`, ported from
-`LightPowerInfo.getPercentValue()`) per channel. For the overwhelming
-common case -- non-hyperdrive channels/devices, i.e. any raw value at or
-below 1000 -- this gives byte-identical results to the old `raw/10`
-shortcut; the extra machinery only changes anything for genuinely boosted
-channels. It also flags which channels are currently boosted via
-`.diagnostics["hyperdrive_channels"]`.
+`LightPowerInfo.getPercentValue()`) per channel. For the common case --
+non-hyperdrive channels/devices, i.e. any raw value at or below 1000 --
+this gives the same results as a simple `raw/10`; the extra machinery
+only changes anything for genuinely boosted channels. It also flags which
+channels are currently boosted via `.diagnostics["hyperdrive_channels"]`.
 
 This costs extra BLE round trips beyond `get_current_light_intensities()`
 alone (two more `Get`s for `MaxPower`/`NormalPower`). Use
-`get_current_light_intensities()` directly if you don't need hyperdrive
-accuracy or want to minimize round trips.
+`get_current_light_intensities()` directly if hyperdrive accuracy isn't
+needed, or to minimize round trips.
 
 **Not replicated**: `LightPowerInfo`'s `gm8b4()` lookup table -- a
 hardcoded wattage override for a handful of specific AquaIllumination