diff --git a/README.md b/README.md index e1fcdc6..1180fb2 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,104 @@ -# ocpp-csms +# OCPP CSMS (OCPP 2.0.1.) -Charging Station Management System for electric vehicles - OCPP 2.0.1. compliant +Charging station Management system for electric vehicle charging stations. -## Functionality working so far: +Based on: OCPP-2.0.1 (Full protocol documentation: +[openchargealliance.org/downloads](https://www.openchargealliance.org/downloads/)) -- BootNotificationRequest and response -- Transaction and response +**_ Under development _** -## Quick start +## Working principle - Generate & save GCP credential JSON file with Pub/Sub and Firestore access into the following locations/filenames: - - device-service/credentials/PRIVATE.json - - websocket-service/credentials/PRIVATE.json - - user-service/credentials/PRIVATE.json - - transaction-service/credentials/PRIVATE.json +E.g. incoming BootNotificationRequest: - docker compose up --build +charging station -> websocket-service -> GCP Pub/Sub topic "BootNotificationRequest" -> device-service - Create charging station records on port 5000 (REST API description in the `device-service/http/api` folder). Make note of the unique station id you created +charging station <- websocket-service <- GCP Pub/Sub topic "BootNotificationResponse" <- device-service - Connect to port 3000 as a websocket client: - ws://{HOST}:3000/ocpp/{stationid} +## Functional features: + +- Implemented OCPP messages: + +| Implemented OCPP Messages | Microservice name | +| ----------------------------------------------------- | ------------------- | +| BootNotificationRequest, BootNotificationResponse | device-service | +| HeartbeatRequest, HeartbeatResponse | device-service | +| StatusNotificationRequest, StatusNotificationResponse | device-service | +| TransactionEventRequest, TransactionEventResponse | transaction-service | +| AuthorizeRequest, AuthorizeResponse | user-service | + +## Technical features: + +- microservice-based architecture +- GO: managing multiple websocket connections easily with goroutines, multithreading would be more tedious in many other languages +- Google Firestore for simple data persistence +- Google Cloud Pub/Sub for async messaging between services (using [watermill.io](https://github.com/ThreeDotsLabs/watermill)) +- REST API for managing charging station information (API description: [swaggerhub.com](https://app.swaggerhub.com/apis/gregszalay/ocpp_device_service/v2.0.0)) + +## Quick Start + +1. Create a **Google Cloud Platform project**. Follow the [google guide](https://cloud.google.com/resource-manager/docs/creating-managing-projects). + +2. Create a **service account** and create **JSON credentials** for it. Follow the [google guide](https://developers.google.com/workspace/guides/create-credentials) (see the _"Service account credentials"_ section). When you create the service account, under "select a role" choose `Pub/Sub Admin` and `Firebase Admin` (note: for production use, you may want to restrict these to lower roles, needs to be tested). + +3. Once you have the JSON credentials, place them in the following directories, under the name 'PRIVATE.json': + + - device-service/credentials/PRIVATE.json + - websocket-service/credentials/PRIVATE.json + - user-service/credentials/PRIVATE.json + - transaction-service/credentials/PRIVATE.json + +> Note: you can use the same service account and the same JSON credentials file in all places, or you can create separate ones for extra security if you want + +4. Create a Cloud Firestore database Follow the [google guide](https://firebase.google.com/docs/firestore/quickstart) + +5. In the **docker-compose.yml** file, replace `chargerevolutioncloud` name with the **project id** of your own GCP project. + +6. Install docker and docker-compose if you haven't already + +7. If you are deploying on a remote machine or VPS, **open** up port `3000` and port `5000` so you can access the system from your own machine. + +> Important: For actual deployment you should add a reverse proxy layer or some other security measure to protect your open port. A good place to start: [How To Deploy a Go Web Application with Docker and Nginx on Ubuntu 18.04](https://www.digitalocean.com/community/tutorials/how-to-deploy-a-go-web-application-with-docker-and-nginx-on-ubuntu-18-04) + +7. Build and run the docker images with + + docker compose up --build + + or + + docker compose up --build -d + + to hide console output + +8. The device service should now be running on `localhost:5000`. Use Postman or some other tool to send a post request and create a charging station (API description: [swaggerhub.com](https://app.swaggerhub.com/apis/gregszalay/ocpp_device_service/v2.0.0)) For example, you can send something like this in the request payload: + + POST: `localhost:5000/chargingstations/create` + + { + "id": "CS123", + "serialNumber": "5", + "model": "CS-5500", + "vendorName": "ChargerMaker Inc.", + "firmwareVersion": "1.8", + "modem": { + "iccid": "24", + "imsi": "24" + }, + "location": { + "lat": 41.366446, + "lng": -38.1854651 + } + } + + If this is successful, a collection named _"chargingstations"_ and a document named _"CS123"_ should have been created in the Firestore database of your project. + +9. The websocket service should be running on `localhost:3000`. Connect to port 3000 as a websocket client (use the station id you have created in the previous step): + + `ws://{HOST}:3000/ocpp/{stationid}` + + > Tip: Postman now supports websocket connections (beta version), but only on the Windows desktop app I believe. This could be useful for testing. Or you can have a look at my basic charging station simulator: [gregszalay/ocpp-charging-station-simulator](https://github.com/gregszalay/ocpp-charging-station-simulator) + +### To-do + +- secure websocket connections (wss) +- full implementation of all basic messages (reset, getconfig etc.)