RCKit
RCKit library for Arduino

This is the Arduino RCKit library.

RCKit provides a kit of software objects that make it easy to build an RCOIP (Remote Control Over IP) receiver on Arduino. 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.

As such it can be used to build Remote Controlled (RC) vehicles and devices of various kinds, along with matching transmitters. Large numbers of channels can be supported, along with a back-channel which sends data from the Receiver to the Transmitter. A compatible iPhone transmitter app is also available.

The transmitter could be a handheld Wi-Fi enabled device such as an iPhone, iPad or Arduino based device. Or it could be an interactive program running on a desktop computer. The RCTx iPhone transmitter app is available on the Apple App Store. It provides a simple RCOIP transmitter equipped with 2 joysticks and a number of switches.

The receiver (using this RCKit software) could be a remote controlled car, plane, helicopter or some other device.

The RCOIP protocol is a 2-way protocol that defines UDP messages between the RCOIP transmitter and receiver. This effectively makes the transmitter a UDP client and the receiver a UDP server. Messages sent from the transmitter to the receiver include setting analog outputs, and messages from the receiver to the transmitter include receiver status messages.

RCTx, RCKit and the RCOIP protocol offer the following advantages over conventional Remote Control:

Videos explaining how it works and what you can do with it can be found at:

There is also a video showing how RCKit can be used with the IRrc library at http://www.airspayce.com/mikem/arduino/IRrc to control a 3 channel infra-red model helicopter at:

The version of the package that this documentation refers to can be downloaded from http://www.airspayce.com/mikem/arduino/RCKit/RCKit-2.5.zip You can find the latest version at http://www.airspayce.com/mikem/arduino/RCKit

You can also find online help and disussion at http://groups.google.com/group/rckit Please use that group for all questions and discussions on this topic. Do not contact the author directly, unless it is to discuss commercial licensing.

Tested on Arduino Duemilanove, Diecimila, Mega and Asynclabs Yellowjacket with arduino-1.0 and arduino 1.0.1 on OpenSuSE 12/ and avr-libc-1.6.2-5.11, cross-avr-binutils-2.19-9.1 and cross-avr-gcc43-4.3.3_20081022-9.3

RCRx

RCRx class is an RCOIP receiver. It works with Arduino and a range of communications hardware like WiShield and Ethernet to receiver commands from an RCOIP compliant Transmitter (such as the RCTx iPhone app available on the Apple App Store).

When the RCRx object is constructed, it must be given an array of Setter objects. When a RCOIPv1CmdSetAnalogChannels message is received by RCRx, The Setter corresponding to each Channel value in the RCOIPv1CmdSetAnalogChannels command will be passed to the respective Setter in the analogOutputs array. The Arduino software is expected to be configured so that each analogOutput is connected to a Setter that will implement the received value, perhaps by setting an analog or digital output on an Arduino pin. Setter objects are provided to achieve this. See below.

RCRx will automatically respond to received commands with RCOIPv1ReplyReceiverStatus messages as appropriate to the configured timeouts etc. See the RCOIP protocol document for more details.

Setters

Setter classes are objects that receive a value, maybe transform it and then do something with it. Typically they set an output pin according to the received input value, but almost any other transformation, output or communication can be imagined.

The following output Setter objects are provided with RCKit. They can be used to translate receiver channel values into physical outputs:

The following transformation Setter objects are provided with RCKit. They can be used to transform receiver channel values before being given to one of the output Setter classes above:

Example Sketches

Several example Arduino sketches are included, including a regression test suite and a sample complete 5 channel receiver with Servo outputs for WiFi and Ethernet.

Transceivers

Version 2.0 of this library added the concept of a Transceiver, in order to be able to support multiple type of communications transport. A Transceiver is an object responsible for communicating with an RCOIP transmitter. Several types of Transceiver are supported by the standard RCRx library:

RCTx iPhone App

RCTx is an RCOIP compliant transmitter for iPhone available on the Apple App Store at https://itunes.apple.com/us/app/rctx/id567423127?mt=8

You can use it with the WiShieldTransceiver object to use WiFi to communicate directly to a WiShield equipped RCRx receiver. Or you can use it with the EthernetTransceiver object and your LAN and Wirelesss Access Point to communicate to an Ethernet equipped RCRx receiver.

RCTx presents a simulated RC transmitter with 2 joysticks and a number of switches. The left josystick sets channels 0 and 1 and the right joystick channels 2 and 3. The switches set channels 4 through 9 inclusive. The one connected to channel 4 is momentary contact.

To install and configure RCTx to work with a WiShield equipped RCRx:

To install and configure RCTx to work with an Ethernet equipped RCRx:

Prerequisites

These prerequisites must be installed in the libraries directory of your Arduino devlopment environment, even if you are not going to use them with RCRx, otherwise the RCRx will not build.

Installation

Install in the usual way: unzip the distribution zip file to the libraries sub-folder of your Arduino IDE sketchbook.

