API Documentation/Specification evcs-user-priority-api.json
https://community.developer.gridx.de//uploads/short-url/1vJaIOfEzVhC4abgzmzohSTvOme.json
last updated: 2025-03-04T12:16:37.960Z (sha 6dd3f59c)
1 Like
Hey all 
We hope the developer community can serve as a good place to keep track of discussions and iterations we take while working on this new API. While it is only visible to selected few users right now, please remember it might not always be in the future and we should not leak details.
The overall flow would look something like this:
- Whenever the prioritization changes (new plug / change of priority during ongoing session), you can call the
PUTendpoint and provide some identification of the desired EVCS and connector to update. For now we are looking into the serial number. Alternatively we could also use EVSE (but requires additional provisioning to gridX) or gridX appliance IDs (but requires additional mapping). - On unplug we reset the user priority for the connector of the EVCS. This will always be visible in the
GETendpoint. - For convenience we also thought about some
DELETEto reset all priorities. See also the open questions below.
That said, here are some open questions:
- How do we well address the specific connector / plug of an EVCS? Inside of gridX we model this as distinct appliances. We need to check if the received serial numbers contain some identifier (e.g. does HYC report
device/connectorXYper connector?) - Is it feasible to store further identifiers along with each site, e.g.
systemIDper gridBox? - Should there be some endpoint to reset the priority of individual connectors?
For systemID and applianceID take a look at the XENON API Documentation.
Looking forward to discuss this 
1 Like
“How do we identify a specific EVSE, if there are multiple” is probably a dedicated topic to discuss: Identifier to match an incoming request to a specific EVSE
Hi!
One point / question concerning the value for the priority:
What is should be the expected format / value range for the different levels of priority?
In OCPP2.0.1 the charging priority parameter has a range of -9…9, shall we use this as well?
Is there any logic on gridX side concerning the ratio of the priority values or is it simply higher value → higher prio?
Hey @ohoecklin, thanks for reaching out
From our side we considered:
- 0 is the default priority. Any unplug event would reset the priority back to 0.
- With an increasing value the priority increases, so indeed higher value → higher priority.
So far our assumption was to use only positive numbers and that unassigned sessions would receive the lowest priority (i.e. 0). But there is nothing blocking us from adding support for negative numbers. Do you see a need to lower priority for charging sessions to “less than default”?
Questions from bernhard.jakobs@eon.com:
Initial questions in general:
- Is the systemID mandatory in order to set the priority?
Or would the serial number be sufficient?
Currently, we are not managing the systemID in the charge point management system.
- Is the serial number a free text field to be set manually in the Xenon portal?
Hey, thanks for reposting Akash.
- The SystemID would make lookups on our side much more efficient and can help with access control. We will check for solutions that accept the asset identification at the system level and how to efficiently handle the assignment there.
- The serial number is a hardware property and cannot be edited. It allows us to reliably identify assets. We will check how to approach other identifiers though, e.g. the
OCPP Chargepoint ID, to make interfacing easier.
Thank you @Akash_Roshan and @RaffaelStahl
My questions were outdated after our discussion.
As discussed, the systemID is not maintained in the CPMS and should not be mandatory.
Instead, a static accountID for all E.ON systems could be used.
The systemID might be an additional optional parameter.
The preferred identifier of a charging station in this case is the OCPP Chargebox Identity (CBID).
The identification of a unique charge point is to be defined.
Hey @Bernhard, thanks for summarizing the points again!
Chargebox Identity
Our Integrations team looked into identifiers we can read via the existing interfaces.
OCPP parameters are not generally exposed via Modbus, as most vendors seem to limit this interface to load management.
But we found the BootNotification in OCPP should carry both hardware serial number and OCPP-specific identification.
It might also be stored in the CPMS / CSMS?
To facilitate the mapping we would have the middleware send the hardware serial number along with any other identification for later use.
This needs to be done at least once but may happen on each BootNotification, as repeated calls would not changed anything.
(Note I am very generous with the term Middleware here)
sequenceDiagram
rect rgb(191, 223, 255)
Charging Station->>Middleware: BootNotification with Serial Number
Note over Charging Station, gridX: Initial Registration, at least once
Middleware->>gridX: Chargebox Identity + Serial Number
Note over gridX: Assign Identity
end
rect rgb(191, 223, 255)
Middleware->>gridX: Put Priority using Chargebox Identity + Connector
Note over gridX: Lookup using Identity
end
Later requests can then use the Chargebox Identity (or any other) to update a priority, no need to store the assetID or serial numbers.
SystemID
We can create organizational authentication tokens that are valid for all systems in a specific account. The token itself describes the account. For any request we find the asset among all assets of all systems that are assigned to this specific account. It would only need the “Initial Registration” once.
The scope of the token can be limited to this specific use-case.
Let me know if that would work, I can then update the specs for it 
Thank you for the proposal @RaffaelStahl
Regarding the SystemID, the authentication token for the entire account sounds good.
Regarding the identification of the charge point, is the hardware serial number in the boot notification the same as the serial number that can be seen in the Xenon portal?
Would the serial number + connector be feasible to put the priority (without initial registration)?
Hey, what I was able to find (and what the above is based on) is that for one Alfen station we observed this BootNotification as part of some OCPP 1.6 experiment:
{
"chargePointVendor": "Alfen BV",
"chargePointModel": "ICU Eve Mini",
"chargePointSerialNumber": "#####R###",
"chargeBoxSerialNumber": "DE_EDR_ELAB####",
"firmwareVersion":"4.7.1-3158"
}
(where I replaced some parts of the serial numbers with #). This chargePointSerialNumber matches the hardware serial number that Alfen makes available via Modbus and is indeed the same one we use to identify assets.
- Each OCPP 1.6 and OCPP 2.0.1 have this serial number field available as part of the
BootNotification. And while the field is not required per spec, I do not see any reason for manufacturers to not implement this value if they already expose it via Modbus. - Still, to verify, I have requested another setup with another Alfen station in the gridX lab, where we will observe the
BootNotificationcontents once more and compare that to the values via Modbus. - We do not have access to HYCs in the gridX lab right now. Is there some way we could get access to such OCPP
BootNotification(or, if stored somewhere in the CSMS) directly the serial number, to compare that with some asset that is currently onboarded in XENON? I will also reach out to our solution engineers to see if we can organize for some HYC testing somewhere else. But if you see some way to support that this would help a lot.
Serial number and connector should be sufficient to put a priority, as this allows us to uniquely identify one EVSE to control. Such an example is already included in the API specs (see the PUT request above, example request body for BySerialNumber). In that case we do not need any other registration. We only need to make sure Modbus and OCPP enumerate the connectors in the same order…
Still, I would like to further explore support for OCPP / other external identifiers, as a more general improvement to our API.
I came across this document and it looks very promising for the HYC OCPP communication:
The 22BZ00055 matches the pattern for the serial numbers that we get from HYCs via Modbus! Still, to be tested, but promising.
Regarding HYC, I don´t see distinct chargePointSerialNumber and chargeBoxSerialNumber in the E.ON CSMS and the use of the SerialNumber would be supported.
Regarding Alfen, a different chargePointSerialNumber and chargeBoxSerialNumber is used at many E.ON stations. The chargeBoxSerialNumber is used as identifier in the CSMS (OCPP 1.6).
Thank you for highlighting that the options BySerialNumber and ByEVSE will be supported as well. We have overlooked those options during the previous discussions.
I assume that we could start using the EVSE and might not need the initial registration step.
Nevertheless, we should have a joint session to confirm this and to compare the actual values (incl. order of connectors) across the systems in an existing setup with Alfen and HYC chargers.
The EVSEID has to be maintained manually in XENON, right? It might change during the lifecycle of a charging station and would have to be synchronized across systems.
Hey @Bernhard, we were able to organize a test both in our lab (for Alfen) and in Essen (for Alpitronic).
For each we configured the gridBox to act as an OCPP backend and deployed an OCPP debug server (think ws://gridbox:8180/ocpp). In both cases we used OCPP 1.6j.
The Alfen used the chargepointID of DE_EDR_E12345678 when connecting via OCPP. We captured this BootNotification:
{
"chargePointVendor": "Alfen BV",
"chargePointModel": "NG920-61101",
"chargePointSerialNumber": "ACE9876543",
"chargeBoxSerialNumber": "DE_EDR_E12345678",
"firmwareVersion": "7.1.3-4342"
}
where ACE9876543 is the serial number we can access via Modbus and use to identify the asset.
This matches your observation that the Alfen stations prefer to use the chargeBoxSerialNumber in OCPP communication.
The HYC was configured in a similar way. It used the chargepointID of 123456789 when connecting via OCPP. We captured this BootNotification:
{
"chargePointSerialNumber": "HYC_50_123456789",
"chargePointVendor": "alpitronic GmbH",
"meterType": "",
"meterSerialNumber": "",
"chargePointModel": "HYC50_2_74_74",
"iccid": "#######################F",
"chargeBoxSerialNumber": "HYC_50_123456789",
"firmwareVersion": "hyc_v2.2.1",
"imsi": "###############"
}
where HYC_50_123456789 is the serial number we can access via Modbus and use to identify the asset.
The HYC seems to use the chargePointIdentity from its configuration (as below), which at least in this case does match both charge(Point|Box)SerialNumber as a suffix, but could be changed to any other value.
Seeing this, it is definitely possible to reliably assign any additional identifier of any sort if we can have it along with the chargePointSerialNumber.
Yes, definitely! As far as the testing went today, it seems consistent though (both setups had two connectors and started their enumeration at 1).
The EVSEID is available as part of the API and I will check again to make sure this is part of the public API. I understand the challenge that this might only work for public charging stations but still wanted to include it, as it is something that exists already in the API. You are totally right though, it does leave the challenge to map it across systems and here too I see the chargePointSerialNumber as an important piece of information. If we get that right, we can sync EVSEID and any other kind of identity 
Hey @Bernhard,
with EVCS User Priority API Changelog - #3 we just updated the API proposal in two places:
- The API for the
evcs-user-prioritizationnow uses theSystemIDandAssetIDconsistently. This makes it conform with the gridX API around it and we can keep it like that for longer term. - The more flexible asset identification has moved to
/how-to-name-this- it needed a placeholder so that we can continue our discussion on the possible identifiers, but this would be the proposal for the short term. It does not require anyAccountID,SystemIDorAssetID, instead the request body can encode the serial number (+ connector) or EVSE-ID and the account will be inferred from the authentication token.
Longer term we cannot support /how-to-name-this and need to migrate it to a more standardized API. Either by extending the Asset API to make it more easy to tag and later find assets or by deepening the Integration with the OEMs and gain access to the CBID via Modbus. But at least it should unblock the project for now and help us better understand what to look out for.
Heads up: the API embedding seems to truncate some parts of the description, you might need to click Multiline description to see it in full.
Hey,
just a quick update on this thread: We have included the API specs with the public API specs: gridX API Documentation .
Future questions can go to the PM / SEs / or be raised here in the community.
Best,
Raffael
1 Like