Free Radio Network
Change language Change language
Home Home
FRN Gateways FRN Gateways
Who's on-line? Who's on-line?
FRN Client software FRN Client
Interface Interface
Com Port Inteface Com Port Interface
JOTA JOTA
Downloads Downloads
the forum Forum
Links Developers

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:

[CallsignAndUser] Is username or callsign and username. Place a comma and space ', ' between callsign and username.
[EMailAddress] is the user's email address
[BandAndChannel] In case of PC only user, this is 'PC Only'.
In case of a cross-link this is 'Crosslink'.
In case of a gateway this is the frequancy in full Mhz and kHz seperated by a '.' (dot), followed by the mode 'FM', 'AM' or 'DIG', followed by a spce and the squelch type 'CTC', 'DSC' or 'NONE' followed by the CTC frequency or ID code.
Examples:
446.03125FM CTC131.8
28.12500AM
145.43750FM DCS828
446.02625DIG CID123
[Description] Add optional extra info here. (Channel number, ctcs code nr, etc).
[Country] The country
[CityCityPart] The city and the part of the city, or the part of the country and the city divided by a minus sign.
('den Haag - Moerwijk' or 'Maastricht - Limburg')

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:

[EMailAddress] is the user's email address
[PassWord] main password send by the email

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:

[CallsignAndUser] is username or callsign and username.
[BandAndChannel] In case of PC only user, this is 'PC Only'.
In case of a crosslink this is 'Crosslink'.
In case of a gateway this is the frequancy in full Mhz and kHz seperated by a '.' (dot), followed by the mode 'FM', 'AM' or 'DIG', followed by a spce and the squelch type 'CTC', 'DSC' or 'NONE' followed by the CTC frequency or ID code.
Examples:
446.03125FM CTC131.8
28.12500AM
145.43750FM DCS828
446.02625DIG CID123
[Description] Add optional extra info here. (Channel number, ctcs code nr, etc).
[Country] The country
[CityCityPart] The city and the part of the city, or the part of the country and the city divided by a minus sign.
('den Haag - Moerwijk' or 'Maastricht - Limburg')

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>'

[Version] String containing the protocol version number ('2014000')
[EMailAddress] is the user's email address
[DynPassWord] The dynamic password. If not available, the main password can be used.
[CallsignAndUser] is username or callsign and username.
[ClientType] '0' : Crosslink
'1' : Gateway
'2' : PC Only
[BandAndChannel] In case of PC only user, this is 'PC Only'.
In case of a crosslink this is 'Crosslink'.
In case of a gateway this is the frequancy in full Mhz and kHz seperated by a '.' (dot), followed by the mode 'FM', 'AM' or 'DIG', followed by a spce and the squelch type 'CTC', 'DSC' or 'NONE' followed by the CTC frequency or ID code.
Examples:
446.03125FM CTC131.8
28.12500AM
145.43750FM DCS828
446.02625DIG CID123
[Description] Add optional extra info here. (Channel number, ctcs code nr, etc).
[Country] The country
[CityCityPart] The city and the part of the city, or the part of the country and the city divided by a minus sign.
('den Haag - Moerwijk' or 'Maastricht - Limburg')
[Net] The net where the user wants to connect with.

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>

[AccessInfo] A HTML string containing information on the connected net.
[ServerVersion] The version of the server
[AccessLevel] 'OWNER': The client is connected as the owner of the server
'NETOWNER': The client is connected as owner of the net (room)
'ADMIN': The client is connected as admin
'OK': The client is connected as normal user
'WRONG': The username and ore password is wrong, or account does not exist
'BLOCK': The client is blocked from this net.
[BackUpServer] The backup server to be connected if connection to this server is not possible.
[BackUpServerPort] The port of the backup server.

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]'

[Val] '0' Dissable transmit rigths control
'1' Enable transmit rights control. Only clients with transmit rights can send audio to server.

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:

0 = DT_IDLE There is now new info or voip data. No more data needs to be read out. There is no active client.
1 = DT_DO_TX With this the server is indicating that you may start sending voip data. This is a response to the request to send string 'TX0' Right after the DT_DO_TX byte, two bytes are send containing the list index of the active client in the client list.
2 = DT_VOICE_BUFFER Voip data will be send. First two bytes will be send containing the list index of the active client, then 325 bytes of encoded voice data will be send. The codec and audio format will be explained later.
3 = DT_CLIENT_LIST

The client lists will be send. Typically this happens if your client connects and when one other client connects or disconnects. The first two bytes send after DT_CLIENT_LIST are again the active client index. Then a string will be send, containing an integer value. This is the amount of strings that will follow. These strings have the following format:

'<S>[Status]</S><M>[Muted]</M><NN>[Country]'</NN><CT>[CityCityPart]</CT><BC>[BandAndChannel]</BC><CL>[ClientType]</CL><ON>[CallsignAndUser]</ON><ID>[ID]</ID><DS>[Description]</DS>'

[Status]
[Muted]
[Country]
[CityCityPart]
[BandAndChannel]
[ClientType] '0' : Crosslink
'1' : Gateway
'2' : PC Only
[CallsignAndUser]
[ID]
[Description]
4 = DT_TEXT_MESSAGE
5 = DT_NET_NAMES
6 = DT_ADMIN_LIST
7 = DT_ACCESS_LIST
8 = DT_BLOCK_LIST
9 = DT_MUTE_LIST
10 = DT_ACCESS_MODE
Any other > 10

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.