For isolated performance tests, make perf-ipad builds and launches the separate
SmartGrid Perf app, collects arbitrary case metrics and device telemetry into
~/Documents/SmartGridOne/perf.sqlite3, and leaves the iPad on its home screen.
It initializes no audio. See the benchmark guide.
The repository can build, install, launch, sync, and collect logs from the paired SmartGridOne iPad without a USB cable.
make juce-deps.SmartGridOne - App scheme. The project uses
development team 84DCGNY7JA.brew install sox).The deploy and install targets create the pinned Python environment automatically when it is missing. To prepare it separately for sync or logs:
make ios-setup
The known device defaults are UDID 00008122-001439681EA1001C and host
192.168.1.53. If DHCP changes the address, set IPAD_HOST; set IOS_DEVICE
to target another paired device.
From the repository root:
make ios-deploy
This builds a signed Release app for generic iOS, upgrades the installed app over Wi-Fi, and launches it. The iPad must be unlocked for launch. Each failure stops the command; fix the reported cause and rerun it from the beginning.
Other targets are ios-build, ios-install, and the compatibility alias
deploy-ios. ios-install installs the existing build without launching it.
All three use build/xcode/ios/Release/Products/SmartGridOne.app by default;
CONFIG=Debug selects the separate Debug directory. Build caches and products
stay in this checkout. See building.md for incremental builds,
configuration selection, and cleanup.
make ios-deploy IPAD_HOST=192.168.1.80 IOS_DEVICE=00008122-001439681EA1001C
Sync chooses USB when the requested UDID is attached and Wi-Fi otherwise:
scripts/.venv-ios/bin/python scripts/sync_ipad.py
Use --transport usb or --transport wifi to force a transport. Patch files
copy in both directions. App logs copy from the iPad and refresh when the remote
file grows. Recordings copy to the Mac and extract the stereo master using the
SMRTGRID extractor or SoX for legacy WAV/RF64 files. They are removed from the iPad
only after a complete download, successful extraction, and stable-size check.
For a connectivity check that cannot transfer or delete a recording:
scripts/.venv-ios/bin/python scripts/sync_ipad.py --transport wifi --no-recordings
Copy the latest app log, or a named log relative to the app log directory:
scripts/.venv-ios/bin/python scripts/ipad_logs.py app
scripts/.venv-ios/bin/python scripts/ipad_logs.py app --name session.log
Collect recent historical iPad unified logs:
scripts/.venv-ios/bin/python scripts/ipad_logs.py system --last 15m
scripts/.venv-ios/bin/python scripts/ipad_logs.py system --since 2026-09-15T12:00:00-07:00
Completed captures go under ~/Documents/SmartGridOne/diagnostics. A failed
capture retains a directory ending in .partial; a rerun creates a fresh one.
See the repository ipad-logs skill for archive queries and the full evidence
taxonomy.
The iPad creates the .logarchive format; the collector only transfers and
extracts it. This format is independent of SGREC. On November 8, 2026, iPadOS
27.2 (24B119) produced OSArchiveVersion = 6, which both log show and log
stats on macOS 15.7.4 rejected with “newer log tools are needed”. Changing the
SGREC reader or upgrading the collection dependency does not address that
reader mismatch. Preserve the archive’s original version metadata.
Mandiant unifiedlog_iterator v0.7.0 adds iOS 27 support. Its released Apple Silicon binary successfully decoded the original v6 archive on this Mac. Use the maintained command:
scripts/.venv-ios/bin/python scripts/ipad_logs.py decode CAPTURE.logarchive \
--output build/results/incident-decoded
The command downloads the pinned release on first use (network access required),
verifies package SHA-256
bf5c4a3418b133fbd403ca7893a2280acb8c2c3605b4ad6f87f9fc75b35a20b7,
and installs it under ignored build/tools/unifiedlogs-0.7.0/. Each run checks
the binary’s pinned checksum too. It requires an Apple Silicon Mac and does not
modify the archive. No manual installation or archive metadata edits are needed.
Choose a new output directory for each decode; decoded JSONL can be large.
It contains records.jsonl, summary.json (UTC coverage, loss-record count,
archive version, reader provenance), the bookmark, and reader stdout/stderr.
Failed decoding retains .partial output and does not publish a completed
directory. Existing complete or partial output is never overwritten.
Records are not globally time-sorted. Check timestamp coverage, loss records,
and missing-message markers before drawing conclusions. This reader reproduced
the previous day’s 2,241 invalid-number messages and both thermal-transition
timestamps obtained with Apple’s reader; that validates those anchors, not
every possible message type. Keep raw captures alongside decoded results.
The existing message-thread reporter drains numeric callback batches once per second and adds the following to its roughly once-per-minute diagnostic dump:
Audio metrics: callback count, valid CPU-clock count, summed elapsed/CPU
microseconds and summed callback budgets. cpu_count < count means some CPU
measurements were unavailable; do not interpret those as zero CPU work.Audio metrics range: first and last callback-entry monotonic timestamps
covered by the aggregate. Ranges can span more than a minute after a UI stall.Audio callback kind=worst_wall|worst_cpu|worst_arrival: complete paired
measurements and position of each selected callback. The following
Audio callback timing line has the same callback ID. excess_us is arrival
interval minus the previous buffer’s duration, floored at zero. It is a cadence
diagnostic, not a hardware deadline or proof of scheduler starvation.Audio clock: a monotonic-to-UTC anchor and engine sample rate. Use captured
mono_us to place incidents, rather than the text logger’s drain-time prefix.Recording metrics: existing recorder state/error, written frames/bytes,
session queue high-water and maximum compression/write-block duration, plus
the recording’s start host-sample index. These counters reset on recording
start and are approximate concurrent snapshots, not interval maxima.Individual elapsed-time overruns and long arrival gaps are logged as
kind=incident when their batch reaches the reporter. Recording positions can
be related to engine_sample / oversample - start_host_sample; the engine
sample is captured at callback entry, before its first rendered sample.
The audio path reads a steady clock and the current thread’s CPU clock at entry
and exit, then updates fixed-size numeric storage. It performs no logging,
formatting, allocation, waiting or file I/O. The clock is warmed during device
preparation. On Apple platforms, the public CLOCK_THREAD_CPUTIME_ID path uses
the kernel’s current-thread runtime query, not thread enumeration or another
thread’s Mach port. Relevant implementation sources:
Libc clock_gettime
and XNU thread_get_runtime_self.
One aggregate is queued approximately each second. The 64-batch SPSC queue is
fixed-size; if full, the producer keeps accumulating totals and worst records
until publication succeeds. Each pending batch retains at most 16 individual
incidents, and each reporter poll formats at most 16 incidents. Additional
incident details are counted in omitted_incidents; totals and worst records
are still retained. Device restarts preserve queued records and reset arrival
history so downtime is not misclassified as an arrival gap. These diagnostics
do not collect CPU use of other processes, and do not alter general log points.
The iPad / MAYA44 investigation journal
is versioned in this repository. Add dated results there and update its index
and experiment queue. The old diagnostic worktree is historical context, not
the journal’s storage location. Large raw device captures remain under
~/Documents/SmartGridOne/diagnostics and are linked from the entries.
Start the receiver on the Mac (Python 3.10 or newer; SoX is needed for legacy WAV/RF64 recordings):
python3 scripts/sync_receiver.py
On the iPad, open File > Sync with Mac and tap the receiver. On first use, compare the certificate fingerprint with the Mac terminal and enter the access code printed there. The iPad remembers that pairing in Keychain. Use Pair / change access code to correct a code. The Mac and iPad must share a local network; allow Local Network access when prompted and incoming connections to the receiver if macOS asks.
Sync copies missing patches both ways without overwriting them, refreshes larger logs on the Mac, and sends completed recordings. The Mac retains the original and automatically extracts its stereo master while later files transfer. Only a verified successful extraction acknowledgement permits deleting that recording from the iPad. Unfinished recordings are skipped and retained. An interrupted file starts again on the next sync; complete matching Mac originals are reused.
All iPad sync activity belongs to the foreground Sync page. Leaving the page stops discovery and resolving, cancels requests, closes the session, and joins the transfer worker before returning to File. App inactivity does the same. Returning to the app while the page remains open restarts discovery, but does not restart a transfer. There are no background sessions, startup discovery, audio callbacks, audio-engine hooks, or audio-thread polling for sync. Cancel sync stops the transfer while leaving discovery and publishing controls available.
The separately launched Mac receiver listens only while its command is running;
press Ctrl-C to stop it. Its default port is 47658, and Bonjour publishes the
port, so no address entry or LAN scan is needed. --name, --port, --host,
--root, and --identity-dir can override the defaults. Receiver keys and
identity are stored under
~/.config/smartgridone/sync, outside the repository. Keep that directory to
preserve pairing. HTTPS uses the pinned certificate and a private access code.
scripts/.venv-ios/bin/python -m unittest discover -s scripts/tests -v
The native integration tests compile a Foundation-only client, exercise TLS against temporary loopback receivers, and verify Bonjour discovery on the Mac. They cover full/repeated sync, certificate mismatch, unfinished/corrupt recordings, cancellation during upload/download and extraction, foreground loss, and rejection of transfers after Close. The receiver suite also exercises real legacy WAV extraction and shutdown during an upload.
Physical-iPad discovery, pairing, and full sync were verified on 2026-09-23:
4.12 GB of recordings arrived, both stereo files were extracted, logs synced,
and verified iPad originals were removed. Bulk transfer averaged about 6.6 MB/s
on that run; TCP retransmissions caused some pauses. The normal app made no sync
connections during a 20-second launch observation. Physical screen-lock and
background transitions still need verification. Compare transfer MiB/s with
sync_ipad.py --transport wifi on the same recording and network before drawing
conclusions about relative speed.
Register a SoundCloud application for the account you intend to publish from.
Its registered redirect must exactly match the setup callback; the default is
http://127.0.0.1:47659/callback. From the repository root on the Mac, run:
python3 scripts/soundcloud_connect.py
The command privately prompts for the application’s client ID and client secret,
then asks for the registered callback URL. Press Return to use the default.
Complete the browser consent using the intended SoundCloud account. Setup uses
PKCE and state, verifies the account, and reports that it is connected in Mac
Keychain. Credentials and rotating tokens are stored under service
com.theallelectricsmartgrid.soundcloud, account publisher; they are not stored
with recordings or in the repository. The setup command has no credential flags.
Start, or restart, the receiver after connecting:
python3 scripts/sync_receiver.py
The receiver loads authorization at startup. Keep the Mac awake and this command
running. The default archive is ~/Documents/SmartGridOne; --root chooses a
different archive. Its .soundcloud.sqlite3 stores non-secret catalog data, jobs,
and receipts. Preserve it to retain upload history. Receiver pairing still uses
its separate identity directory and access code described above.
No SoundCloud login is added on the iPad. Its existing pinned receiver pairing allows publication to the account configured on that Mac. The panel message Connect SoundCloud on the Mac receiver to enable publishing. Sync is available. means setup is missing or authorization needs repair: run the connection command again and restart the receiver. An older receiver shows an update message while ordinary sync remains available.
*_stereo.wav
exports and incoming recordings appear together. Before sending audio, the
iPad announces each finished source recording; these rows show Pending
transfer. Unfinished recordings are excluded. Duration appears once the
Mac has extracted the stereo file. This requires an updated Mac receiver;
older receivers continue to support ordinary sync.Smart Grid Nightly YYYY/MM/DD, using the
recording’s stored local start date. The first known post for a date has no
suffix; subsequent defaults begin at ` #2`. Existing posts and pending jobs
affect the number, which the Mac assigns when it accepts the upload. Custom
titles are trimmed and receive no automatic suffix. Older numbered files use
SGREC start metadata or a stored modification-time fallback; edit the title
if that displayed date is unsuitable.Refresh catalog rescans local stereo exports and refreshes the configured account’s track metadata, including tracks uploaded manually elsewhere. Ordinary status polling reads the Mac’s saved state. If the first account listing fails, automatic naming waits for a successful refresh; a complete cached listing can continue to supply defaults after a later refresh failure.
Cloud-only recordings are skipped without downloading them during catalog scans. Download a recording on the Mac first, then use Refresh catalog to include it.
For a recording already published manually, select its track in Select an existing account track and tap Link existing. The receiver can suggest a unique nightly date and duration match; verify the selected track before explicitly linking it. Custom titles and ambiguous matches can be selected from the same account-track list. Linking records Uploaded for this file version and account without sending audio again. Use Refresh catalog if the track is missing from the list.
A definite rejection shows its error and Retry. Fix the cause before retrying. If the iPad loses the receiver’s acceptance response, it retains the request identity and checks the Mac’s status. Retry same request uses that same identity to recover the accepted job. Resolve this pending upload before uploading another recording; other drafts can still be edited.
An unknown result means SoundCloud may already have accepted the Mac’s request. Tap Open SoundCloud account, inspect the account, and refresh/link an existing track if it was created. Only use Upload again after checking: that explicit new attempt may create a duplicate. Unknown results never trigger an automatic second creation request.
Cancel sync stops only iPad file transfer. Leaving the Sync page or making the app inactive stops iPad discovery, requests, and polling; an upload already accepted by the Mac continues there. Reopen the page and choose the Mac to see its saved job or receipt. Foreground return to an already-open page reconnects after discovery without automatically restarting file transfer or submitting another upload.
Requests marked Queued after transfer also survive leaving the page or restarting the receiver. If transfer is cancelled or fails before the stereo export is ready, the request stays waiting. Select the Mac again to resume sync; publication starts only after a successful matching transfer and extraction. An extraction error is displayed on the waiting row. Pending transfers cannot be linked to historical tracks until the export is ready.
Stopping the receiver with Ctrl-C, sleeping the Mac, or interrupting its network can interrupt the outgoing publication. On receiver restart, queued jobs resume, completed receipts remain Uploaded, and jobs interrupted while Uploading become Unknown for explicit recovery. The original and stereo recordings remain on the Mac regardless of publication outcome.
On 2026-10-29, queued-after-transfer coverage passed with 33 publishing/API tests, 13 native publishing scenarios, 12 native sync scenarios, and 20 receiver tests. The native TLS scenario queues two incoming recordings before the first audio transfer, closes the publishing controls, and recovers both completed receipts. Backend cases cover restart persistence, title/artwork retention, digest matching, failed-transfer recovery, and a tap during transfer completion. These checks use a fake SoundCloud API; no real track was published.
On 2026-10-11, both macOS and iPad simulator builds succeeded. Focused tests used real local HTTPS receivers, temporary stereo files, and a fake external account. Automated tests covered independent bulk/control requests, close/inactivity, recovery of a lost acceptance response without another creation, historical linking, metadata, artwork, restart persistence, and the existing sync/extraction regressions.
The iPad Air 13-inch (M3), iOS 18.5 simulator walkthrough could not reach the
Sync page. An existing topology cell construction crash was fixed and both
Apple targets rebuilt successfully; launch then aborted in the simulator audio
service (_ReportRPCTimeout / AURemoteIO::Start) even after one simulator
restart. The agent did not complete an interactive simulator walkthrough.
The paired iPad Air 13-inch (M3) was unavailable in xcrun devicectl list devices
on 2026-10-11. On 2026-10-13, macOS and physical-iPad Release builds succeeded,
and the iPad app was installed and launched over Wi-Fi. The SoundCloud app was
registered, account access authorized, credentials saved in Mac Keychain, and
298 existing account tracks loaded successfully. Catalog startup was corrected
to skip iCloud-only files without downloading them; the focused catalog and
receiver tests passed.
On 2026-10-14, the user confirmed the outstanding manual walkthrough steps were already completed and instructed landing. Manual selection, title/image editing, native image picking, leaving/reopening, and foreground lifecycle acceptance are recorded as user-reported verification. This does not turn the earlier blocked simulator attempt into a passing agent run. No agent-initiated real publication was performed during verification. The receiver was stopped at the user’s request; landing does not rebuild, redeploy, or restart it.