wocha/ocpp-proxy-alert repository overview

⁠OCPP-Proxy-Alert

WebSocket OCPP proxy that forwards charge point traffic to one or two upstream OCPP servers, with an optional alert system for connection events and StatusNotification messages.

⁠Features

• WebSocket proxy for OCPP JSON messages (CALL, CALLRESULT, CALLERROR).
• One or two upstreams: mandatory primary (PRI), optional secondary (SEC).
• Client CALL messages are forwarded to all connected upstreams.
• Only the primary upstream response is relayed back to the client for client-originated CALLs.
• Each upstream can send CALL messages directly to the client.
• If a client reconnects with the same ID as an existing connection, the old connection is closed.
• Client messages are buffered if no upstream is connected yet, and flushed automatically once at least one upstream is ready.
• Automatic upstream reconnection with exponential backoff (up to 10 attempts, max delay 60 s).
• If all upstreams disconnect, the client connection is closed gracefully.
• Configurable mapping between technical client IDs and human-readable names (clientIdToHuman.json).
• Notifications via email (SMTP via Nodemailer) and/or Pushover.
• Configurable log level via Winston⁠.

⁠Requirements

• Node.js >= 18

⁠Install

npm install

or by Docker deployment⁠

⁠Quick start

1. Edit config/config.json with your URLs and settings.

2. Run the proxy:

   node src/index.js
   

   Copy

⁠Configuration

⁠Main settings

⁠Client connection

The client must connect to a path of the form ws://<host>:<port>/<clientId> where <clientId> is an alphanumeric string (letters, digits, underscores, hyphen). Any connection with an invalid path is rejected immediately.

The proxy then opens an upstream connection to <primaryUrl><clientId> (and <secondaryUrl><clientId> if configured).

⁠Human-readable client names

The file config/clientIdToHuman.json maps a technical client ID to a display name used in notifications:

{
  "STATION01": "North Parking — Charger 1",
  "STATION02": "South Parking — Charger 2"
}

If the file is missing or a given ID is not listed, the raw client ID is used.

⁠Notifications

Notifications are controlled by the notify object. Each event is enabled individually by setting its value to true.

⁠Available events

⁠Notification channels

To enable email and/or Pushover, add the corresponding blocks inside notify:

{
  "notify": {
    "connectedToProxy": true,
    "cpStatusFaulted": true,
    "email": {
      "from": "[email protected]",
      "to": "[email protected]",
      "transporter": {
        "host": "smtp.example.com",
        "port": 587,
        "secure": false,
        "auth": { "user": "smtp-user", "pass": "smtp-pass" }
      }
    },
    "pushover": {
      "userKey": "YOUR_USER_KEY",
      "appToken": "YOUR_APP_TOKEN"
    }
  }
}

If a channel is missing or misconfigured, it is disabled at startup and a warning is logged.

⁠Notes on email.transporter

Email is sent via Nodemailer⁠. The email.transporter object must follow the same format as the argument to nodemailer.createTransport({}).

• Sendmail transport⁠ configuration
• SMTP transport⁠ configuration
• Simplified setup using well-known services⁠

⁠Full configuration example with Gmail

{
  "logLevel": "info",
  "primaryUrl": "ws://ws1.ocpp.fr/",
  "secondaryUrl": "ws://ws2.ocpp.fr/",
  "proxy": { "host": "0.0.0.0", "port": 9000 },
  "notify": {
    "connectedToProxy": false,
    "disconnectedFromProxy": false,
    "connectedToUpstream": false,
    "disconnectedFromUpstream": false,
    "cpStatusAvailable": false,
    "cpStatusUnavailable": false,
    "cpStatusFaulted": true,
    "conStatusAvailable": false,
    "conStatusPreparing": false,
    "conStatusCharging": true,
    "conStatusSuspendedEVSE": false,
    "conStatusSuspendedEV": false,
    "conStatusFinishing": false,
    "conStatusReserved": false,
    "conStatusUnavailable": false,
    "conStatusFaulted": true,
    "conStartTransaction": true,
    "conStopTransaction": true,
    "email": {
      "from": "[email protected]",
      "to": "[email protected]",
      "transporter": {
        "service": "Gmail",
        "auth": { "user": "smtp-user", "pass": "smtp-pass" }
      }
    },
    "pushover": {
      "userKey": "YOUR_USER_KEY",
      "appToken": "YOUR_APP_TOKEN"
    }
  }
}

⁠Run

node src/index.js

Graceful shutdown on SIGINT / SIGTERM (all client and upstream connections are closed before exit).

⁠Architecture

Client (OCPP charge point)
       │
       ▼
  OcppProxy  ──── OcppRouter (message routing, response filtering)
       │
       ├──► UpstreamConnection PRI  ──► Primary server
       └──► UpstreamConnection SEC  ──► Secondary server (optional)