Skip to content

Document the three fields GET /v1/info gained - #33

Open
enver-haase wants to merge 2 commits into
GideonZ:masterfrom
enver-haase:docs/info-mac-and-git-hash
Open

Document the three fields GET /v1/info gained#33
enver-haase wants to merge 2 commits into
GideonZ:masterfrom
enver-haase:docs/info-mac-and-git-hash

Conversation

@enver-haase

@enver-haase enver-haase commented Sep 3, 2026

Copy link
Copy Markdown

GET /v1/info gained three fields in GideonZ/1541ultimate#827, merged for 3.15: git_commit_hash, ethernet_mac and wifi_mac. The sample response in api/api_calls.rst still showed the shape before that.

All three need a word about when they are absent, which a JSON sample cannot really carry, so they get short paragraphs under it:

  • Which firmware answers with them. From 3.15 onwards; older firmware answers this call without them. The sample's firmware_version moves from 3.12 to 3.15 for the same reason — a sample cannot carry fields the version it names does not have.
  • git_commit_hash — the abbreviated hash of the commit the firmware was built from, the same string the System Information screen shows. It tells two builds apart that carry the same version number.
  • ethernet_mac and wifi_mac — the wired and wireless hardware addresses, upper case and colon separated (routes.cc formats them with %b, which resolves to "0123456789ABCDEF"). Each is left out when the device has no such interface, and while an interface has not started and its address is not known yet. Only the first interface of each kind is reportedroutes.cc skips any later one with if (reported[kind]) continue;.
  • Waking is Wi-Fi only. A magic packet is sent to wifi_mac. The wired interface does not wake the device: the only matcher is software/u64ctrl/main/wol_magic.c, called from one place, wifi_modem.c:164 on the ESP32, and the setting is CFG_WAKE_ON_WIFI. Nothing equivalent exists on the RMII side.

That last point is worth flagging beyond this PR. I first wrote the broader claim here because I copied it from the comment in routes.cc and from the description in rest_api_openapi_u64.yaml / _u2.yaml, both of which say the two addresses are what a Wake-on-LAN packet is addressed to. The same overreach is already merged in the firmware repository. Happy to raise a small PR against test-merge to narrow it there too, so the two sources do not disagree — say the word.

The second commit is separate and can be dropped on its own: the sample's core_version read 143, but the firmware builds that field as sprintf(core_version, "1.%02x", ...), so an Ultimate 64 Elite reports 1.49. No device answers with 143.

Built with sphinx-build . ./build/ before pushing: exit 0, no warning naming api_calls.rst. The warnings the build does emit are the pre-existing toc.not_readable ones about missing config/ pages. I read the rendered api/api_calls.html too, so the paragraphs really do land inside the table cell rather than after the table.

`git_commit_hash`, `ethernet_mac` and `wifi_mac` were added to the endpoint in
GideonZ/1541ultimate#827 and merged for 3.15, but the sample response here
still showed the older shape.

Each of the three needs a word about when it is absent, which a JSON sample
cannot carry on its own, so they get short paragraphs below the sample rather
than only a trailing comment: which firmware first answers with them, that only
the first interface of each kind is reported, and that it is the Wi-Fi address,
not the wired one, that a magic packet wakes the device through.

The sample's firmware version moves from 3.12 to 3.15, because a sample cannot
carry fields that the version it names does not have.
The firmware builds this field as `sprintf(core_version, "1.%02x", ...)` in
`software/api/routes.cc`, so it always carries the dot: an Ultimate 64 Elite
reports `1.49`. The sample here showed `143`, which no device answers with.

Separate from the rest of this branch, since it predates the three fields being
documented and can be dropped on its own.
@enver-haase

Copy link
Copy Markdown
Author

Raised the firmware side as GideonZ/1541ultimate#842, so the two do not end up disagreeing: the same too-broad sentence is in the DESCRIPTION in routes.cc and therefore in both generated OpenAPI documents. It narrows the claim to wifi_mac and adds the one thing the loop has always done without saying so — only the first interface of each kind is reported.

Merging one of the two without the other leaves one source telling callers that a packet to ethernet_mac wakes the device.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant