Wednesday, January 20, 2016

Bluetooth (BLE) Robot Remote Control using an iPhone - Part 2

Introduction


If you want to use an iPhone as your controller then Bluetooth is one of the better communication options for directing your robot / drone / whatever.

In Part 2 we will cover the iPhone app required to control your BLE device. The AVA BLE Remote is available as a free download from iTunes. We will first cover how the app works and then how it was coded. For those who don't want to write their own controller, feel free to use ours. We have included the ability to customise the characters sent in response to a command.

We suggest you read Part 1 to understand the overall design but here is a quick recap.

This app has been designed to work with a Bluno board from DFRobot. The Bluno is a combination of an Arduino and a Bluetooth shield. It uses Bluetooth Low Energy (BLE), which is compatible with iOS 7.0+ devices: iPhone 5+,iPad 3+,iPad Mini,and iPod 5th Gen (note that Bluetooth LE capability is required).




Getting Started: The Connection Screen


When the app starts, it will open the connection tab and display any compatible BLE devices which are within range. To connect to a device just tap on its name. If the connection is successful, the word connected will be displayed and the communication indicator "LEDs" will turn from flashing blue to green. You can start a manual search for BLE devices by tapping the search (magnifying glass) icon in the top right of the connection screen. You can stop the search by tapping the disconnect device button (a cross) in the top left.

If you are already connected to a BLE device, tapping the disconnect device button will disconnect you. You can only attach to one BLE device at a time.



Setting a Task


Tasks are a behavioural robotics concept, but of course you can use them as you wish. You don't need to use tasks at all, if you want you can just use the next tab (Control) to direct your robot. Tasks are useful if you want the robot to do more than one thing. In our case, the robot only responds to remote control commands when the remote task has been set.

The idea is that each task is made up of subset of core behaviours. By combining different behaviours you can create a robot task. For example, the default tasks provided with the app are mapped to the following core behaviours in AVA.

Task ID        Name        Behaviours

     0               Status        BID_STOP
     1               Remote     BID_MANUAL
     2               Patrol        BID_AVOID, BID_ESCAPE, BID_POWER
     3               Follow IR BID_PIR_ATTRACT, BID_AVOID, BID_ESCAPE, BID_POWER
     4               Avoid IR   BID_PIR_REPEL, BID_AVOID, BID_ESCAPE, BID_POWER

By combining simple core behaviours you can get emergent complex task following behaviours which degrade gracefully when the robot faces unexpected situations. In our robot, each of the behaviours are set a priority. This priority decides which behaviour takes precedence. If the priorities are the same then the code will deal with them in the order presented (which gives an implied priority). You can refresh your knowledge on behavioural robotics by reading our earlier post on different approaches to robot AI.

Behaviour                        Priority                      Inputs                               Outputs 

BID_STOP                            1                            cliff, collision sensors       left & right motor stop
BID_MANUAL                    2                            BLE remote                       left & right motor controls
BID_ESCAPE                       3                            distance sensors, heading  left & right motor controls
BID_AVOID                         4                            distance sensors                 left & right motor controls
BID_POWER                        5                            batt voltage, homing          left & right motor controls
BID_PIR_ATTRACT           6                            PIR                                     left & right motor controls
BID_PIR_REPEL                 6                            PIR                                     left & right motor controls

The Task tab in the iPhone app allows you to send a tasking message to your Bluno. It is the responsibility of the robot code to assign current behaviours based on the assigned task.

Tapping a task will transmit the tasking ID (e.g. 1) via Bluetooth. Tap the add button (+) to add your own tasks. Tap Edit to delete or rearrange the tasks. Tapping "Default Tasks" will reload the task list that comes with the app.




Controlling your BLE Device


The Control tab acts as a virtual gamepad for your BLE device. The currently selected task is displayed at the top of the screen. Tapping the function keys (F1 to F4) will send the designated character via Bluetooth to your Bluno. Similarly, tapping the directional dPad or stop button will send the character assigned to those buttons. You can change the characters which are transmitted from the key mapping option in the console tab. The default mappings are:

F1    w
F2    x
F3    y
F4    z

Up Arrow         f
Down Arrow    b
Left Arrow       l
Right Arrow     r
Stop                  s

The speed slider will send the selected speed encapsulated with less than and greater than brackets.

Messages received back from the Bluno are displayed at the bottom of the screen.




The Console


The console tab allows you to send any character strings that you wish to the Bluno. Just type the message in the text field and tap Send. Any received messages will be displayed below.

The console tab also contains the system log which records various events, such as device discovery, connection, data transmission and disconnection. You can email the system log by tapping the mail button in the top right of the screen.

