Pipelet OCPP Broker – Developer & Operations Guide

Product overview

The Pipelet OCPP Toolkit provides a full stack for managing EV charge points via the Open Charge Point Protocol (OCPP) and auxiliary services. It combines a WebSocket broker, dashboard, REST API, service agent, diagnostic server, and a simple OCPP server for testing.

Architecture

Getting Started

1. Clone: git clone https://github.com/pipelet/Pipelet-OCPP-Broker.git
2. Python: Install Python 3.10+ and virtualenv.
3. Create venv: python3 -m venv .venv && source .venv/bin/activate
4. Install deps: pip install -r requirements.txt
5. Configure: Copy config.json (or config.multi_listener.example.json) and fill TLS, database, and token values.
6. Seed DB: Apply required SQL files (see Installation).
7. Run services (examples):
   • python pipelet_ocpp_broker.py
   • python pipelet_rest_api.py
   • python pipelet_ocpp_server.py
   • python pipelet_dashboard.py
   • python pipelet_diagnostic_server.py
   • python pipelet_service_agent.py
8. Tokens & environment: Export bearer tokens for dashboard/REST calls and optional OCPI forwarding token.

Installation & prerequisites

Configuration files

• config.json: main settings (broker listeners, dashboard port, MySQL, Hubject, OCPI, logging, TLS paths). Defaults include WebSocket ping_interval/ping_timeout.
• config.multi_listener.example.json: sample for multiple WebSocket listeners.
• Environment variables: optional overrides for ports, OCPI endpoints, and alert webhooks (see README).

Deployment

[Unit]
Description=Pipelet OCPP Broker
After=network.target mysql.service

[Service]
User=pipelet
WorkingDirectory=/opt/pipelet
ExecStart=/opt/pipelet/.venv/bin/python pipelet_ocpp_broker.py --config /opt/pipelet/config.json
Restart=on-failure
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=multi-user.target

TLS & certificates

• Use system certificates or Let’s Encrypt paths (e.g., /etc/letsencrypt/live/<host>/).
• Set ocpp_proxy_ssl or per-listener use_ssl; provide certfile/keyfile.
• For client-authenticated flows (Hubject), set require_client_certificate and client_verify_header.

Deployment flow

1. Provision server with Python, MySQL client, and firewall rules for WebSocket, REST, dashboard, and diagnostics ports.
2. Install code under /opt/pipelet (or similar) and set permissions for TLS keys.
3. Apply SQL migrations and import any seed data.
4. Place config.json with correct hostnames, tokens, and certificates.
5. Enable and start systemd units; verify with systemctl status.
6. Add cron for meter-value triggers if needed (see docs/trigger_meter_values_cron.md).

Operations

Working with services

• Broker: exposes WebSocket endpoints, supports per-connection ping_enabled query override.
• OCPP server: provides TriggerMessage helpers (boot, meter values, status) and PNC actions.
• Dashboard: UI + JSON APIs for redirects, OCPI settings, and monitoring.
• Service agent: MQTT-based config checks; ensure broker topics are accessible.
• Diagnostic server: HTTP/FTP uploads for GetDiagnostics outputs.

API usage for external developers

REST endpoints are documented in API_OVERVIEW.md and the Postman collection. Key paths are summarized below with sample curl calls.

DataTransfer helper (REST API)

curl -X POST http://HOST:9750/api/datatransfer \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"stationId":"CP-1001","vendorId":"ACME","messageId":"Ping","data":"hello"}'

Response shape:

{
  "payload": {...},           // echoed request payload
  "ocpp_response": {...}      // raw station reply
}

Plug&Charge OCPP commands (OCPP server)

curl -X POST http://HOST:9751/api/pnc/ocpp-command \
  -H "Content-Type: application/json" \
  -d '{
    "station_id": "STATION",
    "action": "get_15118_ev_certificate",
    "exiRequest": "BASE64",
    "iso15118SchemaVersion": "urn:iso:15118:2:2013:MsgDataTypes"
  }'

PNC certificate management

curl -X POST http://HOST:9751/api/pnc/ocpp-certificates \
  -H "Content-Type: application/json" \
  -d '{
    "station_id": "STATION",
    "action": "install_certificate",
    "certificateType": "CSMSRootCertificate",
    "certificate": "BASE64_CERT"
  }'

Redirect management (dashboard/REST)

curl -X POST http://HOST:9750/api/op_redirects \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "/ocpp16/CP-1001",
    "ws_url": "wss://backend.example/ws",
    "activity": "allow",
    "mqtt_enabled": 0,
    "ping_interval": 60
  }'

Working with OCPP & OCPI

Troubleshooting basics

• Connection drops: Check TLS cert paths, ping_interval/ping_timeout settings, and firewall rules on WebSocket ports.
• Broker routing: Verify op_redirects entries via dashboard or /api/op_redirects; ensure activity is set to allow.
• Authentication: Confirm bearer tokens for dashboard/REST; check OCPI toggle state when forwarding is expected.
• Database: Validate MySQL credentials in config.json and run missing schema files from sql/.
• Diagnostics: Use /diagnostics listing and ensure FTP port is reachable.
• Hubject/PNC: Ensure client certificate paths and Hubject URLs are populated in config.json.

Security considerations

• Store bearer tokens and Hubject/OCPI secrets outside the repo (env vars or vaulted config); avoid committing config.json with real secrets.
• Use TLS on all public endpoints; prefer force_tls12 for stricter compatibility.
• OCPI forwarding remains disabled until explicitly toggled to avoid unintended CDR pushes.
• Restrict dashboard and REST API via firewall, reverse proxy auth, and strong tokens.
• Limit database users to least privilege; rotate credentials regularly.
• Review diagnostic uploads for sensitive data before sharing.

Contact & support

Questions or incidents? Add your operations contact details here (email, phone, on-call chat). For API help, provide partner/token request procedures and escalation paths.