FAQ¶

How does the attendant log in?¶

The attendant opens the app and logs in with their employee credentials (username and password). This ensures every swap is linked to an authorized attendant.

What if the customer's QR code won't scan?¶

Switch to the Enter Subscription ID fallback. The attendant can type the customer's subscription ID manually. If the subscription is still not found, verify the ID with the customer.

How does the app read the battery?¶

The app scans the battery's QR code to identify it, then connects via Bluetooth Low Energy (BLE). It reads two services:

ATT service — provides the battery ID
DTA service — provides the remaining energy (kWh)

What if the Bluetooth connection fails?¶

Ensure Bluetooth is enabled on the attendant's device and that the battery is within range. Retry the connection. If the problem persists, restart the app or try a different battery.

How is the swap cost calculated?¶

The cost formula is:

energy_difference = floor(new_energy - old_energy, 2)
net_energy        = energy_difference - quota_remaining
cost              = net_energy × rate_per_kWh

The energy difference is floored to 2 decimal places. The customer's prepaid quota is subtracted before applying the per-kWh rate.

What happens if the customer's quota covers the full cost?¶

If the quota covers the entire energy difference, the net amount due is zero. The attendant can complete the swap directly — Step 5 (Payment) is skipped and the flow goes straight to Step 6 (Done).

What payment methods are supported?¶

Payment is collected via M-Pesa using one of two methods:

Scan QR code — the attendant scans the customer's M-Pesa payment QR
Enter receipt manually — the attendant types the M-Pesa confirmation code

How are transactions reported to the backend?¶

After payment is confirmed (or skipped due to quota), the app sends two MQTT messages to the backend:

A payment event with the amount, receipt code, and timestamp
A service event with the battery swap details (old battery, new battery, energy, customer subscription)

Can the attendant go back to correct a mistake?¶

Yes. Use the Back button at any step to return to the previous step. Selections and readings are preserved until changed.

Does the flow work offline?¶

BLE-based battery scanning and energy readings work without internet. However, the customer lookup (Step 1) and payment/MQTT reporting (Step 5) require network connectivity.

Can the attendant start another swap immediately?¶

Yes. After completing a swap in Step 6 (Done), the attendant taps New Swap to return to Step 1 and begin a new transaction.