Chapter 5

Phase 2: Implementation

Overview

5.1 The Phase 2 surface: chargers, sessions, telemetry, conformance, array

Phase 1 of WIA-COMM-008 defined the data envelopes that describe a wireless charger, a receiver and a charging event. Phase 2 makes those envelopes reachable over HTTPS and WebSocket. The surface is small and is organised around the physical objects a charging deployment actually contains: the charger (a transmitter with one or more coils), the session (one receiver being powered by one charger), the telemetry stream (power, temperature and alignment while energy flows), the conformance record (what the charger has been certified to do), and the array (a charger that serves several devices at once).

The seven calls below cover the whole life of a charger and its sessions. Every one of them is also discoverable through the convention at /.well-known/wia-wireless-charging, so a client that knows only the host name can find the rest.

POST /wireless-charging/v1/chargers              # register charger
GET  /wireless-charging/v1/chargers/{id}         # fetch charger record
POST /wireless-charging/v1/sessions              # start charging session
GET  /wireless-charging/v1/sessions/{id}/state   # current session state
POST /wireless-charging/v1/sessions/{id}/stop    # stop session
WS   /wireless-charging/v1/telemetry/stream      # power/temperature telemetry
GET  /wireless-charging/v1/conformance/{id}      # WPC/AirFuel/J2954 cert status

Two further groups sit beside the core: an interoperability-testing API for recording charger-and-receiver test runs, and webhook delivery for session and foreign-object events. Both are covered later in this chapter. The design intent is that an operator, a device maker and a test house can all work from the same records instead of exchanging spreadsheets and log files.

Technical Foundation

5.2 From coil physics to session state

Wireless charging moves energy across an air gap through a magnetic field. In inductive coupling, a transmitter coil and a receiver coil sit close together and behave like a loosely coupled transformer. In magnetic resonance, both sides are tuned to the same frequency, which tolerates larger gaps and looser alignment at the cost of more demanding electronics. The specification treats the two Qi (WPC) and AirFuel Alliance families as the practical embodiments of these ideas. For AirFuel it names a 6.78 MHz resonant frequency with a ±5% tolerance and BLE for device pairing and control.

These physical facts shape the API in a few direct ways. First, energy transfer needs a control channel. A Qi receiver tells the transmitter how much power it wants by modulating the load it presents, which is in-band ASK signalling. An AirFuel receiver uses a BLE side channel. The telemetry stream computes receiver power from whichever channel is in use, so the two families produce the same kind of event even though their signalling differs. Second, the receiver's identity is established before power flows. The session request carries a receiver descriptor derived from the device's NFC-detected or BLE-discovered identity, and the charger's compatibility matrix is checked against it. A Qi-only charger rejects an AirFuel-only receiver, and the reverse holds, unless the charger advertises multi-protocol support.

Third, a charging session is a sequence of physical phases, not a single request and response. The session record therefore carries an explicit state machine:

StateMeaning in the charging process
negotiatingReceiver identity and requested power are being matched to charger capability
rampingPower is being brought up toward the agreed envelope
chargingSteady energy transfer
topping-offFinal stage as the battery approaches its target
completeTarget state-of-charge reached
aborted-fodStopped because a foreign object was detected
aborted-thermalStopped because a temperature threshold was crossed
aborted-misalignmentStopped because alignment was lost beyond policy

The three aborted states are worth attention. They record why charging stopped, using the three hazards that dominate wireless-power engineering: metal heated by the field, excess heat in the coils or device, and a receiver that has drifted off the transmitter. A client does not have to guess the cause from a generic failure code.

Market Analysis

5.3 Three certification families and the compatibility problem

The wireless-charging market is fragmented by protocol rather than by product category. Qi, maintained by the Wireless Power Consortium, is the family most people meet in phones and accessories. The AirFuel Alliance covers resonant charging, including zone-style chargers. For electric vehicles, SAE J2954 defines the conformance framework, expressed in the specification as WPT 1, 2 and 3 tiers with optional MF-MF, MF-FF, FF-MF or FF-FF combinations. A single buyer may own devices from more than one of these worlds, and a single operator, such as a hotel, a car-park or an office, may need to serve all of them.

That is why Phase 2 puts compatibility checking at session creation and certification status behind a dedicated endpoint. Without them, an operator learns about incompatibility only when a user's phone fails to charge. With them, the charger can refuse a mismatched receiver up front and say why. The conformance record also gives purchasers a machine-readable way to compare chargers instead of relying on packaging claims.

