Free Radio Network Protocol
Free Radio Network ProtocolThis protocol is used by the Free Radio Network Client for the communication with the System Manager and FRN Servers. This was a closed protocol not mend to be used by third parties. The new protocol with version number 2012000 will be open for every developer who would like to implement a FRN Client program. The 2012000 version is compatible with the SystemManager, but not with the current FRN Server version. A beta server is running with the 2012000 protocol, so developers are able to test there code with this server. This test serverver is the hambu.freeradionetwork.nl with port 10024. Later on FRN Server 2012000 will be released. The information written below is preliminary. More text and illustration are to be added.
The SystemManager is reachable at frn.no-ip.info, port 10025
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 band in full Mhz, followed by ' Ch' followed by the channel number, mode and CTCSS or DCS code. |
| [Description] | Add optional extra info here. Typically it is the frequency of the channel and the frequency of the CTCSS or DCS code. |
| [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.
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.
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 band in full Mhz, followed by ' Ch' followed by the channel number, mode and CTCSS or DCS code. |
| [Description] | extra information on the gateway, typically the frequency of the channel and the frequency of the CTCSS or DCS code. |
| [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') |
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.
1. Connect to the server
2. Send the following connection string:
'CT:<VX>[Version]</VX><EA>[EMailAddress]</EA><PW>[DynPassWord]</PW><ON>[CallsignAndUser]</ON><BC>[BandAndChannel]</BC><DS>[Description]</DS><NN>[Country]</NN><CT>[CityCityPart]</CT><NT>[Net]</NT>'
| [Version] | String containing the protocol version number ('2012000') |
| [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. |
| [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 band in full Mhz, followed by ' Ch' followed by the channel number, mode and CTCSS or DCS code. |
| [Description] | extra information on the gateway, typically the frequency of the channel and the frequency of the CTCSS or DCS code. |
| [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 ('2011003'). 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 owner 'ADMIN': The client is connected as admin 'OK': The client is connected as normal user 'WRONG': The username ans 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', 'ADMIN' or 'OK'. send 'RX0' to the server.
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.
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:
'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 (Admin only)
| [ID] | ID of the client to be blocked |
'MC:<ID>[ID]</ID>'
Mute a client (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 |
'AA:<ID>[ID]</ID>'
Make a client admin (Server Owner only).
| [ID] | ID of the client to become admin |
'AT:<EA>[EMailAddress]</EA>'
'RTX:<EA>[EMailAddress]'</EA>
'ETX:<EA>[EMailAddress]</EA>'
'ENA:[Val]'
| [Val] |
'0' '1' |
'TXR:[Val]'
| [Val] |
'0' '1' |
'UC:<ID>[ID]</ID>'
'UM:<ID>[ID]</ID>'
'DA:<ID>[ID]</ID>'
'DT:<EA>[EMailAddress]</EA>'
'TM:<ID>[ID]</ID><MS>[Message]</MS>'
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 and voice data buffer is empty, send 'TX0' to 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, inicating 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><ON>[CallsignAndUser]</ON><ID>[ID]</ID><DS>[Description]</DS>'
|
||||||||||||||||
| 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 and of the receive trunk. The request is done by sending 'TX0' to the server.