In-House Swap Workflow

This is the workflow your full-time techs use to swap a battery pack on a vehicle in the field. It's built into the operator-app under the new Swap Queue tab.

The goal is a swap completing in 90 seconds or less, with no manual data entry, full audit trail, and a clear error message if anything's wrong.

Before You Go Out

Make sure you have:

• A vehicle to swap — pulled from the Swap Queue, with a real reason (low SoC, peak-shortfall prediction, or SoH rotation)
• A charged pack — either pulled from a station slot (then physically transported with you) or already in your van from a prior visit
• operator-app updated to the version with the Swap Queue tab (check Settings → About for build date)
• Network connectivity — the workflow is offline-tolerant for the swap itself, but the queue load and the final completion need a network round-trip

The Swap Queue Tab

Open operator-app and tap Swap Queue. You'll see a ranked list of vehicles needing a swap. Each row shows:

• Vehicle ID and model
• Current SoC and SoH (or "n/a" if SoH is unavailable for the IoT type)
• The reason the vehicle is in the queue:
  • Low SoC — battery percent below the threshold
  • Peak shortfall — model predicts the vehicle will fall below 20% during peak demand
  • SoH rotation — pack's SoH is below 60 and the vehicle is in a high-mileage slot
• Distance from your current location
• A Start Swap button

The list re-sorts in real time as your location changes and as the bounty engine refreshes.

Step 1: Start the Swap

Tap Start Swap on the vehicle you're standing next to.

The app opens an in-progress swap event server-side and unlocks the battery bay on the vehicle using the existing IoT command path (or the AXA e-key, for AXA-locked vehicles).

If the unlock fails, you'll see an error with the reason — usually a cellular signal issue on the vehicle. Wait a moment and retry, or switch to a manual key if available.

Step 2: Scan the Old Pack

The next screen asks you to scan the pack you're about to remove. Use the camera viewfinder; the QR code is the white-on-black sticker on the pack itself.

The app verifies that the QR you scanned matches the pack currently assigned to this vehicle. If you scanned a different pack — for example, you grabbed someone else's pack from the van — you'll see a "Pack not in vehicle" error. The swap doesn't proceed, the bay stays unlocked, and you can re-scan.

Step 3: Physically Replace the Pack

Pull the old pack out. Place the new charged pack in. The vehicle's standard pack-locking mechanism (key, latch, or push-in connector) is unchanged — Levy Swap doesn't modify the hardware.

Step 4: Scan the New Pack

Now scan the QR on the new pack you just installed.

The app verifies two things:

1. The pack is in charged state — if it's still charging or flagged maintenance, the swap rejects. You'll need to grab a different pack.
2. The pack isn't already installed in another vehicle — protects against double-install.

If both checks pass, you get a Complete button. If either fails, you get a clear error message naming the issue, and the swap rolls back cleanly.

Step 5: Complete

Tap Complete.

The app writes the swap_events row, decrements the station inventory if the new pack came from a station, updates battery_packs.vehicle_id for both the old and new packs, and recomputes the vehicle's expected range based on the new pack's SoH.

The battery bay re-locks automatically. The vehicle returns to whatever status it was in before the swap (usually available), and it disappears from the Swap Queue.

You should hear a confirmation tone and see a "Swap complete" toast. Total elapsed time for a clean swap is roughly 60–90 seconds.

Offline Behavior

If you lose cellular mid-swap:

• Before Start Swap — the queue is read from local cache; you can browse but not start. Move to better signal.
• After Start Swap, before Complete — the swap session is held server-side. The local app remembers what you scanned, and the Complete tap will queue locally and replay when you reconnect.
• If you reconnect and the vehicle has been swapped by someone else — the replay fails gracefully; you'll see a "Swap superseded" message and the queued attempt is discarded.

In practice, queue-and-replay is rare. The vast majority of swaps complete online in under a minute.

What the Old Pack Goes Into

After a successful swap, the old pack is in returned state and not in any station slot. Your options when you get back to the warehouse:

• Drop it into an empty station slot — set the slot to charging and plug it in
• If it shows a defect — set the slot to maintenance instead
• If SoH dropped below 40 during this ride window — the system has already routed the pack toward recycled; place it in your recycling bin and confirm from the dashboard

Reading a Swap Event

Every swap writes a swap_events row visible on:

• The vehicle's detail page → Service History
• The pack's detail page → Swap History (for both the removed and installed packs)
• The tech's own performance summary (visible to subaccount admins)

The row includes: who did the swap, when, where (GPS at completion), the duration, both pack IDs, and the station ID if the install pack came from one.

Common Issues

• "Pack not in vehicle" — see Step 2; you scanned the wrong pack
• "Pack is in use" — the installed-pack scan matches a pack already attached to another vehicle. Physically check what you put in the bay.
• "Pack not charged" — the new pack isn't in charged state. Get a different pack or wait for this one to finish charging.
• Unlock command timed out — the vehicle's cellular is unreachable; wait 60 seconds and retry, or use the manual key if your vehicle model supports it.
• Swap stuck in in_progress — if the app crashed between Step 1 and Step 5, the server-side session times out after 30 minutes. Restart and start a new swap.