WiShield Library Configuration

Requires the Asynclabs WiShield library to be installed, even if you are not using the WiShieldTransceiver. See http://asynclabs.com/wiki/index.php?title=WiShield_library Install the WiShield library in the libraries directory of your arduino IDE installation, then follow the configuration steps below:

Support of RSSI (receiver signal strength indicator) requires mods to WiShield library g2100.c as per http://asynclabs.com/forums/viewtopic.php?f=10&t=385&start=0. You dont have to add this but its a good feature. It is included in the prebuilt WiShield library mentioned below.

Correct operation of the WiShield requires you to set the jumper on the WiShield to INT0 or DIG8 to select the arduino pin to use for WiShield interrupts, and also to make sure it agrees with the settings of USE_DIG0_INTR or USE_DIG8_INTR in spi.h in the WiShield library (which defaults to using Arduino digital pin 2, and which means setting the WiShield jumper to INT0 setting). Yes, the naming conventions are inconsistent :-(. In summary:

WiShield jumper spi.h Arduino
INT0 USE_DIG0_INTR Digital pin 2
D8 USE_DIG8_INTR Digital pin 8

For YellowJacket and WiFi Bee (which has no jumper), leave it as USE_DIG0_INTR.

Caution: on WiFi Bee, Arduino Digital pin 4 is connected to the WiFi Chip HIBERNATE pin. Do not use pin D4 as an RCKit output pin.

In order for WiShield library to support UDP (as needed by this module), you MUST set UIP_CONF_UDP to 1 in uip-conf.h. This is an unfortunate but necessary requirement, otherwise UDP support will not be compiled into the WiShield library. Further, you must edit apps-conf.h and make sure the only APP_* defined is APP_UDPAPP. Failure to do this will cause compile errors.

A modified version of the WiShield library already modified and configured for use with RCKit (including RSSI support) is available at http://www.airspayce.com/mikem/arduino/WiShield-v1.3.0-0-mikem-RCKit.zip

WiShield will work with Arduino Mega, but with difficulty. The problem is that with the Mega, the SPI pins that are required for interface with WiShield come out on different pins to the smaller form factor arduinos like Diecimila and Duemilanove. So, to make the Mega work with the WiShield, you have to reroute the SPI pin to different Arduino pins, as per http://asynclabs.com/forums/viewtopic.php?f=13&t=19&hilit=mega&start=10

By default, WiShieldTransceiver is configured as an Ad-Hoc Wi-Fi network with SSID of 'RCArduino' By default, the network is Open (ie no encryption) and It is configured with a static IP address of 169.254.1.100. These setting can be changed by editing WiShieldTransceiver.cpp in the RCKit distribution.

Author:
Mike McCauley (mikem.nosp@m.@air.nosp@m.spayc.nosp@m.e.co.nosp@m.m) Do not contact the author directly unless it is to discuss commercial licensing. See above for support and discussion groups.

This software and the RCOIP protocol is Copyright (C) 2010-20112 Mike McCauley. Use is subject to license conditions. The main licensing options available are GPL V2 or Commercial:

This library has been tested with Duemilanove and (WiShield 1.0 or YellowJacket or WiFi Bee 1) and iPhone 3.0

Open Source Licensing GPL V2

This is the appropriate option if you want to share the source code of your application with everyone you distribute it to, and you also want to give them the right to share who uses it. If you wish to use this software under Open Source Licensing, you must contribute all your source code to the open source community in accordance with the GPL Version 2 when your application is distributed. See http://www.gnu.org/copyleft/gpl.html

Commercial Licensing

This is the appropriate option if you are creating proprietary applications and you are not prepared to distribute and share the source code of your application. Contact info@.nosp@m.airs.nosp@m.payce.nosp@m..com for details.

Revision History
Version:
1.0 Initial release
1.1 Added Linear
1.2 Compiles under Arduino 1.0
1.3 Fix error in test suite tat prevvented correct tests with latest versions of AccelStepper Added documentation for examples. Added new class MotorControllerSetter, which can be used to control motor controllers with a direction and (PWM) speed pin.
2.0 Caution: API Change: existing RCRx sketches will not work with this new version without (minor) modifications. Separate the WiShield WiFi driver code out into a separate Transceiver object. Rationalise some includes and headers Add support for WiShield and Ethernet transceivers, with examples to suit
2.1 Some files were missing from the 2.0 release. Clarified the fact that only Arduino 1.0 and later is now suported (due to incompatible changes in Ethernet UDP support)
2.2 Compiler problems were reported unless SPI.h was include first in sketches (although I could not reproduce this). Changed examples to suit.
2.3 Found and documented a problem when you use Arduino digital pin D4 as an output with WiFi-Bee, which uses that pin as HIBERNATE. Dont use D4 as output with WiFi-Bee
2.4 Fixed incorrect link to RCTx on App Store.
2.5 Updated author and distribution location details to airspayce.com