Basic Protocol

Ta treść nie jest jeszcze dostępna w Twoim języku.

Document status: Approved (2020-02-01)

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 0000 Handshake to get device type/version and supported extensions.

If there’s no exchange for a period, the server terminates the connection. To prevent this, the client must regularly send 0001 Keep Alive or other commands. The timeout is transmitted in the Handshake response (KA field).

The server must respond within 10 seconds, otherwise the client may terminate or repeat the request.

Request and Response Format

<TID> <PID> <LEN> <CMD> <DATA>

Fields are coded Big Endian (most significant byte first).

Field	Length	Description
`TID`	2 bytes	Transaction number
`PID`	2 bytes	Protocol ID, always `0x3900`
`LEN`	2 bytes	Package length (excluding TID, PID, LEN)
`CMD`	2 bytes	Command code
`DATA`	`LEN - 2`	Data field

Maximum packet length is 65535 bytes, but devices may set smaller limits via FLIM field in Handshake response.

Error Response

<TID> 3900 0004 <ECMD> <ERROR>

Where ECMD is the command code with MSB set (<CMD> + 0x8000) and ERROR is 2-byte error code.

Common Error Codes

Code	Description
`0001`	Unknown error
`0002`	Device I/O error
`0003`	Device busy (try again later)
`0004`	Invalid LEN field
`0005`	Unknown command
`0006`	Invalid DATA field
`0007`	No access rights

Commands

`0000` Handshake

Request meta-information about the device.

Request:

<TID> 3900 0002 0000

Response:

<TID> 3900 <LEN> 0000 <IC> <HW> <FW> <FLIM> <KA> [<EXT> ...]

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 Alive

Maintain connection when no other requests are needed.