|
RCKit
|
This section describes the RCOIP (Remote Control Over IP) protocol. More...
#include <RCOIP.h>
This section describes the RCOIP (Remote Control Over IP) protocol.
RCOIP protocol is used to carry remote control commands from a Transmitter to a Receiver over an IP transport such as Ethernet or Wi-Fi.
The RCOIP protocol is a 2-way protocol that defines UDP messages between an RCOIP Transmitter and Receiver.
This protocol is intended to carry command and status messages between a pair of devices that act like a conventional Remote Control or Radio Control (RC) transmitter and receiver. The effect is that commands sent from the transmitter to the receiver cause the reciever to change its behaviour (perhaps by changing the output value on a pin controlling a servo or motor) Unlike conventional RC receivers, an RCOIP receiver can also send useful and interesting telemetry data back to the receiver (albeit at a lower priority).
So, Commands are sent from the Transmitter to the Receiver over UDP, and periodically in response, Replies are sent by UDP from the Receiver to the Transmitter.
This effectively makes the Transmitter a UDP client and the Receiver a UDP server. Messages sent from the Transmitter to the Receiver include commands to set analog outputs, and messages from the Receiver to the Transmitter include Receiver status messages.
The Receiver is typically a lightweight, low cost device with limitated computation ability. Typical Receiver devices are Arduino microcontrollers with WiShield Wi-Fi support.
The Transmitter might be heavier and support more features such as interactive user interfaces etc. Typical Transmitters might be iPhone, iPad or Arduino+WiShield devices. The transmitter might look and operate like or simulate a conventional RC transmitter.
The User is a person (or possibly a program) that uses the Transmitter to send commands to the Receiver in order for the Receiver to do the bidding of the User. This will typically be a person holding a Transmitter device and manipulating its controls in order to control a vehicle with an embedded Receiver.
The messages sent by the Transmitter to the Receiver might include Channel data. Each channel is an analog value in the range 0 to 255. Each channel is typically controled by some physical input on the Transmitter. Each Channel causes some physical effect in the Receiver, and is typically alter by moving some control on the Transmitter. The physical interpretation of Channels and their values is dependent on the configuration of the Receiver, and the Transmiter and Receiver are expected to be configured so their interprtation of what each Channel is used for should agree. For example, in one configuration Channel 0 might be throttle, Channel 1 might be aileron and Channel 2 might be undercarriage. And in another configuration, Channel 0 might be steering, Channel 1 might be throttle and Channel 2 might be horn on/off.
RCOIP is intended to be carried over almost any type of network that can carry IP, including Wired and Wireless (Wi-Fi) networks. RCOIP does not make any mandatory requirements on networks and address, but recommendations for commonly used conventions are given below.
The most common and recommended network is a point-to-point ad-hoc Wi-Fi network connection between the Transmitter and the Receiver. Transmitter and Receiver must agree on the SSID (the network identifier) and whether the ad-hoc network to be used requires encryption (WEP, WPA, WPA2). Typically, static IP addresses would be used on such a network. The recommended static IP addresses for such an ad-hoc network connection are
Another common model is for both Receiver and Transmitter to connect to a mutual infrastructure Wi-Fi network. In this model, either of both Transmitter or Receiver might be configured to get a dynamic IP address using DHCP. Otherwise they may be configured with static IP addresses compatible wit the supporting network.
Any agreed upon UDP port may be used to carry RCOIP, but the recommended ports are 9048 for the Receiver, and any (unspecified) host allocated port number for the Transmitter. Port 9048 is controlled by Open System Consultants (http://www.airspayce.com), and permission is granted by them to use 9048 as the recommended port for RCOIP
Whenever the User alters a control or setting on the Transmitter, the Transmitter sends a RCOIPv1CmdSetAnalogChannels message to the Receiver. RCOIPv1CmdSetAnalogChannels contains the new desired output value for all the defined output channels.
Whenever the Receiver receives a RCOIPCmdSetAnalogChannels it might reply with a RCOIPv1ReplyReceiverStatus message. However, in order limit bandwidth and battery power requirements, it does not reply to every RCOIPv1CmdSetAnalogChannels, but only so that it replies at most every ReplyInterval milliseconds. The recommended value for ReplyInterval is 1000 milliseconds.
RCOIPv1CmdSetAnalogChannels can contain 0 or more analog output values. The maximum number of analog channels is dictatated by the maximum UDP packet size supported by the network, however a minimum of at least 100 channels is expected. Only the number of channels configured into the Transmitter are sent.
The interpretation of the channel values is dependent on the configuration of the receiver. Each channel value is an 8 bit octet interpreted as an unsigned integer, ranging from 0 to 255 inclusive. 0 is to be interpreted by the Receiver as 'minimum' and 255 as 'maximum', but the exact physical effect of each channel and the channel values is completely dependent on the configuration of the Receiver. Channel values that are expected by the Receiver but which have not (yet) been received from the Transmitter are to be interprted as 0. The Receiver is to maintain the output corresponding to the last received RCOIPv1CmdSetAnalogChannels message until and unless failure detection results in a failsafe configuration (see below).
As can be seen from the above discussion, RCOIP is not a 'reliable' protocol in the sense that it does not use acknowledgements in order to guarantee delivery of messages. It relies on the 'best efforts' of the network, and the transmission of multiple messages to deal with network packet loss and delivery problems. Transmitter and Receiver can use absence of received messages for a period of time as a hint of loss of communications. This is discussed further below.
In order to assist with the detection of communications failure between the Transmitter and he Receiver, a system of keepalive messages is defined.
The Transmitter is required to send a message to the receiver at least every KeepaliveInterval milliseconds. The reecommended value for KeepaliveInterval is 1000 milliseconds. Any command may be sent as the keepalive, but RCOIPv1CmdSetAnalogChannels is recommended (note: at present there is only one command message defined, and it is RCOIPv1CmdSetAnalogChannels)
When the Receiver receives a keepalive message it will respond in the usual way, by sending a RCOIPv1ReplyReceiverStatus back to the transmitter, provided it is more than ReplyInterval milliseconds since the last reply.
If the Receiver does not receive any Command messages for more than FailInterval milliseconds, the Receiver detects loss of communication with the Transmitter and may adopt a failsafe configuration.
If the Transmitter does not receive any Reply messages for more than FailInterval milliseconds, the Transmitter detects loss of communication with the receiver and may react in whatever appropriate way, such as informing the User.
If the Receiver detects loss of communication with the Transmitter, it is free to respond in whatever way is appropriate. The recommended and safest way is for the Receiver to adopt a 'failsafe' configuration, typically by reducing any motor or throttle outputs to 0, off, stopped or safe. If, subsequent to a communications failure and a failsafe configuration, the Receiver again detects Commands from the Transmitter, it may recommence normal operations however, it is recommended that the Receiver remain in the failsafe configuration until perhaps manually reset.
1.8.17