The interoperability API addresses the second market problem, which is that certification of each side does not guarantee that a particular pair works well together. Test runs are registered per charger and receiver pair, and the aggregate results are published as a matrix at GET /interop-tests/matrix, broken down by charger class and receiver class. Over time such a matrix reveals patterns, such as one charger class that consistently struggles with one receiver class, that individual test reports hide.

Industry Applications

5.4 Where the interfaces earn their keep

Multi-coil array chargers. Spatial-freedom Qi chargers at 15 to 22 W, AirFuel zone chargers and multi-charger desks serve several devices from several coils. For these, the array API exposes the active-device list together with each device's coil allocation, its power envelope and the cross-talk envelope between neighbouring coils. Cross-talk matters because adjacent fields can disturb one another's signalling and efficiency. An operator who can see it can diagnose a desk where one device charges slowly whenever another is placed beside it.

Scheduling is also part of the array interface. Operators can prioritise charging slots from declared device priorities, for example low-battery devices first, or a device the user has tagged as a priority. This is a policy layer on top of physics: the coils set the limit on what can be delivered, and the schedule decides who gets it when demand exceeds capacity.

Public and shared installations. A café table or airport seat sees many unrelated users and devices. The session request includes a user-consent envelope, so the record of who agreed to what travels with the session. The state machine and the alarm events let a venue's operations team distinguish a user who walked away (complete or a manual stop) from a charger that shut itself down for safety.

Vehicle charging. For EV deployments the relevant record is the SAE J2954 tier and combination in the conformance envelope. Because vehicle charging involves much more power than a desk pad, the thermal and foreign-object states carry more operational weight, and the webhook channel described in section 5.6 is how a fleet operator learns of such an event without polling.

Manufacturers and safety teams. Foreign-object detection events are delivered with a per-detection root-cause trace and a recommended remediation. Post-market-surveillance teams can use them as field evidence about how detection behaves with real objects such as coins, keys, card clips and phone-case metal, rather than only with the standard test objects used in certification.

Standards Compliance

5.5 Conformance records and interoperability test runs

The conformance endpoint returns a charger's certification envelope in one place. It brings together records that otherwise live with different bodies:

ElementWhat it records
WPC Qi certificationThe Qi certification number
AirFuel Alliance certificationThe certification number, where applicable
SAE J2954 tierWPT 1/2/3, with the optional MF/FF combinations
EMC test reportReference per CISPR 11, FCC 47 CFR Part 15, ETSI EN 300 330 and EN 301 489
EMF safetyConformance per ICNIRP and IEEE C95.1

The groupings follow the way the underlying certification programmes divide the work. Qi certification tests cover power transfer at the BPP and EPP levels, communication packet structure and timing, efficiency against minimum targets, detection of standard metal objects, EMI/EMC, and safety limits on temperature, overcurrent and overvoltage. AirFuel tests cover the resonant frequency, BLE pairing and control, simultaneous multi-device charging, and EMF exposure and thermal limits. The WIA record does not replace any of these programmes. It points to their outcomes so that other systems can consult them.

The interoperability API extends the same idea to test execution. POST /interop-tests registers a run between a charger and a receiver. The request names the test catalogue entry from the relevant WPC, AirFuel or SAE test plan. It also carries the test conditions (alignment offsets, ambient temperature and the input-voltage profile) and the identifier of the test house, which is expected to be accredited under ISO/IEC 17025. The response gives a pass, fail or advisory verdict for each test with a diagnostic trace. The "advisory" outcome is useful in practice: it lets a lab flag marginal behaviour, for instance a result that passes at nominal alignment but degrades at an offset, without declaring a failure.

Cross-platform testing in the specification asks for more than a single bench setup: multiple charger brands, different power levels, various alignment offsets, and temperature extremes from -10°C to 45°C. Recording the conditions with each result is what makes a later comparison meaningful.

Implementation Considerations

5.6 Limits, alarms and webhook delivery

Rate limits in this API are not only about server load. The session-management limit of 10 sessions per minute per charger exists specifically to defeat coil-thermal abuse. A client that starts and stops sessions rapidly could cycle a coil hard without any individual session ever looking unusual. Limiting it at the charger level protects the hardware. Other limits are more conventional:

ScopeLimit
Charger-record endpoints1000 requests/hour authenticated; 5000 for trusted partners
Session management10 sessions/minute per charger
Telemetry WebSocket50 simultaneous subscriptions per credential
Bulk export (GET /chargers?after=cursor&limit=N)Maximum 200 per page