Tap the settings (gear icon) button if you wish to change the keys mapped to the Control buttons.




iOS Code


The iOS code is pretty straight forward and made much easier by the Bluno frameworks provided by DFRobot. You will need to include the following classes in your code.

- BLEDevice
- BLEUtility
- DFBlunoDevice
- DFBlunoManager

The download link for the entire Xcode project is provided below, but here are the highlights. Most of the heavy lifting is done by the DFBlunoManager class. This is a shared instance (singleton), so you just access it in your classes using:

 blunoManager = [DFBlunoManager sharedInstance];

The first step is scanning for and connecting with available Bluetooth LE (BLE) devices. Scanning is as simple as:

[blunoManager scan];

The results of the scan are handled by the DFBlunoDelegate, so you will need to have one of your classes conform to this protocol. We used the TabBarViewController as this is nice and central. Within our TabBarViewController, there are a couple of delegate methods which get notified when a scan is performed.

#pragma mark- DFBlunoDelegate

- (void)bleDidUpdateState: (BOOL)bleSupported
{
    NSString *logString;
    NSString *timeStamp = [formatter stringFromDate: [NSDate date]];
    
    if (bleSupported) {
        logString = [NSString stringWithFormat: @"%@: Scanning for BLE devices\n", timeStamp];
        [blunoManager scan];
    } else {
        logString = [NSString stringWithFormat: @"%@: BLE not supported\n", timeStamp];
    }
    
    [self log: logString];
}

- (void)didDiscoverDevice: (DFBlunoDevice *)device
{
    NSString *timeStamp = [formatter stringFromDate: [NSDate date]];
    NSString *logString = [NSString stringWithFormat: @"%@: New device discovered - %@\n", timeStamp, device.identifier];
    
    [self log: logString];
    
    BOOL bRepeat = NO;
    
    for (DFBlunoDevice *bleDevice in appDelegate.deviceArray) {
        if ([bleDevice isEqual: device]) {
            bRepeat = YES;
            break;
        }
    }
    
    if (!bRepeat) {
        [appDelegate.deviceArray addObject: device];
        
        NSString *logString = [NSString stringWithFormat: @"%@: Device added to BLE list\n", timeStamp];
        
        [self log: logString];
    }
    
    [connectionViewController.tbDevices reloadData];
}

We use these to update the table tbDevices in the ConnectionViewController. Once you have found an eligible device, you connect to it using:

[blunoManager connectToDevice: device];

In particular, since we use a table view to list the devices in range we allow the user to connect to a specific device by tapping on the row in the table that corresponds to that device. The device data is stored in deviceArray (which is a property of the application delegate). We also have a property in the application delegate which points to the currently active device (blunoDevice). The relevant code from the ConnectionViewController is:

#pragma mark- Table View Delegate

- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath
{
    DFBlunoDevice *device = [appDelegate.deviceArray objectAtIndex:indexPath.row];
    
    if (appDelegate.blunoDevice == nil) {
        appDelegate.blunoDevice = device;
        [blunoManager connectToDevice: appDelegate.blunoDevice];
    } else if ([device isEqual: appDelegate.blunoDevice]) {
        if (!appDelegate.blunoDevice.bReadyToWrite) {
            [blunoManager connectToDevice: appDelegate.blunoDevice];
        }
    } else {
        if (appDelegate.blunoDevice.bReadyToWrite) {
            [blunoManager disconnectToDevice: appDelegate.blunoDevice];
            appDelegate.blunoDevice = nil;
        }
        
        [blunoManager connectToDevice: device];
    }
    
    [self.activityIndicator stopAnimating];
    self.activityIndicator.hidden = YES;
    [tableView deselectRowAtIndexPath: indexPath animated: YES];
}

Once you are connected to the remote device, sending data to it is performed by the following method (found in the application delegate).

#pragma mark - Bluno Communications

- (void)sendString: (NSString *)msg {
    if (self.blunoDevice.bReadyToWrite) {
        NSData *data = [msg dataUsingEncoding: NSUTF8StringEncoding];
        
        [blunoManager writeDataToDevice: data Device: self.blunoDevice];
    }
}

The DFBlunoDelegate will let you know what happens via two methods.

- (void)didWriteData: (DFBlunoDevice*)device
{
    //  NSLog(@"%s", __func__);
    
    NSString *timeStamp = [formatter stringFromDate: [NSDate date]];
    NSString *logString = [NSString stringWithFormat: @"%@: Data written\n", timeStamp];
    
    appDelegate.state = Transmitting;
    [self log: logString];
}

