Skip to content
Polaris Express Docs

Register a new charger

You’re standing up a new charger and need it to appear in the Devices listing so customers can start sessions on it. There are two paths: the charger speaks OCPP and announces itself through SteVe, or the unit can’t speak OCPP and you need a placeholder record so the rest of Polaris Express (billing, tariffs, location metadata) has something to attach to.

Prerequisites

Section titled “Prerequisites”
  • Admin role on the Polaris Express console. Without it, /admin/devices returns 403 Forbidden.
  • Physical or remote access to the charger’s network configuration (OCPP endpoint URL, chargeBoxId).
  • SteVe reachable from the console host. The Devices page fetches charger rows from a cache populated by SteVe; if SteVe is down you’ll see a “Couldn’t reach one of the device sources” banner.
  • A ChargeBox ID agreed with whoever provisions the hardware. This is the identifier the charger sends in its OCPP BootNotification.

Procedure

Section titled “Procedure”

Path A — OCPP charger (managed)

Section titled “Path A — OCPP charger (managed)”

  1. Confirm the charger's OCPP endpoint

    Point the charger at the SteVe OCPP endpoint your environment uses. The exact URL is environment-specific; check with your platform owner. The charger must use the chargeBoxId you agreed on — SteVe rejects boot notifications from unknown IDs unless auto-registration is enabled in SteVe’s config.

    Charger configuration screen showing OCPP endpoint and chargeBoxId fields.

  2. Power on the charger and wait for boot

    Once the charger boots and successfully sends BootNotification to SteVe, SteVe records it as a charge box. Polaris Express pulls charge boxes from SteVe via GET /api/charger, which proxies to the SteVe client.

    GET /api/charger

  3. Open the Devices page

    Go to Admin → Devices (/admin/devices). The page lists OCPP chargers and NFC scanners together in one grid, sorted by last-seen descending, so a freshly-booted charger appears near the top.

    Admin Devices page with the new charger card visible at the top of the grid.

  4. Filter to chargers if the grid is busy

    Use the Type filter in the filter bar and select Charger. The URL updates to ?type=charger. You can further narrow by management mode using Mode → OCPP.

Path B — Unmanaged charger

Section titled “Path B — Unmanaged charger”

Use this when the unit doesn’t speak OCPP but you still need it represented in Polaris Express (for example, a legacy AC unit you bill through a flat tariff).

  1. Open the Devices page

    Go to Admin → Devices.

  2. Click Add unmanaged charger

    In the page header, click Add unmanaged charger. This is only visible to admins and takes you to /admin/devices/new-unmanaged.

    Devices page header showing the Add unmanaged charger button.

  3. Fill in the unmanaged charger form

    Complete the form on /admin/devices/new-unmanaged.

  4. Verify it appears with the Unmanaged badge

    Back on /admin/devices, set Mode → Unmanaged to filter the grid. The new record should appear with managementMode: "unmanaged". The stat strip’s Unmanaged total increments by one.

Verify

Section titled “Verify”

  • Devices grid — The charger appears at /admin/devices. For OCPP chargers, the card shows the ChargeBox ID, last status, and last-seen timestamp.

  • Stat strip — The Chargers total at the top of the page increments by one. If the unit is online, the Online total also increments. A charger is considered online when its normalised status is anything other than Offline.

  • API check — GET /api/charger returns the new charge box in the rows array. Use ?limit=10&skip=0 if you want pagination; without pagination params the response returns the full list under both rows and the legacy chargeBoxes key.

    GET /api/charger?limit=10

If something goes wrong

Section titled “If something goes wrong”

The charger doesn’t appear in the grid

Section titled “The charger doesn’t appear in the grid”
  • Confirm the charger has actually booted and reached SteVe. If SteVe never received a BootNotification, Polaris Express has nothing to cache.
  • Check the page for the amber banner reading “Couldn’t reach one of the device sources — showing partial results.” This means the charger query failed; the grid renders scanners only. Retry after confirming SteVe is healthy.
  • The Devices listing is capped at 200 rows per source. If you have more than 200 chargers, use the filter bar to narrow the result set.

The charger boots but SteVe rejects it

Section titled “The charger boots but SteVe rejects it”

Boot rejections happen at the SteVe layer, not Polaris Express. Check SteVe’s logs for the chargeBoxId. The most common cause is the ID not being pre-registered in SteVe with auto-registration disabled.

The Add unmanaged charger button is missing

Section titled “The Add unmanaged charger button is missing”

You’re not signed in as an admin. The header action only renders when state.user?.role === "admin".

Audit and reversibility

Section titled “Audit and reversibility”
  • Unmanaged charger creation writes a new row to chargers with managementMode = "unmanaged". To reverse, delete or soft-delete the row through whichever admin surface handles unmanaged charger lifecycle.
  • OCPP charger registration is owned by SteVe, not Polaris Express. Removing the charger from the listing means removing it from SteVe; the Polaris Express cache will follow.
  • The DB CHECK constraint on chargers.capabilities (migration 0039) guarantees every charger row includes the charger capability, so a misconfigured insert won’t quietly produce a record that fails to render its capability pill.
Section titled “Related”