Free Radio Network Protocol

This protocol is used by the Free Radio Network Client for the communication with the System Manager and FRN Servers. The protocol with version number 2012000 was the first to be open for every developer who would like to implement a FRN Client program. Now we have the 2014000 version, compatible with the SystemManager and the current FRN Server 2014000 version. The information written below is preliminary. More text and illustration are to be added.

1. Data communication with the SystemManager

The SystemManager is reachable at sysman.freeradionetwork.eu, port 10025

1.1 Getting an account with password, or existing password

1. Make connection with the SystemManager.

2. Send the following string to the SystemManager:

'IG:<ON>[CallsignAndUser]</ON><EA>[EMailAddress]</EA><BC>[BandAndChannel]</BC><DS>[Description]</DS><NN>[Country]</NN><CT>[CityCityPart]</CT>'

Where:

3. Read the responce and disconnect. The SystemManager will give the following response: 'OK', 'NU' or something else.
If 'OK', then the send string is accepted and an email is on it's way to the applied email address.
If 'NU', then the username and password is already in use for another account.
Else the data is not ok.

1.2 Getting a Dynamic Password

The best way to connect a server is using a Dynamic Password rather then the fixed main password send by the email. Get this dynamic password every time the user wants to connect to a server, or every ones in a while.

1. Make connection with the SystemManager.

2. Send the following string to the SystemManager:

'DP:<EA>[EMailAddress]</EA><PW>[PassWord]</PW>'

Where:

3. The SystemManager will give the following responce: '-' if an error occurred or a string containing the dynamic password. If there is no communication with the SystemManager, then use the Dyn Password from the previous time.

1.3 Getting system explorer information

The information for the FRN Client's system explorer is fatched from the SystemManager. Best way to do is by using a thread.

1. Let this thread make contact to the SystemManager every minute.

2. After connection is established send the string 'SM'. The response will be a numeric string representing the server count.

3. Read the following data in a loop. Go thrue the loop as many times as the server count.
3.1 In this loop, first read the server name, then the net count.
3.2 Go thrue a sub loop as many times as the net count.
3.2.1 In this loop, first read the net name, then the client count.
3.2.2 Go thrue a sub loop as many times as the client count.
3.2.2.1 In this loop read the client info string.

4. Disconnect from the SystemManager.

The server name consist of the server address and the server port, divided by ' - Port: '.

The client info string has the following format:

'<ON>[CallsignAndUser]</ON><BC>[BandAndChannel]</BC><DS>[Description]</DS><NN>[Country]</NN><CT>[CityCityPart]</CT>'

where:

2. Data and voice communication with FRN Servers

The best way to exchange data and voice packets with a server is by using a thread. Do the following in this connection thread:

1. Establish connection with the server.

2. Run a tranceiver loop doing the following:
2.1 Transmit data from a data buffer.
2.2 Transmit voice packets or receive voice/data from server.
2.2.1 If in voip transmission mode send voice packets to the server.
2.2.2 Otherwice send 'P' and receive voice or data from the server.

3. Reconnect if the connection is lost.

2.1 Establish connection with a server

1. Connect to the server

2. Send the following connection string:

'CT:<VX>[Version]</VX><EA>[EMailAddress]</EA><PW>[DynPassWord]</PW><ON>[CallsignAndUser]</ON><CL>[ClientType]</CL><BC>[BandAndChannel]</BC><DS>[Description]</DS><NN>[Country]</NN><CT>[CityCityPart]</CT><NT>[Net]</NT>'

3. Read the server responce. The server will respond with two strings to be read out. The first string contains the latest releast protocol version number ('2014000'). This is used to trigger automatic FRN Client software update. The second has the following format:

<MT>[AccessInfo]</MT><SV>[ServerVersion]</SV><AL>[AccessLevel]</AL><BN>[BackUpServer]</BN><BP>[BackUpServerPort]</BP>

4. If the server responce is 'OWNER', 'NETOWNER', 'ADMIN' or 'OK'. send 'RX0' to the server.

2.2 The transceiver loop

The transceiver loop has a common data transmission part followed by two truncks, one for the case the client is transmitting and another one for the case the client is receiving or ready to receive.

2.2.1 Data transmission

Put the data to be send to the server in a buffer (a list of strings). Every time running through the transceiver loop, check if there is data to be send to the server. The following data can be send:

'TM:<ID>[ID]</ID><MS>[Message]</MS>'

'ST:[ClientStatus]'
Send the client status to the server

[ClientStatus]

Status of the client: 0: Available; listening and able to speak 1: Not available; listening not not able to speak 2: Absent; not listening not not able to speak

'BC:<ID>[ID]</ID>'
Block a client (Owners and admins only)

[ID]	ID of the client to be blocked

'UC:<ID>[ID]</ID>'

'MC:<ID>[ID]</ID>'
Mute a client (Owners and admin only). A muted client is only able to listen to the conversation on the net. Transmission to the net is not possible.

[ID]	ID of the client to be muted

'UM:<ID>[ID]</ID>'

'AA:<ID>[ID]</ID>'
Make a client admin (Server Owner only).

[ID]	ID of the client to become admin

'DA:<ID>[ID]</ID>'

'AT:<EA>[EMailAddress]</EA><NI>[NetIndex]</NI>'

[EMailAddress]	The email address of the the client to be access given to.
[NetIndex]	The index of the net where access is given for. If smaller then 0 (-1) then the access is given to the current net.

'DT:<EA>[EMailAddress]</EA>'

'ETX:<EA>[EMailAddress]</EA><NI>[NetIndex]</NI>'

'RTX:<EA>[EMailAddress]</EA><NI>[NetIndex]</NI>'

[EMailAddress]	The email address of the the client to give transmit rights.
[NetIndex]	The index of the net where transmit rights are given for. If smaller then 0 (-1) then the rights are are given to the current net.

'ENA:[Val]'

[EMailAddress]	The email address of the the client to give receive only rights.
[NetIndex]	The index of the net where receive only rights are given for. If smaller then 0 (-1) then the rights are are given to the current net.

[Val]

'0' Dissable access control '1' Enable access control. Only clients with access rights can connect.

'TXR:[Val]'

2.2.2 Transmit voice packets or receive voice/data from server

2.2.2.1 Send voice packets to the server

Start performing the Transmit trunk in the transceiver loop only after the DT_DO_TX byte is received from the server. This will happen if the client first sends the string 'TX0' to the server. This is the request for sending voip data.

1. If voice data buffer is not empty, transmit voip data by sending the string 'TX1' first, then the 325 bytes of voip data. If no data is available sleep or pause for 10 ms.

2. If user does not want to stop transmitting but the voice data buffer is empty, send 'TX0' to the server.

3. If user does want to stop transmitting (PTT button released) then first wait for the voice data buffer to be empty. If all the voice packets are transmitted, then send 'TX0' to the server. Or in other words: stack the 'TX0' command behind the last woice data in the list of data to be send. Do not send 'TX0' at the moment the PTT is released, otherwice the last part of the transmission will be last.

2.2.2.2 Receive voice or data from the server

If receiving, do the following:

1. Send 'P' to the server and read one byte from the server. This byte is the DataType, indicating the type of data that will follow right after. The DataType can have the following values:

2. If the user wants to transmit, send a request to send to the server at the end of the receive trunk. The request is done by sending 'TX0' to the server.