--- asyncapi: 3.0.0 id: 'pionix:de:everest:system_API' info: title: 'EVerest API definition for the system module' version: 1.0.0 description: >- API for EVerest API client implementing the system capabilities OTA update and log upload. license: name: Apache-2.0 url: https://opensource.org/licenses/Apache-2.0 tags: - name: EVerest - name: SystemAPI servers: default: pathname: 'everest_api/1/system/{module_id}' host: 'localhost:1883' description: default local MQTT protocol: mqtt variables: module_id: description: The ID of the module as defined in the EVerest config file. defaultContentType: application/json channels: receive_request_update_firmware: address: 'e2m/update_firmware' messages: receive_request_update_firmware: $ref: '#/components/messages/receive_request_update_firmware' send_reply_update_firmware: address: null messages: send_reply_update_firmware: $ref: '#/components/messages/send_reply_update_firmware' receive_allow_firmware_installation: address: 'e2m/allow_firmware_installation' messages: receive_allow_firmware_installation: $ref: '#/components/messages/receive_allow_firmware_installation' receive_request_upload_logs: address: 'e2m/upload_logs' messages: receive_request_upload_logs: $ref: '#/components/messages/receive_request_upload_logs' send_reply_upload_logs: address: null messages: send_reply_upload_logs: $ref: '#/components/messages/send_reply_upload_logs' receive_request_is_reset_allowed: address: 'e2m/is_reset_allowed' messages: receive_request_is_reset_allowed: $ref: '#/components/messages/receive_request_is_reset_allowed' send_reply_is_reset_allowed: address: null messages: send_reply_is_reset_allowed: $ref: '#/components/messages/send_reply_is_reset_allowed' receive_reset: address: 'e2m/reset' messages: receive_reset: $ref: '#/components/messages/receive_reset' receive_request_set_system_time: address: 'e2m/set_system_time' messages: receive_request_set_system_time: $ref: '#/components/messages/receive_request_set_system_time' send_reply_set_system_time: address: null messages: send_reply_set_system_time: $ref: '#/components/messages/send_reply_set_system_time' receive_request_get_boot_reason: address: 'e2m/get_boot_reason' messages: receive_request_get_boot_reason: $ref: '#/components/messages/receive_request_get_boot_reason' send_reply_get_boot_reason: address: null messages: send_reply_get_boot_reason: $ref: '#/components/messages/send_reply_get_boot_reason' send_firmware_update_status: address: 'm2e/firmware_update_status' messages: send_firmware_update_status: $ref: '#/components/messages/send_firmware_update_status' send_log_status: address: 'm2e/log_status' messages: send_log_status: $ref: '#/components/messages/send_log_status' receive_heartbeat: address: 'e2m/heartbeat' messages: receive_heartbeat: $ref: '#/components/messages/receive_heartbeat' send_communication_check: address: 'm2e/communication_check' messages: send_communication_check: $ref: '#/components/messages/send_communication_check' operations: receive_request_update_firmware: title: 'Request to update the firmware' action: receive channel: $ref: '#/channels/receive_request_update_firmware' description: 'Direction: EVerest to Module' reply: address: location: "$message.header#/replyTo" channel: $ref: '#/channels/send_reply_update_firmware' send_reply_update_firmware: title: 'Reply to update firmware request' action: send description: 'Direction: Module to EVerest' channel: $ref: '#/channels/send_reply_update_firmware' receive_allow_firmware_installation: title: 'Call to allow a firmware installation to proceed' action: receive description: 'Direction: EVerest to Module' channel: $ref: '#/channels/receive_allow_firmware_installation' receive_request_upload_logs: title: 'Receive request to upload logs' action: receive channel: $ref: '#/channels/receive_request_upload_logs' description: 'Direction: EVerest to Module' reply: address: location: "$message.header#/replyTo" channel: $ref: '#/channels/send_reply_upload_logs' send_reply_upload_logs: title: 'Request to upload logs' action: send description: 'Direction: Module to EVerest' channel: $ref: '#/channels/send_reply_upload_logs' receive_request_is_reset_allowed: title: 'Receive request for is reset allowed' action: receive channel: $ref: '#/channels/receive_request_is_reset_allowed' description: 'Direction: EVerest to Module' reply: address: location: "$message.header#/replyTo" channel: $ref: '#/channels/send_reply_is_reset_allowed' send_reply_is_reset_allowed: title: 'Send reply for is_reset_allowed' action: send channel: $ref: '#/channels/send_reply_is_reset_allowed' description: 'Direction: Module to EVerest' receive_reset: title: 'Call to reset the system immediately' action: receive channel: $ref: '#/channels/receive_reset' description: 'Direction: EVerest to Module' receive_request_set_system_time: title: 'Receive request to set the system time' action: receive channel: $ref: '#/channels/receive_request_set_system_time' description: 'Direction: EVerest to Module' reply: address: location: "$message.header#/replyTo" channel: $ref: '#/channels/send_reply_set_system_time' send_reply_set_system_time: title: 'Send reply to set system time request' action: send channel: $ref: '#/channels/send_reply_set_system_time' description: 'Direction: Module to EVerest' receive_request_get_boot_reason: title: 'Receive request to get the boot reason' action: receive channel: $ref: '#/channels/receive_request_get_boot_reason' description: 'Direction: EVerest to Module' reply: address: location: "$message.header#/replyTo" channel: $ref: '#/channels/send_reply_get_boot_reason' send_reply_get_boot_reason: title: 'Send reply to get boot reason request' action: send channel: $ref: '#/channels/send_reply_get_boot_reason' description: 'Direction: Module to EVerest' send_firmware_update_status: title: 'Send firmware update status' action: send channel: $ref: '#/channels/send_firmware_update_status' description: 'Direction: Module to EVerest' send_log_status: title: 'Send log upload status' action: send channel: $ref: '#/channels/send_log_status' receive_heartbeat: title: 'Receive heartbeat' action: receive channel: $ref: '#/channels/receive_heartbeat' send_communication_check: title: 'Send communication check' action: send channel: $ref: '#/channels/send_communication_check' components: messages: receive_request_update_firmware: name: receive_request_update_firmware title: 'Request update firmware' summary: 'Request to update the firmware.' contentType: application/json payload: type: object required: - payload properties: headers: type: object properties: replyTo: # Address for the request to reply to type: string description: Address to send the response to. If this information is missing, the command will still be accepted, but no response will be sent. payload: $ref: '#/components/schemas/FirmwareUpdateRequest' send_reply_update_firmware: name: send_reply_update_firmware title: 'Reply update firmware' summary: 'Reply to update firmware request.' contentType: application/json payload: $ref: '#/components/schemas/UpdateFirmwareResponse' examples: - summary: "Update firmware" payload: "Accepted" receive_request_upload_logs: name: receive_request_upload_logs title: 'Request upload logs' summary: 'Request to upload logs.' contentType: application/json payload: type: object required: - payload properties: headers: type: object properties: replyTo: # Address for the request to reply to type: string description: Address to send the response to. If this information is missing, the command will still be accepted, but no response will be sent. payload: $ref: '#/components/schemas/UploadLogsRequest' send_reply_upload_logs: name: send_reply_upload_logs title: 'Reply upload logs' summary: 'Reply to upload logs request.' contentType: application/json payload: $ref: '#/components/schemas/UploadLogsResponse' examples: - summary: "Upload logs" payload: file_name: "string" upload_logs_status: "Accepted" receive_request_is_reset_allowed: name: receive_request_is_reset_allowed title: 'Request if reset is allowed' summary: >- Request if is reset allowed. This is usually called prior to a reset request. contentType: application/json payload: type: object required: - payload properties: headers: type: object properties: replyTo: # Address for the request to reply to type: string description: Address to send the response to. payload: $ref: '#/components/schemas/ResetType' send_reply_is_reset_allowed: name: send_reply_is_reset_allowed title: 'Reply to is reset allowed' summary: 'Reply to is reset allowed request.' contentType: application/json payload: $ref: '#/components/schemas/ResetAllowed' examples: - summary: "Reset is allowed" payload: true receive_request_set_system_time: name: receive_request_set_system_time title: 'Receive set system time request' summary: Call to set the system time contentType: application/json payload: type: object required: - payload properties: headers: type: object properties: replyTo: # Address for the request to reply to type: string description: Address to send the response to. If this information is missing, the command will still be accepted, but no response will be sent. payload: $ref: '#/components/schemas/SystemTime' send_reply_set_system_time: name: send_reply_set_system_time title: 'Reply to set system time' summary: 'Reply to set system time request.' contentType: application/json payload: $ref: '#/components/schemas/SystemTimeSet' examples: - summary: "system time set successfully" payload: true receive_request_get_boot_reason: name: receive_request_get_boot_reason title: 'Receive get boot reason request' summary: Call to get the boot reason payload: type: object properties: headers: type: object properties: replyTo: # Address for the request to reply to type: string description: Address to send the response to. send_reply_get_boot_reason: name: send_reply_get_boot_reason title: 'Reply to get boot reason' summary: 'Reply to get boot reason.' contentType: application/json payload: $ref: '#/components/schemas/BootReason' examples: - summary: "Get boot reason" payload: "ApplicationReset" receive_allow_firmware_installation: name: receive_allow_firmware_installation title: 'Receive Allow firmware installation' summary: Call to allow firmware installation to proceed description: >- Call to allow a firmware installation to proceed. This is usually called after a firmware update has been downloaded. OCPP requires to move all EVSE to an unavailable state prior to installing new firmware. EVerest will take care of this and call this function when all EVSE are in unavailable state to signal that installation can proceed. receive_reset: name: receive_reset title: 'Receive reset command' summary: Call to reset the system immediately payload: $ref: '#/components/schemas/ResetRequest' send_firmware_update_status: name: send_firmware_update_status title: 'Send firmware update status' summary: Describes the current status of a firmware update of the system payload: $ref: '#/components/schemas/FirmwareUpdateStatus' examples: - summary: "Firmware update status" payload: firmware_update_status: "Downloaded" request_id: 0 send_log_status: name: send_log_status title: 'Send log upload status' summary: Describes the current status of log upload of the system payload: $ref: '#/components/schemas/LogStatus' examples: - summary: "Log upload status" payload: log_status: "BadMessage" request_id: 0 receive_heartbeat: name: receive_heartbeat title: 'Receive heartbeat' summary: Heartbeat produced by EVerest as configured via cfg_heartbeat_interval_ms in the EVerest configuration contentType: application/json payload: $ref: '#/components/schemas/HeartBeatId' examples: - summary: "Heartbeat" payload: 42 send_communication_check: name: send_communication_check title: 'Send communication check' summary: Signal to EVerest that communication is good or check shall be stopped contentType: application/json payload: $ref: '#/components/schemas/CommunicationCheck' examples: - summary: "CommunicationCheck" payload: true schemas: BootReason: description: Enum defining the boot reason type: string enum: - ApplicationReset - FirmwareUpdate - LocalReset - PowerUp - RemoteReset - ScheduledReset - Triggered - Unknown - Watchdog FirmwareUpdateRequest: description: Type defining a Firmware update request type: object additionalProperties: true required: - location - request_id properties: retries: description: >- This specifies how many times the system must try to download the firmware before giving up. type: integer minimum: 1 retry_interval_s: description: The interval in seconds after which a retry may be attempted type: integer request_id: description: >- The Id of this request. If the originating firmware request (e.g. from the OCPP CSMS) did not include a request_id (e.g. classic UpdateFirmware.req), a request_id of -1 is used. type: integer location: description: URI defining the origin of the firmware type: string retrieve_timestamp: description: Time when the firmware update shall be retrieved in RFC3339 format type: string format: date-time install_timestamp: description: Time when the firmware update shall be installed in RFC3339 format type: string format: date-time signing_certificate: description: >- Certificate with which the firmware was signed. PEM encoded X.509 certificate type: string signature: description: Base64 encoded firmware signature type: string FirmwareUpdateStatus: description: Type defining the status of a firmware update type: object additionalProperties: true required: - firmware_update_status - request_id properties: firmware_update_status: description: >- State describing the current status of firmware update of the system type: string $ref: '#/components/schemas/FirmwareUpdateStatusEnum' request_id: description: >- Id of the request. Use the request_id from the corresponding FirmwareUpdateRequest. type: integer FirmwareUpdateStatusEnum: description: | State describing the current download/upload status of a firmware update of the system: - Downloaded: Intermediate state. New firmware has been downloaded by System - DownloadFailed: Failure end state. System failed to download firmware - Downloading: Intermediate state. Firmware is being downloaded - DownloadScheduled: Intermediate state. Downloading of new firmware has been scheduled - DownloadPaused: Intermediate state. Downloading has been paused - Idle: System is not performing firmware update related tasks - InstallationFailed: Failure end state. Installation of new firmware has failed - Installing: Intermediate state. Firmware is being installed - Installed: Successful end state. New firmware has successfully been installed in System - InstallRebooting: Intermediate state. System is about to reboot to activate new firmware - InstallScheduled: Intermediate state. Installation of the downloaded firmware is scheduled to take place on installDateTime - InstallVerificationFailed: Failure end state. Verification of the new firmware (e.g. using a checksum or some other means) has failed and installation will not proceed. (Final failure state) - InvalidSignature: Failure end state. The firmware signature is not valid - SignatureVerified: Intermediate state. Provide signature successfully verified type: string enum: - Downloaded - DownloadFailed - Downloading - DownloadScheduled - DownloadPaused - Idle - InstallationFailed - Installing - Installed - InstallRebooting - InstallScheduled - InstallVerificationFailed - InvalidSignature - SignatureVerified LogStatusEnum: description: | State describing the current status of log upload of the system: - AcceptedCanceled: Log upload request accepted, but cancelled an ongoing log upload. - BadMessage: A badly formatted packet or other protocol incompatibility was detected - Idle: The system is not uploading a log file - NotSupportedOperation: The server does not support the operation - PermissionDenied: Insufficient permissions to perform the operation - Uploaded: File has been uploaded successfully - UploadFailure: Failed to upload the requested file - Uploading: File is being uploaded type: string enum: - AcceptedCanceled - BadMessage - Idle - NotSupportedOperation - PermissionDenied - Uploaded - UploadFailure - Uploading LogStatus: description: Type defining the status of a log upload type: object additionalProperties: true required: - log_status - request_id properties: log_status: description: State describing the current status of log upload of the system type: string $ref: '#/components/schemas/LogStatusEnum' request_id: description: >- Id of the request. Use the request_id from the corresponding UploadLogsRequest. If the originating log request did not include a request_id (e.g. classic GetDiagnostics), a request_id of -1 shall be used. type: integer ResetAllowed: description: 'true if reset is allowed' type: boolean ResetRequest: description: 'request for reset' type: object additionalProperties: true properties: type: description: 'type of the reset (Soft or Hard)' type: string $ref: '#/components/schemas/ResetType' scheduled: type: boolean ResetType: description: Enum defining the type of a reset type: string enum: - Soft - Hard - NotSpecified SystemTime: description: 'system time in RFC3339 format' type: string format: date-time SystemTimeSet: description: 'true if reset successful' type: boolean UpdateFirmwareResponse: description: | Enum for the response of an update_firmware command - Accepted: Accepted this firmware update request. This does not mean the firmware update is successful, the system will now start the firmware update process - Rejected: Firmware update request rejected - AcceptedCanceled: Accepted this firmware update request, but in doing this has cancelled an ongoing firmware update - InvalidCertificate: The certificate is invalid - RevokedCertificate: Failure end state. The Firmware Signing certificate has been revoked type: string enum: - Accepted - Rejected - AcceptedCanceled - InvalidCertificate - RevokedCertificate UploadLogsRequest: description: Type defining an upload logs request. type: object additionalProperties: true required: - location properties: retries: description: >- This specifies how many times the system must try to upload the logs before giving up. type: integer minimum: 1 retry_interval_s: description: The interval in seconds after which an upload retry may be attempted type: integer oldest_timestamp: description: >- Oldest timestamp that should be included in the log in RFC3339 format type: string format: date-time latest_timestamp: description: >- Latest timestamp that should be included in the log in RFC3339 format type: string format: date-time location: description: >- The URL of the location at the remote system where the log should be stored. type: string type: description: >- The type of the log (e.g. in OCPP there is the SecurityLog and the DiagnosticsLog type: string request_id: description: >- The Id of this request. If the originating log request did not include a request_id (e.g. classic GetDiagnostics), the request_id is omitted. type: integer UploadLogsResponse: description: Response to a upload logs request type: object additionalProperties: true required: - upload_logs_status properties: file_name: description: This contains the name of the log file that will be uploaded. type: string upload_logs_status: description: The log status enum type: string $ref: '#/components/schemas/UploadLogsStatus' UploadLogsStatus: description: | Enum for the upload logs status response - Accepted: Request to upload logs has been accepted - Rejected: Request to upload logs has been rejected - AcceptedCanceled: Accepted this log upload, but in doing this has cancelled an ongoing log file upload type: string enum: - Accepted - Rejected - AcceptedCanceled CommunicationCheck: type: boolean description: "Send 'true' at least every 'cfg_communication_check_to_s' seconds to signal module is alive. Send 'false' to stop communication check'" HeartBeatId: type: integer description: "64bit unsigned integer. The id of every heartbeat increases by 1 and overflows when the maximum representable value is reached"