Telemetry. The stream multiplexes events for many sessions, and subscribers filter by session identifier. Each event can include instantaneous transmitter power, receiver power, efficiency, transmitter and receiver coil temperatures, FOD status, an alignment estimate (X/Y offset in millimetres, plus tilt where the receiver can sense it) and state-of-charge progress. Comparing transmitter and receiver power is the essence of foreign-object detection, because power that leaves the transmitter but does not arrive is going somewhere, possibly into a piece of metal. The broker raises alarm events on FOD detection, on thermal threshold crossings and on alignment loss beyond policy. These alarms correspond to the three aborted session states, so a dashboard can show the warning before the session ends and the cause after it.

Webhooks. Operators who do not want to hold a socket open can subscribe to lifecycle events (negotiating, ramping, charging, complete, aborted) and FOD detections. The payload has the same shape as the corresponding GET response and is signed by the WIA tenant key, so a receiver can verify it. Delivery is retried with exponential backoff for up to 24 hours before the broker logs a permanent-failure event for operator review. An implementer should therefore make the webhook handler idempotent and should treat a permanent-failure log entry as a reason to reconcile state through a GET call rather than assume that nothing happened.

A reasonable bring-up sequence is to start the reference container with mock data, run the conformance suite against it, and then replace the mock backend one endpoint at a time. The charger and conformance records are the safest to connect first. Sessions and telemetry should follow only after the charger hardware's own protection logic has been confirmed to operate independently of the API. The API reports and requests; it should never be the only thing standing between a coil and overheating.

A quick check of a live session needs nothing beyond the documented paths:

curl -s "$HOST/wireless-charging/v1/sessions/$SESSION_ID/state"
curl -s -X POST "$HOST/wireless-charging/v1/sessions/$SESSION_ID/stop"

Future Outlook

5.7 Where the interface can grow without breaking

Several features in the current surface are marked optional, and they point to where deployments are likely to extend. Tilt sensing appears in the alignment estimate only where the receiver supports it, so richer positioning data can arrive as more receivers report it. Array chargers already expose cross-talk and coil allocation, which gives a basis for smarter scheduling policies. The interoperability matrix grows more informative with each registered run. Multi-protocol chargers, which Phase 2 already recognises through the compatibility check, reduce the number of mismatches that arise in the first place.

Growth is governed by a compatibility rule. Throughout the 1.x line, every existing endpoint and envelope must stay reachable and keep its documented behaviour. Hosts may add optional fields and new envelopes but may not remove existing ones, and a breaking change needs a major version with a 12-month deprecation window. For an integrator, the practical consequence is to read the fields they need and ignore the ones they do not recognise, so that a charger that adds data tomorrow does not break a client written today.

Review Questions

5.8 Questions for review

  1. A Qi-only charger receives a session request from an AirFuel-only receiver. What does the specification say should happen, and under what condition would the outcome differ?
  2. Explain why transmitter power and receiver power are both carried in the telemetry stream. What does a growing gap between them suggest, and which session state might follow?
  3. Why is the session-start limit set per charger rather than per client? What failure mode is it meant to prevent?
  4. A webhook endpoint was unreachable for more than a day. What does the broker do, and how should the operator recover an accurate view of session state?
  5. List the three aborted-* states and match each to the physical hazard it represents.
  6. An interoperability run passes at nominal alignment but shows degraded behaviour at an offset. Which verdict is most appropriate, and which part of the request records the offset?
  7. Why does an array charger need to expose a cross-talk envelope in addition to per-device power envelopes?

Summary

5.9 Summary and the step toward Phase 3

Phase 2 turns the physical vocabulary of wireless charging into an interface. Chargers and receivers are matched through a compatibility check. Each session moves through a named state machine whose failure states record the hazard that ended it: foreign metal, heat or misalignment. Telemetry exposes transmitter and receiver power, efficiency, coil temperatures, FOD status and alignment, so that a divergence is visible while it develops. Conformance and interoperability records bring Qi, AirFuel, SAE J2954, EMC and EMF results into one place. Rate limits and signed, retried webhooks protect the hardware and keep operators informed even when connections fail.

Everything in this chapter assumed that the caller and the charger already trust each other, that the charger is reached directly and that the API is the only boundary involved. Real deployments cross organisational lines: a venue operator, a device manufacturer, a test house and a fleet owner may each run their own systems. The next chapter, on Phase 3, takes the same envelopes and wraps them in protocol exchanges designed to cross those trust boundaries. It covers how identity, signing and audit records are carried between parties so that a session started in one organisation's system can be understood and verified in another's.