- (void)didReceiveData: (NSData *)data Device: (DFBlunoDevice *)device
{
    //  NSLog(@"%s", __func__);
    
    NSString *timeStamp = [formatter stringFromDate: [NSDate date]];
    NSString *receivedTextString = [[NSString alloc] initWithData: data encoding: NSUTF8StringEncoding];
    
    //  NSLog(@"ASCII Rx: %d",[receivedTextString characterAtIndex: 0]);
    
    if (receivedTextString && receivedTextString.length > 0 && ![receivedTextString isEqualToString: @"\n"]) {
        NSString *logString = [NSString stringWithFormat: @"%@: Rx - %@\n", timeStamp, receivedTextString];
        manualViewController.txtReceivedMsg.text = receivedTextString;
        consoleViewController.txtReceivedMsg.text = receivedTextString;
        [self log: logString];
    }
    
    appDelegate.state = Receiving;
    consoleViewController.txtSendMsg.text = @"";
}


In our app we use these to update the log file in the console and print out any data received from the remote device.

Finally, to disconnect a device, just use:

[blunoManager disconnectToDevice: appDelegate.blunoDevice];

You will need to replace appDelegate.blunoDevice with whatever you have called your Bluno Device object.

The complete source code is available at the Reefwing Code Repository.

Bluno Code


