CitrineOS 1.x to 2.x
Prior to upgrading to version 2.x, if you have existing data, do not run the Sequelize migrations as they may cause data loss.
You can turn off the migrations by setting the DB_STRATEGY to "none" in the docker-compose or entrypoint.sh.
Breaking Changes#
[DATABASE] Station ID -> OCPP Connection Name#
Charging Station "human-readable" identifiers are now stored in the ocppConnectionName column, while the id column
became the dedicated database serial integer identifier. As a result, every related entity to Charging Stations had to
be updated so that their stationId references the Charging Station's id integer column, rather than the
ocppConnectionName string column. All related indexes were also updated to reflect this change.
If you have skipped the migration due to existing data, as warned above, you will need to ensure that all tables
referencing stationId as the Charging Station's string value ocppConnectionName are updated to reference the proper
Charging Station id serial integer column.
You can find an example of how to craft the necessary SQL in the migration file apps/ocpp-server/db/migrations/20260427000000-rename-charging-station-columns.ts.
Note that if you are on version 1.9.x, you can follow the example of the migration above, as it runs against the
stationPkId column. If you are on a version prior to 1.9.x, the column to migrate will be stationId.
OCPP Connection Name in endpoints#
Any query parameters previously referencing stationId now use ocppConnectionName instead. You can see the updated API definitions here.
Station ID foreign key#
In addition to the rename, any relevant tables where they need to refer back to a charging station nows reference the
charging station by the generated database id stored in the column stationId, rather than using ocppConnectionName,
to ensure the data is properly linked together.
[DATABASE] Additional OCPPMessage columns#
This is not a breaking change if you're not reliant on a particular OCPPMessage structure. OCPPMessage deprecated the
state and message columns (though they are still written to for backwards compatability) in favor of type, payload,
and raw. state was replaced by type because the latter stores the actual OCPP Message Type. message was replaced
by payload (the parsed payload) and raw (the raw OCPP message received).
[DATABASE] Table Partitions#
The OCPPMessages and Transactions tables now use PostgreSQL Table Partitioning to manage their data loads. OCPPMessages
uses a one-week partition, while Transactions uses a one-month partitions. You can read more about the partitioning
here.
[CONFIGURATION] System Configuration is no longer persisted#
Configurations for CitrineOS used to come from three places:
- The
SystemConfigin src/config/envs/{local,docker}.ts (selected by APP_ENV) - A persisted
config.jsonin file storage BOOTSTRAP_CITRINEOS_*/CITRINEOS_*env vars
In 2.x configurations are now determined via non-persisted environment variables, represented by the Zod schema in
packages/types/src/config/types.ts. Therefore, your old config.json settings will not be picked up; you will have
to port them to environment variables manually. Additionally, websocket configurations were moved into their own file
called websocket-servers.json.
In general, this is how you migrate to the new environment variables if you already had an old environment:
- Delete your persisted config.json. The Zod schema defaults are the old local-dev values.
- Rename your environment variables. Use one underscore per level, not per word, drop the BOOTSTRAP_ prefix, and always
prefix with
CITRINEOS_. For example,timeouts.maxCallLengthSecondsbecomesCITRINEOS_TIMEOUTS_MAXCALLLENGTHSECONDS. Unknown vars now log a warning at startup instead of silently doing nothing. - Move util.networkConnection.websocketServers into websocket-servers.json. The field names are the same, but the validation is stricter: id/host/port/protocols/securityProfile required, unique ids, exactly one of tenantId or dynamicTenantResolution.
utilandmodulesconfigs were flattened. Everything moves up a level and is keyed by what it configures, not which module reads it (modules.transactions.costUpdatedIntervalbecomestransactions.costUpdatedInterval). The three per-protocol boot blocks collapse into one shared ocpp block — so 1.6 and 2.0.1 chargers can no longer be booted differently via config.- Per-module OCPP action lists, per-module host/port, modules.tenant.ocppRouterBaseUrl, and ocpiServer (OCPI is its own app) were all completely removed as configs.
For more information on the changes and help on migrating your configuration, you can check [here] (https://github.com/citrineos/citrineos-core#migrating-from-the-old-configuration).
[ROUTER] OCPP Router sends to Messages Module#
This is not a breaking change if you haven't made changes to the OCPP Router. To offload some of the business logic out of the "hot path" of the router, a new module called "Messages" was created to handle such logic. You can read more about its purpose and architecture here.
[API] Endpoint Paths#
All Data APIs annotated with @AsDataEndpoint were moved into their own module Api and endpoints declared into their
own files, organized by protocol and module. You can find the new module in packages/ocpp/src/apis. If you rely on
specific API paths, see below:
Data / Command Endpoints
In 1.x, these were @AsDataEndpoint routes under /data/<module>/<namespace>. In 2.x, they're registered in packages/ocpp/src/apis/register.ts under /commands, /ocpprouter, /permissions, /dev or /evdriver.
| 1.x | 2.x | Status |
|---|---|---|
PUT /data/configuration/boot |
PUT /commands/bootConfig |
Moved |
GET /data/configuration/boot |
GET /commands/bootConfig |
Moved |
DELETE /data/configuration/boot |
DELETE /commands/bootConfig |
Moved |
POST /data/configuration/password |
POST /commands/setStationPassword |
Moved |
GET /data/configuration/serverNetworkProfile |
GET /commands/stationNetworkProfile |
Moved |
DELETE /data/configuration/serverNetworkProfile |
DELETE /commands/stationNetworkProfile |
Moved |
GET /data/evdriver/localListVersion |
GET /commands/localListVersion |
Moved |
PUT /data/monitoring/variableAttribute |
PUT /commands/provisionStationVariables |
Moved |
GET /data/monitoring/variableAttribute |
GET /commands/stationVariables |
Moved |
DELETE /data/monitoring/variableAttribute |
DELETE /commands/stationVariables |
Moved |
GET /data/transactions/transaction |
GET /commands/transaction |
Moved |
PUT /data/transactions/tariff |
PUT /commands/tariff |
Moved |
GET /data/transactions/tariff |
GET /commands/tariff |
Moved |
DELETE /data/transactions/tariff |
DELETE /commands/tariff |
Moved |
PUT /data/certificates/rootCertificate |
PUT /commands/installRootCertificate |
Moved |
POST /data/certificates/uploadExistingCertificate |
POST /commands/uploadExistingCertificate |
Moved |
POST /data/certificates/regenerateExistingCertificate |
POST /commands/regenerateCertificate |
Moved |
POST /data/certificates/certificateChain |
POST /ocpprouter/certificateChain |
Moved |
PUT /data/certificates/tlsCertificates |
— | Removed |
POST /data/ocpprouter/tlsReload |
POST /ocpprouter/tlsReload |
Moved |
POST /data/ocpprouter/subscription |
POST /ocpprouter/subscription |
Moved |
GET /data/ocpprouter/subscription |
GET /ocpprouter/subscription |
Moved |
DELETE /data/ocpprouter/subscription |
DELETE /ocpprouter/subscription |
Moved |
PUT /data/ocpprouter/websocketMapping |
PUT /ocpprouter/websocketMapping |
Moved |
DELETE /data/ocpprouter/websocketMapping |
DELETE /ocpprouter/websocketMapping |
Moved |
DELETE /data/ocpprouter/connection |
DELETE /ocpprouter/connection |
Moved |
GET /data/ocpprouter/websocket |
— | Removed |
POST /data/ocpprouter/websocket |
— | Removed |
DELETE /data/ocpprouter/websocket |
— | Removed |
| — | POST /evdriver/webpayment/initiate |
New |
| — | GET /permissions/ |
New |
| — | GET /permissions/user |
New |
| — | POST /dev/token |
New (only when auth.mode = localDev) |
| — | GET /dev/roles |
New (only when auth.mode = localDev) |
OCPP Message Endpoints
These have the same pattern in both versions: POST /ocpp/<version>/<module>/<action>. In 1.x, they were @AsMessageEndpoint methods in each module's MessageApi. In 2.x, they're listed in packages/ocpp/src/apis/ocpp/<version>/<module>.ts.
{2.0.1|2.1} means the route is registered for both versions. In 2.x, a version gets the route only if that version has a request schema for the action.
| 1.x | 2.x | Status |
|---|---|---|
POST /ocpp/1.6/configuration/changeAvailability |
POST /ocpp/1.6/configuration/changeAvailability |
Unchanged |
POST /ocpp/1.6/configuration/changeConfiguration |
POST /ocpp/1.6/configuration/changeConfiguration |
Unchanged |
POST /ocpp/1.6/configuration/dataTransfer |
POST /ocpp/1.6/configuration/dataTransfer |
Unchanged |
POST /ocpp/1.6/configuration/getConfiguration |
POST /ocpp/1.6/configuration/getConfiguration |
Unchanged |
POST /ocpp/1.6/configuration/reset |
POST /ocpp/1.6/configuration/reset |
Unchanged |
POST /ocpp/1.6/configuration/signedUpdateFirmware |
POST /ocpp/1.6/configuration/signedUpdateFirmware |
Unchanged |
POST /ocpp/1.6/configuration/triggerMessage |
POST /ocpp/1.6/configuration/triggerMessage |
Unchanged |
POST /ocpp/1.6/configuration/updateFirmware |
POST /ocpp/1.6/configuration/updateFirmware |
Unchanged |
POST /ocpp/1.6/evdriver/clearCache |
POST /ocpp/1.6/evdriver/clearCache |
Unchanged |
| — | POST /ocpp/1.6/evdriver/getLocalListVersion |
New |
POST /ocpp/1.6/evdriver/remoteStartTransaction |
POST /ocpp/1.6/evdriver/remoteStartTransaction |
Unchanged |
POST /ocpp/1.6/evdriver/remoteStopTransaction |
POST /ocpp/1.6/evdriver/remoteStopTransaction |
Unchanged |
| — | POST /ocpp/1.6/evdriver/sendLocalList |
New |
POST /ocpp/1.6/evdriver/unlockConnector |
POST /ocpp/1.6/evdriver/unlockConnector |
Unchanged |
POST /ocpp/1.6/reporting/getDiagnostics |
POST /ocpp/1.6/reporting/getDiagnostics |
Unchanged |
POST /ocpp/1.6/smartcharging/clearChargingProfile |
POST /ocpp/1.6/smartcharging/clearChargingProfile |
Unchanged |
POST /ocpp/1.6/smartcharging/getCompositeSchedule |
POST /ocpp/1.6/smartcharging/getCompositeSchedule |
Unchanged |
POST /ocpp/1.6/smartcharging/setChargingProfile |
POST /ocpp/1.6/smartcharging/setChargingProfile |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/certificates/certificateSigned |
POST /ocpp/{2.0.1\|2.1}/certificates/certificateSigned |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/certificates/deleteCertificate |
POST /ocpp/{2.0.1\|2.1}/certificates/deleteCertificate |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/certificates/getInstalledCertificateIds |
POST /ocpp/{2.0.1\|2.1}/certificates/getInstalledCertificateIds |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/certificates/installCertificate |
POST /ocpp/{2.0.1\|2.1}/certificates/installCertificate |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/configuration/changeAvailability |
POST /ocpp/{2.0.1\|2.1}/configuration/changeAvailability |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/configuration/clearDisplayMessage |
POST /ocpp/{2.0.1\|2.1}/configuration/clearDisplayMessage |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/configuration/dataTransfer |
POST /ocpp/{2.0.1\|2.1}/configuration/dataTransfer |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/configuration/getDisplayMessages |
POST /ocpp/{2.0.1\|2.1}/configuration/getDisplayMessages |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/configuration/publishFirmware |
POST /ocpp/{2.0.1\|2.1}/configuration/publishFirmware |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/configuration/reset |
POST /ocpp/{2.0.1\|2.1}/configuration/reset |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/configuration/setDisplayMessage |
POST /ocpp/{2.0.1\|2.1}/configuration/setDisplayMessage |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/configuration/setNetworkProfile |
POST /ocpp/{2.0.1\|2.1}/configuration/setNetworkProfile |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/configuration/triggerMessage |
POST /ocpp/{2.0.1\|2.1}/configuration/triggerMessage |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/configuration/unpublishFirmware |
POST /ocpp/{2.0.1\|2.1}/configuration/unpublishFirmware |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/configuration/updateFirmware |
POST /ocpp/{2.0.1\|2.1}/configuration/updateFirmware |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/evdriver/cancelReservation |
POST /ocpp/{2.0.1\|2.1}/evdriver/cancelReservation |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/evdriver/clearCache |
POST /ocpp/{2.0.1\|2.1}/evdriver/clearCache |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/evdriver/getLocalListVersion |
POST /ocpp/{2.0.1\|2.1}/evdriver/getLocalListVersion |
Unchanged |
| — | POST /ocpp/2.1/evdriver/notifyWebPaymentStarted |
New |
POST /ocpp/{2.0.1\|2.1}/evdriver/requestStartTransaction |
POST /ocpp/{2.0.1\|2.1}/evdriver/requestStartTransaction |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/evdriver/requestStopTransaction |
POST /ocpp/{2.0.1\|2.1}/evdriver/requestStopTransaction |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/evdriver/reserveNow |
POST /ocpp/{2.0.1\|2.1}/evdriver/reserveNow |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/evdriver/sendLocalList |
POST /ocpp/{2.0.1\|2.1}/evdriver/sendLocalList |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/evdriver/unlockConnector |
POST /ocpp/{2.0.1\|2.1}/evdriver/unlockConnector |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/monitoring/clearVariableMonitoring |
POST /ocpp/{2.0.1\|2.1}/monitoring/clearVariableMonitoring |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/monitoring/getVariables |
POST /ocpp/{2.0.1\|2.1}/monitoring/getVariables |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/monitoring/setMonitoringBase |
POST /ocpp/{2.0.1\|2.1}/monitoring/setMonitoringBase |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/monitoring/setMonitoringLevel |
POST /ocpp/{2.0.1\|2.1}/monitoring/setMonitoringLevel |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/monitoring/setVariableMonitoring |
POST /ocpp/{2.0.1\|2.1}/monitoring/setVariableMonitoring |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/monitoring/setVariables |
POST /ocpp/{2.0.1\|2.1}/monitoring/setVariables |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/reporting/customerInformation |
POST /ocpp/{2.0.1\|2.1}/reporting/customerInformation |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/reporting/getBaseReport |
POST /ocpp/{2.0.1\|2.1}/reporting/getBaseReport |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/reporting/getLog |
POST /ocpp/{2.0.1\|2.1}/reporting/getLog |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/reporting/getMonitoringReport |
POST /ocpp/{2.0.1\|2.1}/reporting/getMonitoringReport |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/reporting/getReport |
POST /ocpp/{2.0.1\|2.1}/reporting/getReport |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/smartcharging/clearChargingProfile |
POST /ocpp/{2.0.1\|2.1}/smartcharging/clearChargingProfile |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/smartcharging/clearedChargingLimit |
— | Removed |
POST /ocpp/{2.0.1\|2.1}/smartcharging/getChargingProfiles |
POST /ocpp/{2.0.1\|2.1}/smartcharging/getChargingProfiles |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/smartcharging/getCompositeSchedule |
POST /ocpp/{2.0.1\|2.1}/smartcharging/getCompositeSchedule |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/smartcharging/setChargingProfile |
POST /ocpp/{2.0.1\|2.1}/smartcharging/setChargingProfile |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/transactions/costUpdated |
POST /ocpp/{2.0.1\|2.1}/transactions/costUpdated |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/transactions/getTransactionStatus |
POST /ocpp/{2.0.1\|2.1}/transactions/getTransactionStatus |
Unchanged |
POST /ocpp/{2.0.1\|2.1}/transactions/setDefaultTariff |
POST /ocpp/{2.0.1\|2.1}/transactions/setDefaultTariff |
Unchanged |
PNPM#
CitrineOS now uses pnpm, so any commands that you currently run should be prefixed with pnpm.
Running CitrineOS#
The command pnpm citrine was added to make it easier to run CitrineOS. You can check what flags are available using
pnpm citrine --help
Dependency Injection (via Awilix)#
To support testability and module organization, CitrineOS now uses Awilix for dependency injection.
RabbitMQ Dead-Letter Queue#
Dead-lettering was added to RabbitMQ. The exchange is called <exchange>.dlx while the queue is called <exchange>.dlq
with x-citrineos-dead-letter-* headers. See related configurations for RabbitMQ at DATABASE -> schema, validateSchema, and
validateSchemaSeverity in configurations).
Monorepo#
The biggest change between 1.x and 2.x is that CitrineOS is now a monorepo containing the following modules:
- Core (OCPP)
- OCPI
- Operator UI
Folder Structure#
1.x 2.x
------------------------------- -------------------------------
|-- 00_Base/ |-- packages/
|-- 01_Data/ | |-- base/ [NEW] 00_Base
|-- 02_Util/ | |-- dal/ [NEW] 01_Data, data access layer
|-- 03_Modules/ | |-- ocpi/ [NEW] previously in citrineos-ocpi
|-- Server/ | |-- ocpp/ [NEW] combination of 02_Util and 03_Modules
|-- migrations/ | |-- types/ [NEW] split out of base
|-- db.sync.ts |-- apps/
|-- db.force-sync.ts | |-- mock-msp/ [NEW]
|-- entrypoint.sh | |-- ocpi-server/ [NEW] previously in citrineos-ocpi
|-- .sequelizerc | |-- ocpp-server/ [NEW] previously Server
|-- package-lock.json | |-- operator-ui/ [NEW] previously in citrineos-operator-ui
|-- scripts/ [NEW]
|-- docker-compose.yml [NEW]
|-- docker-compose.local.yml [NEW]
|-- pnpm-workspace.yaml
|-- pnpm-lock.yaml
DAL#
Data access layer-related classes (such as Sequelize repository and models) were moved to a standalone package dal
so the data access layer can be imported without pulling in base or core.
Drizzle#
CitrineOS is migrating away from Sequelize towards Drizzle. This work is ongoing and will not be completed by
the release of version 2.0.0, so you can track the progress in packages/dal/src/repositories/drizzle, and the table
schemas are in packages/dal/src/db/drizzle. If you want to try the already-migrated repositories, you can enable it by
setting CITRINEOS_USE_DRIZZLE to "true".
Schema Validation#
In order to align the data models with the database entities, a new schema validator was introduced to run prior to CitrineOS starting to ensure that the shapes in the code and database match each other. There is a validator for Sequelize and Drizzle, though once Drizzle is fully in use, the Sequelize validator will go away.
You can configure how the schema validation runs using configurations (see DATABASE -> schema, validateSchema, and
validateSchemaSeverity in configurations).
Types#
OCPP message models were moved to a standalone package types so consumers can depend on the schemas without pulling in base.
OCPI#
OCPI-related modules, handlers, APIs and transports were all moved to the dedicated ocpi folder. It should no longer
rely on the ocpp folder and instead uses the base, dal , and types dependencies for whatever it shares with
the other modules. The package.json package name for ocpi-server has been updated to be ocpi-server.
Handlers#
All module handlers decorated with @AsHandler were moved out of their respective module.ts files and separated into
their own handlers decorated with @AsRequestHandler or @AsResponseHandler, organized by protocol and request/response
type. You can find the handlers in packages/ocpp/src/handlers.
Filenames in Kebab Case#
Any filenames that were created and not necessary for a library's config were renamed to be in kebab case. This means filenames-now-look-like-this.