00001 // RCOIP.h 00002 // 00003 // Definitions for the RCOIP (Remote Control Over IP) protocol 00004 // These definitions are kept in a single header with no expectation 00005 // of programming language so that C, C++ and Objective-C can be supported 00006 // 00007 /// \file RCOIP.h 00008 /// \class RCOIP RCOIP.h 00009 /// \brief This section describes the RCOIP (Remote Control Over IP) protocol. 00010 /// 00011 /// RCOIP protocol is used to 00012 /// carry remote control commands from a Transmitter to a Receiver over an IP 00013 /// transport such as Ethernet or Wi-Fi. 00014 /// 00015 /// The RCOIP protocol is a 2-way protocol that defines UDP messages between 00016 /// an RCOIP Transmitter and Receiver. 00017 /// 00018 /// \par Terminology 00019 /// 00020 /// This protocol is intended to carry command and status messages between a pair of devices 00021 /// that act like a conventional Remote Control or Radio Control (RC) transmitter and receiver. 00022 /// The effect is that commands sent from the transmitter to the receiver cause the reciever to 00023 /// change its behaviour (perhaps by changing the output value on a pin controlling a servo or motor) 00024 /// Unlike conventional RC receivers, an RCOIP receiver can also send useful and interesting telemetry 00025 /// data back to the receiver (albeit at a lower priority). 00026 /// 00027 /// So, Commands are sent from the Transmitter to the Receiver over UDP, and periodically in response, 00028 /// Replies are sent by UDP from the Receiver to the Transmitter. 00029 /// 00030 /// This effectively makes the Transmitter a UDP client and the Receiver a UDP server. 00031 /// Messages sent from the Transmitter to the Receiver include commands to set analog outputs, 00032 /// and messages from the Receiver to the Transmitter include Receiver status messages. 00033 /// 00034 /// The Receiver is typically a lightweight, low cost device with limitated computation ability. 00035 /// Typical Receiver devices are Arduino microcontrollers with WiShield Wi-Fi support. 00036 /// 00037 /// The Transmitter might be heavier and support more features such as interactive user interfaces etc. 00038 /// Typical Transmitters might be iPhone, iPad or Arduino+WiShield devices. 00039 /// The transmitter might look and operate like or simulate a conventional RC transmitter. 00040 /// 00041 /// The User is a person (or possibly a program) that uses the Transmitter to send commands to the 00042 /// Receiver in order for the Receiver to do the bidding of the User. 00043 /// This will typically be a person holding a Transmitter device and manipulating its controls in 00044 /// order to control a vehicle with an embedded Receiver. 00045 /// 00046 /// The messages sent by the Transmitter to the Receiver might include Channel data. 00047 /// Each channel is an analog value in the range 0 to 255. Each channel is typically controled by some 00048 /// physical input on the Transmitter. 00049 /// Each Channel 00050 /// causes some physical effect in the Receiver, and is typically alter by moving some control 00051 /// on the Transmitter. The physical interpretation of Channels and their values is dependent on the 00052 /// configuration of the Receiver, and the Transmiter and Receiver are expected to be configured 00053 /// so their interprtation of what each Channel is used for should agree. For example, in one configuration 00054 /// Channel 0 might be throttle, Channel 1 might be aileron and Channel 2 might be undercarriage. 00055 /// And in another configuration, Channel 0 might be steering, Channel 1 might be throttle and 00056 /// Channel 2 might be horn on/off. 00057 /// 00058 /// \par IP Network configurations 00059 /// 00060 /// RCOIP is intended to be carried over almost any type of network that can carry IP, 00061 /// including Wired and Wireless (Wi-Fi) networks. RCOIP does not make any mandatory requirements on 00062 /// networks and address, but recommendations for commonly used conventions are given below. 00063 /// 00064 /// The most common and recommended network is a point-to-point ad-hoc Wi-Fi network connection 00065 /// between the Transmitter and the Receiver. Transmitter and Receiver must agree on the SSID 00066 /// (the network identifier) and 00067 /// whether the ad-hoc network to be used requires encryption (WEP, WPA, WPA2). 00068 /// Typically, static IP addresses would be used on such a network. 00069 /// The recommended static IP addresses for such an ad-hoc network connection are 00070 /// \li Transmitter 169.254.1.1 00071 /// \li Receiver 169.254.1.100 00072 /// 00073 /// Another common model is for both Receiver and Transmitter to connect to a mutual infrastructure 00074 /// Wi-Fi network. In this model, either of both Transmitter or Receiver might be configured to get a 00075 /// dynamic IP address using DHCP. Otherwise they may be configured with static IP addresses compatible wit 00076 /// the supporting network. 00077 /// 00078 /// Any agreed upon UDP port may be used to carry RCOIP, but the recommended ports are 9048 for the Receiver, 00079 /// and any (unspecified) host allocated port number for the Transmitter. Port 9048 is controlled by 00080 /// Open System Consultants (http://www.open.com.au), 00081 /// and permission is granted by them to use 9048 as the recommnded port for RCOIP 00082 /// 00083 /// \par RCOIP Protocol Version 1 00084 /// 00085 /// Whenever the User alters a control or setting on the Transmitter, 00086 /// the Transmitter sends a RCOIPv1CmdSetAnalogChannels message to the 00087 /// Receiver. RCOIPv1CmdSetAnalogChannels contains the new desired output value for all the defined 00088 /// output channels. 00089 /// 00090 /// Whenever the Receiver receives a RCOIPCmdSetAnalogChannels it might reply with a RCOIPv1ReplyReceiverStatus 00091 /// message. However, in order limit bandwidth and battery power requirements, it does not reply to 00092 /// every RCOIPv1CmdSetAnalogChannels, but only so that it replies at most every ReplyInterval milliseconds. 00093 /// The recommended value for ReplyInterval is 1000 milliseconds. 00094 /// 00095 /// RCOIPv1CmdSetAnalogChannels can contain 0 or more analog output values. 00096 /// The maximum number of analog channels is dictatated by the maximum UDP packet size 00097 /// supported by the network, however a minimum of at least 100 channels is expected. 00098 /// Only the number of channels configured into the Transmitter are sent. 00099 /// 00100 /// The interpretation of the channel values is dependent on the configuration of the receiver. 00101 /// Each channel value is an 8 bit octet interpreted as an unsigned integer, ranging from 0 to 255 inclusive. 00102 /// 0 is to be interpreted by the Receiver as 'minimum' and 255 as 'maximum', but the exact physical effect 00103 /// of each channel and the channel values is completely dependent on the configuration of the Receiver. 00104 /// Channel values that are expected by the Receiver but which have not (yet) been received 00105 /// from the Transmitter are to be interprted as 0. The Receiver is to maintain the output corresponding 00106 /// to the last received RCOIPv1CmdSetAnalogChannels message until and unless failure detection results in 00107 /// a failsafe configuration (see below). 00108 /// 00109 /// As can be seen from the above discussion, RCOIP is not a 'reliable' protocol in the sense that it does not 00110 /// use acknowledgements in order to guarantee delivery of messages. 00111 /// It relies on the 'best efforts' of the network, and the transmission of multiple messages to 00112 /// deal with network packet loss and delivery problems. Transmitter and Receiver can use absence of received 00113 /// messages for a period of time as a hint of loss of communications. This is discussed further below. 00114 /// 00115 /// \par Keepalive and failure detection 00116 /// 00117 /// In order to assist with the detection of communications failure between the Transmitter and he Receiver, 00118 /// a system of keepalive messages is defined. 00119 /// 00120 /// The Transmitter is required to send a message to the receiver at least every KeepaliveInterval milliseconds. 00121 /// The reecommended value for KeepaliveInterval is 1000 milliseconds. Any command may be sent 00122 /// as the keepalive, but RCOIPv1CmdSetAnalogChannels is recommended 00123 /// (note: at present there is only one command message defined, and it is RCOIPv1CmdSetAnalogChannels) 00124 /// 00125 /// When the Receiver receives a keepalive message it will respond in the usual way, 00126 /// by sending a RCOIPv1ReplyReceiverStatus back to the transmitter, provided it is more than 00127 /// ReplyInterval milliseconds since the last reply. 00128 /// 00129 /// If the Receiver does not receive any Command messages for more than FailInterval milliseconds, the Receiver 00130 /// detects loss of communication with the Transmitter and may adopt a failsafe configuration. 00131 /// 00132 /// If the Transmitter does not receive any Reply messages for more than FailInterval milliseconds, 00133 /// the Transmitter 00134 /// detects loss of communication with the receiver and may react in whatever appropriate way, 00135 /// such as informing the User. 00136 /// 00137 /// If the Receiver detects loss of communication with the Transmitter, it is free to respond in whatever 00138 /// way is appropriate. The recommended and safest way is for the Receiver to adopt a 'failsafe' configuration, 00139 /// typically by reducing any motor or throttle outputs to 0, off, stopped or safe. If, subsequent to a 00140 /// communications failure and a failsafe 00141 /// configuration, the Receiver again detects Commands from the Transmitter, it may recommence 00142 /// normal operations however, it is recommended that the Receiver remain in the failsafe configuration 00143 /// until perhaps manually reset. 00144 /// 00145 // Copyright (C) 2010 Mike McCauley 00146 // $Id: RCOIP.h,v 1.3 2010/06/30 02:48:59 mikem Exp mikem $ 00147 00148 #ifndef RCOIP_h 00149 #define RCOIP_h 00150 00151 // RCOIP (Remote Control Over IP) versions we know about 00152 00153 /// \def RC_VERSION1 00154 /// Indicates Version 1 of RCOIP protocol 00155 #define RC_VERSION1 1 00156 00157 /// \def RC_VERSION 00158 /// This is the default (latest) version of the RCOIP protocol 00159 #define RC_VERSION RC_VERSION1 00160 00161 /// \def RCOIP_DEFAULT_REPLY_INTERVAL 00162 /// Defines the default maximum time in milliseconds between Reply messages 00163 /// sent by the receiver 00164 #define RCOIP_DEFAULT_REPLY_INTERVAL 1000 00165 00166 /// \def RCOIP_DEFAULT_FAIL_INTERVAL 00167 /// Defines the default maximum time in milliseconds between that will be regarded as a loss of connection 00168 /// by either the receiver or the transmitter 00169 #define RCOIP_DEFAULT_FAIL_INTERVAL 2000 00170 00171 /// \def RCOIP_DEFAULT_KEEPALIVE_INTERVAL 00172 /// Defines the default time in milliseconds between keepalaive Command messages 00173 /// sent by the receiver. If no messages are transmitted for more than this period of time 00174 /// a keepalive Command message will be sent to the receiver. 00175 #define RCOIP_DEFAULT_KEEPALIVE_INTERVAL 1000 00176 00177 /// \def RCOIP_DEFAULT_RECEIVER_UDP_PORT 00178 /// Defines the default RCOIP receiver UDP port number 00179 /// 9048 is controlled by Open System Consultants 00180 #define RCOIP_DEFAULT_RECEIVER_UDP_PORT 9048 00181 00182 ///////////////////////////////////////////////////////////////////// 00183 /// \struct RCOIPv1CmdSetAnalogChannels 00184 /// \brief SetAnalogChannels command message structure 00185 /// 00186 /// Defines the structure over-the-wire of 00187 /// a Version 1 SetAnalogChannels command 00188 typedef struct 00189 { 00190 /// The RCOIP version number. 00191 /// Must be set to RC_VERSION1 00192 uint8_t version; 00193 00194 /// 0 or more analog channel values, one per octet. 00195 /// Channel values range from 0 (minimum) to 255 (maximum) inclusive. 00196 /// The physical meaning of channel values and how they map to output devices and pins 00197 /// depends on how the channel is interpreted at the Receiver. 00198 /// Channels which represent simple on-off channels are expected to be 0 for 'off' and any other 00199 /// value for 'on'. 00200 uint8_t channels[0]; 00201 00202 } RCOIPv1CmdSetAnalogChannels; 00203 00204 00205 ///////////////////////////////////////////////////////////////////// 00206 /// \struct RCOIPv1ReplyReceiverStatus 00207 /// \brief ReceiverStatus reply message structure 00208 /// 00209 /// Defines the structure over-the-wire of 00210 /// a Version 1 ReceiverStatus reply 00211 typedef struct 00212 { 00213 /// The RCOIP version number. 00214 /// Must be set to RC_VERSION1 00215 uint8_t version; 00216 00217 /// The value of the RSSI (Receiver Signal Strength Indicator) as measured by the receiver 00218 /// in the last received message. Arbitrary units. If not available, set to 0. 00219 uint8_t RSSI; 00220 00221 /// The current value of the Receiver's battery voltage. 00222 /// 0 means 0V. 255 means 15.0V 00223 uint8_t batteryVoltage; 00224 00225 } RCOIPv1ReplyReceiverStatus; 00226 00227 /// \typedef RCOIPCmdSetAnalogChannels 00228 /// This is the preferred type to use to refer to the latest version of 00229 /// the RCOIPCmdSetAnalogChannels message 00230 typedef RCOIPv1CmdSetAnalogChannels RCOIPCmdSetAnalogChannels; 00231 00232 /// \typedef RCOIPReplyReceiverStatus 00233 /// This is the preferred type to use to refer to the latest version of 00234 /// the RCOIPReplyReceiverStatus message 00235 typedef RCOIPv1ReplyReceiverStatus RCOIPReplyReceiverStatus; 00236 00237 #endif