SharkRF IP Connector Protocol
C Makefile
Latest commit 140c9b8 Dec 24, 2016 @nonoo nonoo committed on GitHub Merge pull request #1 from maihde/master
Fixes related to compiling on OSX

README.md

SharkRF IP Connector Protocol

This is the protocol used by SharkRF openSPOT's UDP API to allow 3rd party developers to create their own applications which communicate using openSPOT.

The protocol is designed for simplicity: strings are closed with zeroes, and packets have redundant fields. For example: call info can be extracted from raw DMR frames, but the protocol includes them in the packets separately, so 3rd party developers don't need to deal with call tracking.

You can find a demo client and server application in this repo. The server is a very simple implementation, it can only handle one client at a time. However, handling multiple clients could be added easily.

Note that openSPOT doesn't use call information sent to it in the packets. It always extracts all required info from raw data streams.

Pull requests are welcome!

Protocol Description

Login process

Client has to start the connection with the login process. If NAK is received or timeout happens during the process, client has to retry logging in later. At least 5 seconds should be kept between retries, as server ignores frequent auth requests.

Login Process Diagram

Max. password length is 32 characters. Server limits auth tries for only one in every 5 seconds. Packets with invalid HMAC are ignored.

Config update (optional)

Client can optionally update it's config information.

Config Process Diagram

Ping

Client should ping the server periodically at least once every 30 seconds (5 seconds is recommended to keep firewalls open) after the last packet has sent to the server. No need to send ping if client transmits in this 5 second timeframe. The server ends the connection after 30 seconds of client inactivity.

Ping Process Diagram

Data

Data packets can be sent in both directions.

Data Diagram

Closing the connection

Both participants can close the connection gracefully.

Close Process Diagram 1

Close Process Diagram 2

Packet Structure

The protocol uses UDP as transport layer. Server listens on port 65100 by default.

UDP packet (srf_ip_conn_packet_t) structure:

Header Payload

See srf-ip-conn/common/srf-ip-conn-packet.h for used packet structures. Byte order is big-endian.