Schema Documentation
Topics read tenix/{domain}/{sender}/{recipient}/…, where todp is the Tenix
Open Data Platform. The order of those two segments is what gives the direction
of a message:
tenix/{domain}/todp/{companyId}/… — sent by Tenix. Subscribe to receive it.tenix/{domain}/{companyId}/todp/… — received by Tenix. Publish to send it.Vehicle Telemetry Channel
Publish Vehicle Telemetry messages
The unique identifier of the Company.
A Vehicle internal number
Accepts the following message:
{
"vehicle": {
"companyId": "1877c37hcebb4c4f808628d99d7bs0df",
"divisionId": "1877c37hcebb4c4f808628d99d7bs0df",
"internalNumber": "2255",
"vin": "2GBE4C3126H66WC5A",
"bmsIds": [
"FD43DE0DC4B6"
]
},
"gps": {
"lat": 0,
"lon": 0,
"alt": 0,
"satellites": 0,
"speed": 0,
"angle": 0,
"timestamp": "2023-06-30T00:00:00.000Z"
},
"ignition": {
"value": true,
"timestamp": "2023-06-30T00:00:00.000Z"
},
"totalFuelConsumed": {
"value": 0,
"timestamp": "2023-06-30T00:00:00.000Z"
},
"odometer": {
"value": 0,
"timestamp": "2023-06-30T00:00:00.000Z"
},
"soc": {
"value": 0,
"timestamp": "2023-06-30T00:00:00.000Z"
}
}
Vehicle Telemetry Channel
Receive Vehicle Telemetry messages
The unique identifier of the Company.
A Vehicle internal number
Accepts the following message:
{
"vehicle": {
"companyId": "1877c37hcebb4c4f808628d99d7bs0df",
"divisionId": "1877c37hcebb4c4f808628d99d7bs0df",
"internalNumber": "2255",
"vin": "2GBE4C3126H66WC5A",
"bmsIds": [
"FD43DE0DC4B6"
]
},
"gps": {
"lat": 0,
"lon": 0,
"alt": 0,
"satellites": 0,
"speed": 0,
"angle": 0,
"timestamp": "2023-06-30T00:00:00.000Z"
},
"ignition": {
"value": true,
"timestamp": "2023-06-30T00:00:00.000Z"
},
"totalFuelConsumed": {
"value": 0,
"timestamp": "2023-06-30T00:00:00.000Z"
},
"odometer": {
"value": 0,
"timestamp": "2023-06-30T00:00:00.000Z"
},
"soc": {
"value": 0,
"timestamp": "2023-06-30T00:00:00.000Z"
}
}
Charging Session State Topic
Publish Charging Session State messages
The unique identifier of the Company.
The unique identifier of the Depot.
The unique identifier of the charger.
The unique identifier of the connector.
Accepts the following message:
A message providing the complete state of a charging session.
{
"timestamp": "2023-06-30T00:00:00.000Z",
"sessionId": 0,
"idTag": "string",
"vehicle": {
"companyId": "1877c37hcebb4c4f808628d99d7bs0df",
"divisionId": "1877c37hcebb4c4f808628d99d7bs0df",
"internalNumber": "2255",
"vin": "2GBE4C3126H66WC5A",
"bmsIds": [
"FD43DE0DC4B6"
]
},
"chargePoint": {
"chargerId": "string",
"chargerName": "string",
"connectorId": 0,
"connectorName": "string"
},
"sessionStart": "2023-06-30T00:00:00.000Z",
"sessionEnd": "2023-06-30T00:00:00.000Z",
"socStart": 0,
"consumedEnergy": 0,
"chargingCost": {
"amount": 0,
"currency": "string"
},
"lastPower": 0,
"lastSoc": 0,
"lastVoltage": 0,
"estimatedCompletionTime": "2023-06-30T00:00:00.000Z",
"status": "PENDING",
"errorCode": "E1234"
}
Charger Connection Status Topic
Receive Charger Connection Status messages
The unique identifier of the Company.
The unique identifier of the Depot.
The unique identifier of the charger.
Accepts the following message:
A message providing the current connection status of a charger.
{
"timestamp": "2023-06-30T00:00:00.000Z",
"status": "ONLINE"
}
Connector Status Topic
Receive Connector Status messages
The unique identifier of the Company.
The unique identifier of the Depot.
The unique identifier of the charger.
The unique identifier of the connector.
Accepts the following message:
A message providing the current status of a charger's connector.
{
"timestamp": "2023-06-30T00:00:00.000Z",
"status": "AVAILABLE"
}
Charging Session State Update Topic
Receive Charging Session State Update messages
The unique identifier of the Company.
The unique identifier of the Depot.
The unique identifier of the charger.
The unique identifier of the connector.
Accepts the following message:
A message providing the current state of a charging session.
{
"timestamp": "2023-06-30T00:00:00.000Z",
"sessionId": 0,
"idTag": "string",
"sessionStart": "2023-06-30T00:00:00.000Z",
"sessionEnd": "2023-06-30T00:00:00.000Z",
"lastMeterValue": 0,
"lastPower": 0,
"lastSoc": 0,
"lastVoltage": 0,
"lastCurrent": 0,
"lastTemperature": 0,
"stopReason": "EMERGENCY_STOP"
}
Connector Alarm Topic
Publish Connector Alarm messages
The unique identifier of the Company.
The unique identifier of the Depot.
The unique identifier of the charger.
The unique identifier of the connector.
Accepts the following message:
{
"alarmType": "CONNECTOR_UNAVAILABLE",
"timestamp": "2023-06-30T00:00:00.000Z",
"message": "string",
"details": "string",
"chargePoint": {
"chargerId": "string",
"chargerName": "string",
"connectorId": 0,
"connectorName": "string"
}
}
Charging Profile Configuration Command Topic
Publish Charging Profile Configuration Command
The unique identifier of the Company.
The unique identifier of the Depot.
The unique identifier of the charger.
Accepts the following message:
A message providing new charging profile configuration request
In case of setting a profile (requestType = "SET_PROFILE") all the fields are supposed to be provided. In case of clearing the profile (requestType = "CLEAR_PROFILE") "startSchedule" and "charging periods" will be omitted
{
"timestamp": "2023-06-30T00:00:00.000Z",
"requestId": "1877c37hcebb4c4f808628d99d7bs0df",
"requestType": "SET_PROFILE",
"sessionId": 0,
"connectorId": 0,
"stackLevel": 0,
"purpose": "TX_DEFAULT_PROFILE",
"startSchedule": "2023-06-30T00:00:00.000Z",
"chargingPeriods": [
{
"from": "2023-06-30T00:00:00.000Z",
"power": 0
}
]
}
Charging Profile Configuration Result Topic
Receive Charging Profile Configuration Result messages
The unique identifier of the Company.
The unique identifier of the Depot.
The unique identifier of the charger.
The unique identifier of the correlated request.
Accepts the following message:
A message providing new charging profile configuration result
{
"timestamp": "2023-06-30T00:00:00.000Z",
"status": "ACCEPTED"
}
Energy Telemetry Topic.
Power measurements from the depot's Energy Management System: how much power is flowing at a point in the depot's electrical hierarchy, and how much more may flow there, in each direction, before a limit is reached.
Power is signed as it is everywhere in this domain: positive is drawn from the
grid, negative is sent to it. A depot with batteries or PV therefore reports a
negative activePower at a node while that node is exporting.
Publish one message per node per sample. The node is named in the payload, so this single topic carries the depot's grid connection point, its power groups and, where present, its substation.
timestamp, node and activePower are required. Send availableImportPower
and availableExportPower for whichever directions the system limits, and
include phases where the equipment measures per phase.
Receive Energy Telemetry messages
The unique identifier of the Company.
The unique identifier of the Depot.
Accepts the following message:
A message providing electrical measurements at a node of the depot energy hierarchy.
A power measurement at one node of the depot's electrical hierarchy, taken at one instant.
The same shape is used at every level, so node is what distinguishes a
reading at the depot's grid connection point from one at a power group. Every
value in a message comes from the same sample, hence the single timestamp.
Flow is signed — positive drawn from the grid, negative sent to it — while the two headroom values are magnitudes in a named direction. Sites with batteries or PV are limited both ways, so the two are reported separately rather than as one margin.
{
"timestamp": "2023-06-30T00:00:00.000Z",
"node": {
"nodeType": "POINT_OF_CONNECTION",
"nodeId": "string"
},
"activePower": 0,
"availableImportPower": 0,
"availableExportPower": 0,
"phases": [
{
"phase": "L1",
"activePower": 0,
"current": 0,
"voltage": 0,
"powerFactor": 0
}
]
}
Energy Alarm Topic.
Grid-side conditions detected by the depot's Energy Management System — ground faults, transformer over temperature, tripped breakers.
Each message carries the complete set of alarms active at the depot at that moment. Publish a new message whenever that set changes: a condition arises, a condition clears, or an active alarm's severity or detail changes.
An alarm present in one message and absent from the next has cleared. An empty
alarms array is a normal message, and says nothing is currently wrong.
Publish with the MQTT retain flag set, so that Tenix picks up the depot's current alarm state on reconnecting rather than waiting for the next change.
Receive Energy Alarm State messages
The unique identifier of the Company.
The unique identifier of the Depot.
Accepts the following message:
A message providing every grid-side alarm currently active at the depot.
The depot's complete alarm state at one instant, published whenever that state changes — a condition arises, a condition clears, or an active alarm's severity or detail changes.
Because each message is the whole state, clearing needs no event of its own: an
alarm that was in the previous message and is not in this one has cleared. A
message with an empty alarms array says the depot is currently clear, and is
how the last alarm's clearance is reported.
Send the whole set every time, including alarms that have not changed. Nothing is acknowledged over this channel, and Tenix holds no state the publisher needs to reconcile with.
{
"timestamp": "2023-06-30T00:00:00.000Z",
"alarms": [
{
"alarmType": "GROUND_FAULT",
"raisedAt": "2023-06-30T00:00:00.000Z",
"message": "string",
"details": "string",
"node": {
"nodeType": "POINT_OF_CONNECTION",
"nodeId": "string"
},
"severity": "INFO",
"alarmId": "string",
"affectedPowerGroupIds": [
"string"
],
"vendorCode": "string",
"expectedClearance": "2023-06-30T00:00:00.000Z"
}
]
}
Energy Management System Link Status Topic.
Whether the depot's Energy Management System is currently connected.
Publish ONLINE on connecting, and register this same topic as the client's
MQTT Last Will and Testament with a payload of OFFLINE. That lets Tenix tell a
system with nothing to report from one that has gone away, and mark the depot's
grid-side data stale when the link drops.
Receive Energy Management System Link Status messages
The unique identifier of the Company.
The unique identifier of the Depot.
Accepts the following message:
A message providing the current connection status of the Energy Management System.
{
"timestamp": "2023-06-30T00:00:00.000Z",
"status": "ONLINE"
}
A Vehicle Telemetry message
A message providing the complete state of a charging session.
A message providing the current connection status of a charger.
A message providing the current status of a charger's connector.
A message providing the current state of a charging session.
A message providing an alarm raised on a charger's connector.
A message providing new charging profile configuration request
In case of setting a profile (requestType = "SET_PROFILE") all the fields are supposed to be provided. In case of clearing the profile (requestType = "CLEAR_PROFILE") "startSchedule" and "charging periods" will be omitted
A message providing new charging profile configuration result
A message providing electrical measurements at a node of the depot energy hierarchy.
A power measurement at one node of the depot's electrical hierarchy, taken at one instant.
The same shape is used at every level, so node is what distinguishes a
reading at the depot's grid connection point from one at a power group. Every
value in a message comes from the same sample, hence the single timestamp.
Flow is signed — positive drawn from the grid, negative sent to it — while the two headroom values are magnitudes in a named direction. Sites with batteries or PV are limited both ways, so the two are reported separately rather than as one margin.
A message providing every grid-side alarm currently active at the depot.
The depot's complete alarm state at one instant, published whenever that state changes — a condition arises, a condition clears, or an active alarm's severity or detail changes.
Because each message is the whole state, clearing needs no event of its own: an
alarm that was in the previous message and is not in this one has cleared. A
message with an empty alarms array says the depot is currently clear, and is
how the last alarm's clearance is reported.
Send the whole set every time, including alarms that have not changed. Nothing is acknowledged over this channel, and Tenix holds no state the publisher needs to reconcile with.
A message providing the current connection status of the Energy Management System.
In case of setting a profile (requestType = "SET_PROFILE") all the fields are supposed to be provided. In case of clearing the profile (requestType = "CLEAR_PROFILE") "startSchedule" and "charging periods" will be omitted
Where in the depot's electrical hierarchy a measurement or alarm belongs.
POINT_OF_CONNECTION — the depot's grid connection. One per depot, and where
depot-level measurements are taken.
POWER_GROUP — a group of chargers sharing a supply, as Tenix models it.
SUBSTATION — a monitoring and protection node. Carries no capacity of its
own and is not a power group.
A power measurement at one node of the depot's electrical hierarchy, taken at one instant.
The same shape is used at every level, so node is what distinguishes a
reading at the depot's grid connection point from one at a power group. Every
value in a message comes from the same sample, hence the single timestamp.
Flow is signed — positive drawn from the grid, negative sent to it — while the two headroom values are magnitudes in a named direction. Sites with batteries or PV are limited both ways, so the two are reported separately rather than as one margin.
How urgent the condition is, from an informational note through to a fault needing immediate operator attention.
The kind of condition detected. Use OTHER where none of the listed values
fits, and describe the specifics in message and details.
One grid-side condition currently active at the depot: node says where it
arose, raisedAt when it was detected, severity how urgent it is, and
affectedPowerGroupIds which parts of the depot it affects.
raisedAt is when the condition began, not when the message was sent — it
stays the same across every message the alarm appears in, while the enclosing
timestamp moves on.
Only alarmType, raisedAt, severity and node are required — send
whichever of the rest the system exposes.
The depot's complete alarm state at one instant, published whenever that state changes — a condition arises, a condition clears, or an active alarm's severity or detail changes.
Because each message is the whole state, clearing needs no event of its own: an
alarm that was in the previous message and is not in this one has cleared. A
message with an empty alarms array says the depot is currently clear, and is
how the last alarm's clearance is reported.
Send the whole set every time, including alarms that have not changed. Nothing is acknowledged over this channel, and Tenix holds no state the publisher needs to reconcile with.
Whether the Energy Management System is connected.