Overvis Connect Protocol Documentation
https://www.overvis.com/docs/en/overvis-connect/
2026-04-06
| | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
Overvis Connect ProtocolOvervis Connect is a lightweight communication protocol between device and application. The underlying protocol describes connection support and sending meta information. Additional functionality, such as working with device parameters, reading the device journal, working with the device’s internal clock, etc., is described in the protocol extensions. Key FeaturesSection titled “Key Features”
Common Use CasesSection titled “Common Use Cases”
DocumentationSection titled “Documentation”Core ProtocolSection titled “Core Protocol”
ExtensionsSection titled “Extensions”Device OperationsSection titled “Device Operations”
Security & AuthenticationSection titled “Security & Authentication”
Data Transfer & EncryptionSection titled “Data Transfer & Encryption”
File SystemSection titled “File System”
Document StatusesSection titled “Document Statuses”
SupportSection titled “Support”
|
| | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Basic ProtocolDocument status: Approved (2020-02-01) Data Exchange ProcedureSection titled “Data Exchange Procedure”Overvis Connect is a client-server protocol. The device is always the server, the application is the client. The client sends requests, the server responds. The connection initiator can be either party. When the server (device) initiates a connection, it’s called “backward” connection—useful for bypassing firewalls when multiple devices connect to one cloud application. Usually, the first request is If there’s no exchange for a period, the server terminates the connection. To prevent this, the client must regularly send The server must respond within 10 seconds, otherwise the client may terminate or repeat the request. Request and Response FormatSection titled “Request and Response Format”Fields are coded Big Endian (most significant byte first).
Maximum packet length is 65535 bytes, but devices may set smaller limits via Error ResponseSection titled “Error Response”Where Common Error CodesSection titled “Common Error Codes”
CommandsSection titled “Commands”Section titled “0000 Handshake” |
| Field | Length | Description |
|---|---|---|
IC | 2 bytes | Device type category (manufacturer ID) |
HW | 2 bytes | Hardware type (LSB decimal = AO version) |
FW | 4 bytes | Firmware version (MSB 2 bytes = version type) |
FLIM | 2 bytes | Max packet length in bytes |
KA | 2 bytes | Keep-alive timeout in seconds |
EXT | 2 bytes | Supported extension codes (0 or more) |
0001 Keep AliveMaintain connection when no other requests are needed.
Request:
<TID> 3900 0002 0001Response:
<TID> 3900 0002 0001| | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXT0001: Device Parameters
This extension describes reading and setting device parameters (setpoints/settings). Parameters are stored in persistent memory. To optimize work with many records and eliminate intermediate states, the extension supports transactions—changes are saved in RAM first, then written to permanent memory when the transaction completes. CommandsSection titled “Commands”Section titled “0002 Read Parameters” |
| Field | Length | Description |
|---|---|---|
SOURCE | 1 byte | Data source |
OFFSET | 2 bytes | Offset in parameter structure |
BLOCKLEN | 2 bytes | Block length |
BLOCKDATA | BLOCKLEN | Parameter block bytes |
Errors:
| Code | Description |
|---|---|
0010 | Incorrect SOURCE |
0011 | Reading out of bounds |
0012 | Response overflow |
0013 | ROM read error |
0003 Write ParametersWrite parameters and manage transactions.
When initialized, the device allocates RAM for the parameter structure and copies from permanent memory. Changes accumulate in RAM. Device keeps the structure for at least 10 seconds. On transaction completion (TRCON = 2), changes are written to permanent memory.
Request:
<TID> 3900 <LEN> 0003 <SOURCE> <TRCON> [( <OFFSET> <BLOCKLEN> <BLOCKDATA> ) ...]Response:
<TID> 3900 0002 0003| Field | Length | Description |
|---|---|---|
SOURCE | 1 byte | Data source |
TRCON | 1 byte | Transaction control: 0=start new, 1=continue, 2=commit |
OFFSET | 2 bytes | Offset in parameter structure |
BLOCKLEN | 2 bytes | Block length |
BLOCKDATA | BLOCKLEN | Parameter block bytes |
Errors:
| Code | Description |
|---|---|
0010 | Incorrect SOURCE |
0011 | Writing out of bounds |
0012 | ROM write error |
0013 | ROM resource expired |
0014 | RAM error (can’t allocate) |
0015 | Transaction aborted by another connection |
0016 | Transaction timeout |
0017 | Attempting to continue completed transaction |
| | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXT0002: Device State
This extension describes reading the current values of device status parameters. CommandsSection titled “Commands”Section titled “0004 Read State” |
| Field | Length | Description |
|---|---|---|
OFFSET | 2 bytes | Offset in parameter structure |
BLOCKLEN | 2 bytes | Block length |
BLOCKDATA | BLOCKLEN | Parameter block bytes |
Errors:
| Code | Description |
|---|---|
0010 | Reading out of bounds |
0011 | Response overflow |
| | ||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXT0003: Device Journal
This extension describes reading and clearing the journal of accumulated data (typically measurement history). Journal FormatSection titled “Journal Format”
All journal entries have the same length within a session. CommandsSection titled “Commands”Section titled “0005 Read Journal” |
| Field | Length | Description |
|---|---|---|
AFTERREC | 4 bytes | LASTREC from previous packet (0 for first request) |
LASTREC | 4 bytes | Address of last entry in current packet |
RECORDS | variable | Journal entries (descending date order) |
Errors:
| Code | Description |
|---|---|
0010 | ROM read error |
0011 | Invalid AFTERREC |
0006 Clear JournalClear all journal contents. Starts asynchronous process (use 0019 for result).
Request:
<TID> 3900 0002 0006Response:
<TID> 3900 <LEN> 0006 <PROCID> [<BUSYTIME>]| Field | Length | Description |
|---|---|---|
PROCID | 2 bytes | Process ID for result query |
BUSYTIME | 4 bytes | Max time if not background |
Process Errors:
| Code | Description |
|---|---|
0010 | ROM write error |
0011 | ROM resource expired |
| | |||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXT0004: Device Clock
This extension describes reading and changing the device’s internal clock time. CommandsSection titled “Commands”Section titled “0007 Get Time” |
| Field | Length | Description |
|---|---|---|
DTIME | 4 bytes | Unix timestamp (seconds since 1970-01-01 UTC) |
Errors:
| Code | Description |
|---|---|
0010 | Time reading error |
0008 Set TimeSet new device time.
Request:
<TID> 3900 0006 0008 <STIME>Response:
<TID> 3900 0006 0008 <DTIME>| Field | Length | Description |
|---|---|---|
STIME | 4 bytes | Time to set (Unix timestamp) |
DTIME | 4 bytes | Current device time (should equal STIME) |
Errors:
| Code | Description |
|---|---|
0010 | Time write error |
| | ||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXT0005: Firmware Update
This extension describes the firmware update process. CommandsSection titled “Commands”Section titled “0009 Get FW File Version” |
| Field | Length | Description |
|---|---|---|
FWVER | 4 bytes | FW file version (MSB 2 bytes = version type) |
Errors:
| Code | Description |
|---|---|
0010 | ROM read error |
0011 | FW file not found |
000A Delete FW FileDelete firmware file. Execute before writing new file. Asynchronous process.
Request:
<TID> 3900 0002 000AResponse:
<TID> 3900 <LEN> 000A <PROCID> [<BUSYTIME>]Process Errors:
| Code | Description |
|---|---|
0010 | ROM error |
0011 | ROM resource expired |
000B Send FW FileWrite firmware file to device.
Request:
<TID> 3900 <LEN> 000B <OFFSET> <TOTLEN> <BLOCKDATA>Response:
<TID> 3900 0002 000B| Field | Length | Description |
|---|---|---|
OFFSET | 4 bytes | Byte offset in FW file |
TOTLEN | 4 bytes | Total FW file length |
BLOCKDATA | variable | Data block |
Errors:
| Code | Description |
|---|---|
0010 | Out of bounds (TOTLEN) |
0011 | OFFSET/BLOCKDATA mismatch |
0012 | ROM write error or data exists |
000C Start FW UpdateStart firmware update. Application should disconnect after response.
Request/Response:
<TID> 3900 0002 000CErrors:
| Code | Description |
|---|---|
0010 | ROM read error |
0011 | FW file not found |
0012 | FW file CRC error |
| | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXT0006: Basic Events
This extension describes reading and management of simple events (scheduled or triggered by parameter changes). Event FormatSection titled “Event Format”
CommandsSection titled “Commands”Section titled “000D Read Events” |
| Field | Length | Description |
|---|---|---|
AFTEREV | 4 bytes | LASTEV from previous packet (0 for first) |
LASTEV | 4 bytes | Address of last entry |
EVENT | regulated | Event data |
Errors: 0010 ROM read error, 0011 Invalid AFTEREV
000E Write EventsRequest:
<TID> 3900 <LEN> 000E (<EVENT> ...)Response:
<TID> 3900 0002 000EErrors: 0010 ROM write, 0011 ROM expired, 0012 No space, 0013 Invalid EVENT
000F Delete EventsRequest:
<TID> 3900 <LEN> 000F (<EVENT> ...)Response:
<TID> 3900 0002 000FErrors: 0010 ROM write, 0011 ROM expired, 0012 Invalid EVENT
0010 Clear EventsDelete all events. Asynchronous process.
Request:
<TID> 3900 0002 0010Response:
<TID> 3900 <LEN> 0010 <PROCID> [<BUSYTIME>]| | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXT0007: Sensitive Information Check
This extension validates a value known to the server for the client (e.g., a password). Returns boolean—valid or not. No device state changes occur. Useful when application and device trust each other but application doesn’t trust user. Example: user proves physical possession of device by entering a code displayed on device. No brute-force protection needed on device side due to state immutability requirement. CommandsSection titled “Commands”Section titled “0011 Confirm Value Correctness” |
| Field | Length | Description |
|---|---|---|
KIND | 2 bytes | Value type (implementation-specific) |
VALUE | variable | Value to check |
RESULT | 1 byte | 1=correct, 0=incorrect |
Errors:
| Code | Description |
|---|---|
0010 | Invalid KIND |
| | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
EXT0008: Get Device ID
This extension retrieves the device’s unique 64-bit identifier (UID). CommandsSection titled “Commands”Section titled “0012 Get Device ID” |
| Field | Length | Description |
|---|---|---|
UID | 8 bytes | Unique device identifier |
Errors:
| Code | Description |
|---|---|
0010 | Error reading UID |
| | |||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXT0009: DH Key Exchange
Describes exchanging public key parameters using Diffie-Hellman algorithm for establishing encrypted sessions. Reference: Diffie-Hellman key exchange CommandsSection titled “Commands”Section titled “0013 Public Data for New Shared Secret” |
| Field | Length | Description |
|---|---|---|
GLEN | 2 bytes | Length of GKEY |
GKEY | GLEN | Radix g |
PLEN | 2 bytes | Length of PKEY |
PKEY | PLEN | Module p |
SKEY | variable | Server public key A |
DKEY | variable | Device public key B |
Errors:
| Code | Description |
|---|---|
0010 | GLEN/PLEN too small |
0011 | GLEN/PLEN too big |
0012 | Shared secret too short |
0013 | Shared secret too long |
0014 | Key exchange calculation error |
| |
|---|
EXT000A: Device Reboot
CommandsSection titled “Commands”Section titled “0014 Reboot Device on Disconnect” |
| | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXT000B: Next Reconnect
For backward connections only. Sets delay and address for next device connection. CommandsSection titled “Commands”Section titled “0015 Set Next Reconnect” |
| Field | Length | Description |
|---|---|---|
DELAY | 4 bytes | Delay in ms |
PORT | 2 bytes | Server port |
HOST | variable | Domain/IP as ASCII |
Errors:
| Code | Description |
|---|---|
0010 | Invalid DELAY |
| | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXT000C: Shared Secret Authentication
Two-way authentication using 256-bit secret key known to application. Device must have unique Limitation: Application stores all secret keys in clear text. Compromised application list affects all devices; keys cannot be changed on sold devices. See CommandsSection titled “Commands”Section titled “0016 Device-Server Shared Secret Authentication” |
| Field | Length | Description |
|---|---|---|
DTOKEN | 32 bytes | Random 256-bit sequence |
STOKEN | 32 bytes | Random 256-bit sequence |
CHALLENGE | 32 bytes | First 256 bits of SHA-512(DTOKEN + SKEY) |
ANSWER | 32 bytes | First 256 bits of SHA-512(STOKEN + SKEY) |
Errors:
| Code | Description |
|---|---|
0010 | Hash mismatch (client auth error) |
0011 | Too many requests, try later |
| | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXT000D: Wrapped Packet
Wrap any data in Overvis Connect packets. Wrapped packets can exceed session limit—split across multiple commands. Enables tunneling any protocol (HTTP, FTP, etc.). CommandsSection titled “Commands”Section titled “0017 Exchange Wrapped Packets” |
| Field | Length | Description |
|---|---|---|
OFFSET | 4 bytes | Block offset (or previous response offset for continuation) |
REMLEN | 4 bytes | Remaining request length (0=last part) |
BLOCKDATA | variable | Data block |
Response:
<TID> 3900 <LEN> 0017 <OFFSET> [ <ESTREM> <BLOCKDATA> ]| Field | Length | Description |
|---|---|---|
OFFSET | 4 bytes | Block offset in response |
ESTREM | 4 bytes | Estimated remaining length (0=last part) |
BLOCKDATA | variable | Response data |
Errors:
| Code | Description |
|---|---|
0010 | Request too long |
0011 | Invalid OFFSET |
| | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXT000E: Encrypted AES-256-CBC
Full encryption using AES 256 CBC with single key buffer for requests and responses. Key exchange via other extensions. CommandsSection titled “Commands”Section titled “0018 Send Encrypted Request” |
| Field | Length | Description |
|---|---|---|
LEN | 2 bytes | Length of CMD + DATA |
CMD | 2 bytes | Command code |
DATA | variable | Data field |
CHKSUM | 2 bytes | Byte sum of CMD + DATA |
PADDING | multiple of 16 | Random bytes (min 128 total PAYLOAD) |
Decryption error (unencrypted):
<TID> 3900 0004 8018 0010All other errors are encrypted within PAYLOAD. If client can’t decrypt response, it must terminate connection.
| | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXT000F: Asynchronous Result
Retrieve results of asynchronous processes started by other commands. Process result persists across reconnections. CommandsSection titled “Commands”Section titled “0019 Get Asynchronous Process Result” |
| Field | Length | Description |
|---|---|---|
PROCID | 2 bytes | Process identifier |
PERROR | 2 bytes | Error code (0=success) |
EXTRA | variable | Additional result data |
Errors:
| Code | Description |
|---|---|
0010 | Invalid PROCID |
0011 | Result not yet available |
| | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXT0010: Encrypted Gamma
Full encryption using Gamma algorithm with single key buffer. AlgorithmSection titled “Algorithm”Uses 40-byte key, encrypts in 16-byte blocks. For each block:
Block encryption (16 bytes):
Key for block 0: SHA-1 hash of key #1 (20 bytes) + key #2 (16 bytes) + block number zeros (4 bytes). Decryption reverses: XOR first, then reverse permutation. CommandsSection titled “Commands”Section titled “0018 Send Encrypted Request” |
| Field | Length | Description |
|---|---|---|
WRAPLEN | 2 bytes | Length of CMD + DATA |
CMD | 2 bytes | Command code |
DATA | variable | Data field |
CHKSUM | 2 bytes | Byte sum of CMD + DATA |
PADDING | multiple of 16 | Random bytes (min 128 total) |
Decryption error returned unencrypted: <TID> 3900 0004 8018 0010
| | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXT0011: EdDSA Authentication
Two-way authentication using EdDSA (Ed25519). Public key length: 32 bytes, signature: 64 bytes. Both public keys known to both parties. Private keys never transferred. Device public key serves as unique identifier. Authentication ProcessSection titled “Authentication Process”
Unauthenticated clients have minimum rights ( CommandsSection titled “Commands”Section titled “001A Start Authentication” |
| Field | Length | Description |
|---|---|---|
SPUBKEY | 32 bytes | Server public key |
DPUBKEY | 32 bytes | Device public key |
SCHALLENGE | 32 bytes | Random bytes for server to sign |
DCHALLENGE | 32 bytes | Random bytes for device to sign |
Errors: 000A Server key mismatch, 000B Too many requests
001B Confirm AuthenticationRequest:
<TID> 3900 0042 001B <SSIGN>Response:
<TID> 3900 0042 001B <DSIGN>| Field | Length | Description |
|---|---|---|
SSIGN | 64 bytes | Server signature of SCHALLENGE |
DSIGN | 64 bytes | Device signature of DCHALLENGE |
Errors: 000A Invalid signature, 000B Not initialized/timeout, 000C Device busy
001C Create New EdDSA SecretChange server public key and regenerate device key pair. Requires prior authentication.
Request/Response:
<TID> 3900 0022 001C <SPUBKEY>/<DPUBKEY>Errors: 000A Key generation error
| | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXT0013: File System Read
CommandsSection titled “Commands”Section titled “001E Access File” |
| Field | Length | Description |
|---|---|---|
FILENAME | variable | File path |
HANDLE | 4 bytes | Temporary file ID |
FILESIZE | 4 bytes | File size |
FILETIME | 4 bytes | Last modified time |
ATTR | 2 bytes | File attributes |
Errors: 0010 Read error, 0011 Not found, 0012 No free handles, 0013 Already open
001F Read FileRequest:
<TID> 3900 000C 001F <HANDLE> <OFFSET> <BLOCKLEN>Response:
<TID> 3900 <LEN> 001F <BLOCKDATA>Errors: 0010 Read error, 0011 Invalid handle, 0012 Out of bounds
| | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXT0014: File System Navigate
CommandsSection titled “Commands”Section titled “0020 Access Directory” |
| Field | Length | Description |
|---|---|---|
FILESIZE | 4 bytes | Size (0 for directories) |
FILETIME | 4 bytes | Last modified |
ATTR | 2 bytes | Attributes |
NAMELEN | 2 bytes | Name length |
NAME | NAMELEN | Item name |
Errors: 0010 Read error, 0011 Invalid handle, 0012 No free handles
| | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXT0015: File System Write
CommandsSection titled “Commands”Section titled “0022 Access File for Writing” |
| Field | Length | Description |
|---|---|---|
HANDLE | 4 bytes | File handle |
OFFSET | 4 bytes | Write position |
DATA | variable | Data to write |
FILESIZE | 4 bytes | Current file size |
Errors: 0010 Write error, 0011 Invalid handle, 0012 Invalid offset, 0013 No space
| |
|---|
EXT0016: File System Manage
Uses 32-bit file system element identifiers from other FS extensions. CommandsSection titled “Commands”Section titled “0024 Rename/Move Element” |