RCForb Protocol

RCForb uses a dynamic (asyc) protocol designed by (© 2006) KG6YPI & Brad DeMorrow. The concept is simple, the server notifies the clients of changes that may occur on the server when they occur. For example, if the frequency changes (either by a user or the radio itself), the server notifies all clients of the new frequency. The advantage of this protocol is clients do not have to constantly ask for information, using less bandwidth compared to other "Radio Over IP" based protocols. Another advantage, all clients stay perfectly "in-sync" with each other when the server notifies them of changes.

Developing Clients
Below is a description of the data sent between the server and client. The actual encoding of RCForb may vary between ASCII or Unicode. When RCForb is in ASCII mode, you can connect to it with a Telnet style client (Putty is a good one). When RCForb is in Unicode mode, there is no Telnet style client that will work. Only RCForb based clients will work in Unicode mode. To support Unicode mode take a look at the code examples at the bottom of this post.

Connecting to RCForb
On connection you need to send the "set protocol" command to initiate your connection in the server.
set protocol rcs

Once you set protocol, you will receive the current server's status.

Code:

set protocol rcs
post::id::RCForb
post::version::0.5.3870 b20143
post::driver::Dummy Radio (1.1)
post::radio::Dummy
post::buttons::TX,NB,NR,Notch
post::dropdowns::Mode,Filter
post::sliders::AF,Squelch,Pitch
post::frequency::16191886
post::frequencyB::431650201
post::smeter::S9+20,177,255
post::smeterB::S1,25,255
post::button::NB::0
post::button::Notch::0
post::button::NR::0
post::button::TX::0
post::list::Filter::6k,15k,50k,230k
post::list::Mode::AM,FM,USB,LSB,CW
post::dropdown::Filter::6k
post::dropdown::Mode::USB
post::range::AF::0,100,0
post::range::Pitch::0,100,0
post::range::Squelch::0,100,0
post::slider::AF::0
post::slider::Pitch::0
post::slider::Squelch::0
post::heartbeat::27s 641ms
post::time::8/6/2010 12:46:32 PM
post::lasttuner:: * Remote Open *
post::user_in::Guest-80

Reading Server Posts Messages
Most of the data posted from the server is "self explanatory", so we will only mention certain commands here.

Heartbeats
You must respond back to the post::heartbeat::{data} command with post::heartbeat::{data}
If not, you will be disconnected after about 30 seconds.
post::heartbeat::1234

User In/Out
post::user_in::{name}
post::user_out::{name}

Buttons
---

Dropdowns
The server sends a comma separated list of available dropdowns in the following command:
post::dropdowns::{list}

You will then receive the available items for the dropdown as follows:
post::list::{dropdown}::{items}

Finally you will receive the current state of the dropdown:
post::dropdown::{name}::{item}

Sliders
The server sends a comma separated list of available sliders in the following command:
post::sliders::{list}

You will then receive the range (min,max,offset) of the slider as follows:
post::range::{slider}::{data}

Finally you will receive the current state of the slider:
post::slider::{name}::{item}

Auth Messages
You will receive an auth message if you try to tune and you do not have permission.
post::auth::{message}

Error Message
post::error::{message}

Info Messages
post::info::{message}

Warning Messages
post::warning::{message}

Radio In-Use Status
post::radio-open::{message}
post::radio-in-use::{inuse_by}::{message}
post::radio-closed::{message}

Login with RemoteHams.com account
The login command uses the following format
login {user_name} {pass_md5_lower_case}

To login with a username of 'test' and a password of 'password' the command would be
login test 5f4dcc3b5aa765d61d8327deb882cf99

Posting Chats
post::chat::{message}
post::chat::hello

Setting Frequency
post::frequency::{freq_in_hertz}
post::frequency::50125000

Setting Buttons
post::button::{name}::{data}
post::button::TX::1

Setting Dropdowns
post::dropdown::{name}::{data}
post::dropdown::Mode::AM

Setting Sliders
post::slider::{name}::{data}
post::slider::Squelch::5

Supporting Unicode in RCForb Protocol
RCForb handles Unicode in a non-standard way. All of the Unicode characters are not fully supported (due to a 2 byte limit imposed by RCForb). RCForb receives and sends 2 bytes at a time in Unicode mode. When in ASCII mode receives and sends 1 byte at a time. Below is a bare-bones example C# Socket Client to connect to RCForb in Unicode mode to better explain this to Programmers.

Code:

TODO