The Bluno code was covered in Part 1 of this series. Sample code to allow you to test the app is available from the Reefwing Gist Repository (https://gist.github.com/reefwing/eab05c12b615070732c3).

Wednesday, January 6, 2016

Bluetooth (BLE) Robot Remote Control using an iPhone - Part 1

Overview


Any self respecting autonomous robot needs a remote control / telemetry mode. This is useful for testing and most importantly fun! There are lots of different ways that you could approach this (e.g. hard wired, WiFi, or RF) but we liked the idea of using our iPhone as the controller and this seemed like a good excuse to play around with Bluetooth.

Figure 1. The Bluno - Arduino Uno + BLE.

As this is a fairly meaty subject, we will break it up into three posts. Each post will cover the following:

  1. Bluno - An Arduino board combined with a Bluetooth 4 Low Energy module produced by DFRobot (see Figure 1). In our design this acts as the middle-ware, providing a bridge between our iPhone app and the Arduino Mega 2560 which acts as our main robot controller. You could control a simple robot directly from the Bluno. We also used the Bluno accessory shield, mostly to provide an indication of what is happening via its OLED display. However, this doesn't leave a lot of spare pins (3 digital and 2 analog to be precise).
  2. iOS App - I will provide the source code for this and make it available for download from iTunes once I have finished debugging. It should be flexible enough to use in your own robot design. I have included the ability to remap the keys should you wish to use different characters to the ones I selected.
  3. Mega 2560 Integration - This is the final step in allowing your robot to be controlled via an iPhone app. The Bluno communicates with the Mega 2560 using the serial 3 comms port. We could have used the I2C bus, but as this is used for logging it could be tied up when a critical stop command was trying to be sent from the remote. As a remote command is one of the highest priority behaviours, it made sense for it to have its own dedicated communication channel.

The Design


The wiring is simple. As shown in Figure 2, the Bluno connects to our Mega 2560 using 2 wires. Pins 4 and 5 of the Bluno connects to pins 14 and 15 on the Mega 2560 (the Serial 3 Tx and Rx pins). That's it, the magic happens in the software. We have described in an earlier post how the Mega 2560 controls our HB-25 Motor Controllers. Bluno uses a TI CC2540 BT 4.0 chip to provide BLE functionality. We will use this to communicate with the iPhone.

Figure 2. AVA Schematic.


The Hardware


We are using the SoftwareSerial library on the Bluno so you can use any 2 spare digital pins, but if you also use the accessory shield (Figure 3) then you wont have many other options. The accessory shield provides quite a bit of capability.


128x64 OLED Screen                                    Display messages from your phone interface.
Buzzer                                                            Enable Sound notifications or simple music.
DHT11 Temperature & Humidity Sensor     For environmental monitoring.
1.5A Relay                                                     Device switch or integrating with other electronics.
Helical Potentiometer                                    Transfer real time data to your phone
RGB LED                                                      Display full colour RGB
Mini Joystick                                                 Tells your phone which direction is pressed


The pins used by BLE module and the accessory shield are:

0    BLE Rx (also used for programming and for the terminal comms).
1    BLE Tx (also used for programming and for the terminal comms).
2    DHT11 Temp / Humidity sensor.
3    RGB LED (blue control).
4    Spare - used for serial Rx, connects to Mega 2560 Tx.
5    Spare - used for serial Tx, connects to Mega 2560 Rx.
6    OLED RESET
7    OLED DC
8    Buzzer
9    RGB LED (red control)
10  RGB LED (green control)
11  Relay
12  Spare
13  LED

A0    Joystick
A1    Knob (potentiometer)
A2    Spare
A3    Spare
A4    I2C - SDA
A5    I2C - SCL

Figure 3. The DFRobot Accessory Shield.

Looking at Figure 3 you will note our first design problem. None of the pins are accessible without breaking out the soldering iron. To allow us to connect our 2 serial wires we purchased a prototyping screw terminal shield from DFRobot (Figure 4).

Figure 4. Prototyping Screw Terminal Shield.

The proto shield is sandwiched between the Bluno and the accessory shield (Figure 5). Excellent we now have access to pins 4 and 5, BUT now the OLED display no longer works. Design problem number 2. For some unfathomable reason (particularly since all these products come from the same supplier) the proto shield is 2 pins short. The missing pins are the I2C SDA and SCL (used to control the OLED). There are a number of ways you can fix this, but the easiest is to get an Arduino Header Kit (like the one shown in Figure 5) and use the 6 pin header to bridge between the Bluno and the accessory shield. There are holes in the proto shield to allow this (albeit not exactly in the right spot). Cut off the 4 unused pins to prevent them shorting on anything. You can solder the header kit onto the proto board if you want but we didn't find this necessary.

Figure 5. Arduino Header Kit.

The images below (Figure 6) show the boards connected together and mounted on AVA. The yellow and brown wires are the serial comms to the Mega 2560 and the red and green are power and go to the distribution board on the bottom deck. The board adjacent to the Bluno is used for monitoring of the 2 x 12V SLA batteries. The panel voltmeter displays the current battery voltage (11.5 VDC).



Figure 6. Bluno, Proto and Accessory Shield.

The Software


You can download the Bluno software from the Reefwing Gist Repository. The code is pretty straight forward. The Bluno waits until it receives data on its serial port from the BLE module and passes it to the Mega via another serial port. The RGB LED flashes blue once a second while waiting for data. It will flash green once when data is received. The iOS app allows you to select a number of tasks for the robot to perform. In Figure 6, you can see that the current task is task 2: Patrol. When task 1, Remote Control is selected, the RGB LED goes a solid red.

The main code loop is shown below. As we will see in the next post, the iPhone app sends a character code to indicate the command required (e.g. 's' means stop).

if (Serial.available())  {
        char data = Serial.read();
        commsDetected = true;
        switch (data) {
            case 's':
                Serial.write("Ack - STOP");
                megaSerial.write(data);
                break;
            case 'f':
                Serial.write("Ack - Forward");
                megaSerial.write(data);
                break;
            case 'b':
                Serial.write("Ack - Back");
                megaSerial.write(data);
                break;
            case 'l':
                Serial.write("Ack - Left");
                megaSerial.write(data);
                break;
            case 'r':
                Serial.write("Ack - Right");
                megaSerial.write(data);
                break;
            case 'w':
                Serial.write("Ack - F1");
                megaSerial.write(data);
                break;
            case 'x':
                Serial.write("Ack - F2");
                megaSerial.write(data);
                break;
            case 'y':
                Serial.write("Ack - F3");
                megaSerial.write(data);
                break;
            case 'z':
                Serial.write("Ack - F4");
                megaSerial.write(data);
                break;
            case '0':
                task = statusReport;
                taskDescription = "T0: Status";
                Serial.print(taskDescription);
                megaSerial.write(data);
                remoteControlled = false;
                break;
            case '1':
                task = remoteControl;
                taskDescription = "T1: Remote";
                Serial.print(taskDescription);
                megaSerial.write(data);
                remoteControlled = true;
                break;
            case '2':
                task = patrol;
                taskDescription = "T2: Patrol";
                Serial.print(taskDescription);
                megaSerial.write(data);
                remoteControlled = false;
                break;
            case '3':
                task = followIR;
                taskDescription = "T3: Follow IR";
                Serial.print(taskDescription);
                megaSerial.write(data);
                remoteControlled = false;
                break;
            case '4':
                task = avoidIR;
                taskDescription = "T4: Avoid IR";
                Serial.print(taskDescription);
                megaSerial.write(data);
                remoteControlled = false;
                break;
            default:
                char errorMsg[32];
                String error = "Unknown Command - ";
                error += data;
                error.toCharArray(errorMsg, 32);
                Serial.write(errorMsg);
                break;
        }
        Serial.println();
    }