RCKit
RCOIP.h
Go to the documentation of this file.
1 // RCOIP.h
2 //
3 // Definitions for the RCOIP (Remote Control Over IP) protocol
4 // These definitions are kept in a single header with no expectation
5 // of programming language so that C, C++ and Objective-C can be supported
6 //
7 /// \file RCOIP.h
8 /// \class RCOIP RCOIP.h
9 /// \brief This section describes the RCOIP (Remote Control Over IP) protocol.
10 ///
11 /// RCOIP protocol is used to
12 /// carry remote control commands from a Transmitter to a Receiver over an IP
13 /// transport such as Ethernet or Wi-Fi.
14 ///
15 /// The RCOIP protocol is a 2-way protocol that defines UDP messages between
16 /// an RCOIP Transmitter and Receiver.
17 ///
18 /// \par Terminology
19 ///
20 /// This protocol is intended to carry command and status messages between a pair of devices
21 /// that act like a conventional Remote Control or Radio Control (RC) transmitter and receiver.
22 /// The effect is that commands sent from the transmitter to the receiver cause the reciever to
23 /// change its behaviour (perhaps by changing the output value on a pin controlling a servo or motor)
24 /// Unlike conventional RC receivers, an RCOIP receiver can also send useful and interesting telemetry
25 /// data back to the receiver (albeit at a lower priority).
26 ///
27 /// So, Commands are sent from the Transmitter to the Receiver over UDP, and periodically in response,
28 /// Replies are sent by UDP from the Receiver to the Transmitter.
29 ///
30 /// This effectively makes the Transmitter a UDP client and the Receiver a UDP server.
31 /// Messages sent from the Transmitter to the Receiver include commands to set analog outputs,
32 /// and messages from the Receiver to the Transmitter include Receiver status messages.
33 ///
34 /// The Receiver is typically a lightweight, low cost device with limitated computation ability.
35 /// Typical Receiver devices are Arduino microcontrollers with WiShield Wi-Fi support.
36 ///
37 /// The Transmitter might be heavier and support more features such as interactive user interfaces etc.
38 /// Typical Transmitters might be iPhone, iPad or Arduino+WiShield devices.
39 /// The transmitter might look and operate like or simulate a conventional RC transmitter.
40 ///
41 /// The User is a person (or possibly a program) that uses the Transmitter to send commands to the
42 /// Receiver in order for the Receiver to do the bidding of the User.
43 /// This will typically be a person holding a Transmitter device and manipulating its controls in
44 /// order to control a vehicle with an embedded Receiver.
45 ///
46 /// The messages sent by the Transmitter to the Receiver might include Channel data.
47 /// Each channel is an analog value in the range 0 to 255. Each channel is typically controled by some
48 /// physical input on the Transmitter.
49 /// Each Channel
50 /// causes some physical effect in the Receiver, and is typically alter by moving some control
51 /// on the Transmitter. The physical interpretation of Channels and their values is dependent on the
52 /// configuration of the Receiver, and the Transmiter and Receiver are expected to be configured
53 /// so their interprtation of what each Channel is used for should agree. For example, in one configuration
54 /// Channel 0 might be throttle, Channel 1 might be aileron and Channel 2 might be undercarriage.
55 /// And in another configuration, Channel 0 might be steering, Channel 1 might be throttle and
56 /// Channel 2 might be horn on/off.
57 ///
58 /// \par IP Network configurations
59 ///
60 /// RCOIP is intended to be carried over almost any type of network that can carry IP,
61 /// including Wired and Wireless (Wi-Fi) networks. RCOIP does not make any mandatory requirements on
62 /// networks and address, but recommendations for commonly used conventions are given below.
63 ///
64 /// The most common and recommended network is a point-to-point ad-hoc Wi-Fi network connection
65 /// between the Transmitter and the Receiver. Transmitter and Receiver must agree on the SSID
66 /// (the network identifier) and
67 /// whether the ad-hoc network to be used requires encryption (WEP, WPA, WPA2).
68 /// Typically, static IP addresses would be used on such a network.
69 /// The recommended static IP addresses for such an ad-hoc network connection are
70 /// \li Transmitter 169.254.1.1
71 /// \li Receiver 169.254.1.100
72 ///
73 /// Another common model is for both Receiver and Transmitter to connect to a mutual infrastructure
74 /// Wi-Fi network. In this model, either of both Transmitter or Receiver might be configured to get a
75 /// dynamic IP address using DHCP. Otherwise they may be configured with static IP addresses compatible wit
76 /// the supporting network.
77 ///
78 /// Any agreed upon UDP port may be used to carry RCOIP, but the recommended ports are 9048 for the Receiver,
79 /// and any (unspecified) host allocated port number for the Transmitter. Port 9048 is controlled by
80 /// Open System Consultants (http://www.airspayce.com),
81 /// and permission is granted by them to use 9048 as the recommended port for RCOIP
82 ///
83 /// \par RCOIP Protocol Version 1
84 ///
85 /// Whenever the User alters a control or setting on the Transmitter,
86 /// the Transmitter sends a RCOIPv1CmdSetAnalogChannels message to the
87 /// Receiver. RCOIPv1CmdSetAnalogChannels contains the new desired output value for all the defined
88 /// output channels.
89 ///
90 /// Whenever the Receiver receives a RCOIPCmdSetAnalogChannels it might reply with a RCOIPv1ReplyReceiverStatus
91 /// message. However, in order limit bandwidth and battery power requirements, it does not reply to
92 /// every RCOIPv1CmdSetAnalogChannels, but only so that it replies at most every ReplyInterval milliseconds.
93 /// The recommended value for ReplyInterval is 1000 milliseconds.
94 ///
95 /// RCOIPv1CmdSetAnalogChannels can contain 0 or more analog output values.
96 /// The maximum number of analog channels is dictatated by the maximum UDP packet size
97 /// supported by the network, however a minimum of at least 100 channels is expected.
98 /// Only the number of channels configured into the Transmitter are sent.
99 ///
100 /// The interpretation of the channel values is dependent on the configuration of the receiver.
101 /// Each channel value is an 8 bit octet interpreted as an unsigned integer, ranging from 0 to 255 inclusive.
102 /// 0 is to be interpreted by the Receiver as 'minimum' and 255 as 'maximum', but the exact physical effect
103 /// of each channel and the channel values is completely dependent on the configuration of the Receiver.
104 /// Channel values that are expected by the Receiver but which have not (yet) been received
105 /// from the Transmitter are to be interprted as 0. The Receiver is to maintain the output corresponding
106 /// to the last received RCOIPv1CmdSetAnalogChannels message until and unless failure detection results in
107 /// a failsafe configuration (see below).
108 ///
109 /// As can be seen from the above discussion, RCOIP is not a 'reliable' protocol in the sense that it does not
110 /// use acknowledgements in order to guarantee delivery of messages.
111 /// It relies on the 'best efforts' of the network, and the transmission of multiple messages to
112 /// deal with network packet loss and delivery problems. Transmitter and Receiver can use absence of received
113 /// messages for a period of time as a hint of loss of communications. This is discussed further below.
114 ///
115 /// \par Keepalive and failure detection
116 ///
117 /// In order to assist with the detection of communications failure between the Transmitter and he Receiver,
118 /// a system of keepalive messages is defined.
119 ///
120 /// The Transmitter is required to send a message to the receiver at least every KeepaliveInterval milliseconds.
121 /// The reecommended value for KeepaliveInterval is 1000 milliseconds. Any command may be sent
122 /// as the keepalive, but RCOIPv1CmdSetAnalogChannels is recommended
123 /// (note: at present there is only one command message defined, and it is RCOIPv1CmdSetAnalogChannels)
124 ///
125 /// When the Receiver receives a keepalive message it will respond in the usual way,
126 /// by sending a RCOIPv1ReplyReceiverStatus back to the transmitter, provided it is more than
127 /// ReplyInterval milliseconds since the last reply.
128 ///
129 /// If the Receiver does not receive any Command messages for more than FailInterval milliseconds, the Receiver
130 /// detects loss of communication with the Transmitter and may adopt a failsafe configuration.
131 ///
132 /// If the Transmitter does not receive any Reply messages for more than FailInterval milliseconds,
133 /// the Transmitter
134 /// detects loss of communication with the receiver and may react in whatever appropriate way,
135 /// such as informing the User.
136 ///
137 /// If the Receiver detects loss of communication with the Transmitter, it is free to respond in whatever
138 /// way is appropriate. The recommended and safest way is for the Receiver to adopt a 'failsafe' configuration,
139 /// typically by reducing any motor or throttle outputs to 0, off, stopped or safe. If, subsequent to a
140 /// communications failure and a failsafe
141 /// configuration, the Receiver again detects Commands from the Transmitter, it may recommence
142 /// normal operations however, it is recommended that the Receiver remain in the failsafe configuration
143 /// until perhaps manually reset.
144 ///
145 // Copyright (C) 2010 Mike McCauley
146 // $Id: RCOIP.h,v 1.4 2018/09/17 23:09:57 mikem Exp mikem $
147 
148 #ifndef RCOIP_h
149 #define RCOIP_h
150 
151 // RCOIP (Remote Control Over IP) versions we know about
152 
153 /// \def RC_VERSION1
154 /// Indicates Version 1 of RCOIP protocol
155 #define RC_VERSION1 1
156 
157 /// \def RC_VERSION
158 /// This is the default (latest) version of the RCOIP protocol
159 #define RC_VERSION RC_VERSION1
160 
161 /// \def RCOIP_DEFAULT_REPLY_INTERVAL
162 /// Defines the default maximum time in milliseconds between Reply messages
163 /// sent by the receiver
164 #define RCOIP_DEFAULT_REPLY_INTERVAL 1000
165 
166 /// \def RCOIP_DEFAULT_FAIL_INTERVAL
167 /// Defines the default maximum time in milliseconds between that will be regarded as a loss of connection
168 /// by either the receiver or the transmitter
169 #define RCOIP_DEFAULT_FAIL_INTERVAL 2000
170 
171 /// \def RCOIP_DEFAULT_KEEPALIVE_INTERVAL
172 /// Defines the default time in milliseconds between keepalaive Command messages
173 /// sent by the receiver. If no messages are transmitted for more than this period of time
174 /// a keepalive Command message will be sent to the receiver.
175 #define RCOIP_DEFAULT_KEEPALIVE_INTERVAL 1000
176 
177 /// \def RCOIP_DEFAULT_RECEIVER_UDP_PORT
178 /// Defines the default RCOIP receiver UDP port number
179 /// 9048 is controlled by Open System Consultants
180 #define RCOIP_DEFAULT_RECEIVER_UDP_PORT 9048
181 
182 /////////////////////////////////////////////////////////////////////
183 /// \struct RCOIPv1CmdSetAnalogChannels
184 /// \brief SetAnalogChannels command message structure
185 ///
186 /// Defines the structure over-the-wire of
187 /// a Version 1 SetAnalogChannels command
188 typedef struct
189 {
190  /// The RCOIP version number.
191  /// Must be set to RC_VERSION1
192  uint8_t version;
193 
194  /// 0 or more analog channel values, one per octet.
195  /// Channel values range from 0 (minimum) to 255 (maximum) inclusive.
196  /// The physical meaning of channel values and how they map to output devices and pins
197  /// depends on how the channel is interpreted at the Receiver.
198  /// Channels which represent simple on-off channels are expected to be 0 for 'off' and any other
199  /// value for 'on'.
200  uint8_t channels[0];
201 
203 
204 
205 /////////////////////////////////////////////////////////////////////
206 /// \struct RCOIPv1ReplyReceiverStatus
207 /// \brief ReceiverStatus reply message structure
208 ///
209 /// Defines the structure over-the-wire of
210 /// a Version 1 ReceiverStatus reply
211 typedef struct
212 {
213  /// The RCOIP version number.
214  /// Must be set to RC_VERSION1
215  uint8_t version;
216 
217  /// The value of the RSSI (Receiver Signal Strength Indicator) as measured by the receiver
218  /// in the last received message. Arbitrary units. If not available, set to 0.
219  uint8_t RSSI;
220 
221  /// The current value of the Receiver's battery voltage.
222  /// 0 means 0V. 255 means 15.0V
223  uint8_t batteryVoltage;
224 
226 
227 /// \typedef RCOIPCmdSetAnalogChannels
228 /// This is the preferred type to use to refer to the latest version of
229 /// the RCOIPCmdSetAnalogChannels message
231 
232 /// \typedef RCOIPReplyReceiverStatus
233 /// This is the preferred type to use to refer to the latest version of
234 /// the RCOIPReplyReceiverStatus message
236 
237 #endif
RCOIPv1ReplyReceiverStatus::version
uint8_t version
Definition: RCOIP.h:215
RCOIPv1CmdSetAnalogChannels::version
uint8_t version
Definition: RCOIP.h:192
RCOIPv1CmdSetAnalogChannels
SetAnalogChannels command message structure.
Definition: RCOIP.h:188
RCOIPv1ReplyReceiverStatus
ReceiverStatus reply message structure.
Definition: RCOIP.h:211
RCOIPCmdSetAnalogChannels
RCOIPv1CmdSetAnalogChannels RCOIPCmdSetAnalogChannels
Definition: RCOIP.h:230
RCOIPReplyReceiverStatus
RCOIPv1ReplyReceiverStatus RCOIPReplyReceiverStatus
Definition: RCOIP.h:235
RCOIPv1ReplyReceiverStatus::batteryVoltage
uint8_t batteryVoltage
Definition: RCOIP.h:223
RCOIPv1ReplyReceiverStatus::RSSI
uint8_t RSSI
Definition: RCOIP.h:219