Michael Koukoullis

Masters of Doom

Sun, 03 Jun 2018 00:00:00 +0000

I absolutely loved reading Masters of Doom. It canvases the history of some of my favourite video games growing up and I should have read it years ago. The story of the two Johns, John Carmack and John Romero is a page turning, novel-like read that I couldn’t put down.

Masters of Doom book cover art

It begins with the story of two kids growing up during the early days of video games, like PacMan, that were played in corner stores and pizza shops. They met as adults while programming games for Softdisk, a monthly disk magazine produced in Shreveport Louisiana. After Carmack masters the rendering of continuous scrolling graphics on a PC, similar to Mario Bros on Nintendo, they decide to moonlight on their own game: Commander Keen. It’s launch was a raging success that leads to them breaking out and forming id Software where they’ll eventually create breakthrough PC video games such as Wolfenstein 3D, Doom, and Quake.

Doom cover art

At the time they were released, each of these games represented state-of-the-art game play, design, technology, and immersiveness. The two Johns led the field, and this book is an epic tale detailing the high and lows of what was arguably one of the most productive duos in video games history of the 20th century.

How to run Swift on EC2 with Terraform

Mon, 26 Feb 2018 00:00:00 +0000

In this post you’ll learn how to get an AWS EC2 instance provisioned and running Swift. I’ll be using an infrastructure-as-code (IAC) approach and a tool called Terraform. Terraform will allow you to orchestrate EC2 instances with one command in your terminal.

Instead of clicking around a web UI or SSHing to a server and manually executing commands, the idea behind IAC is to write code to define, provision, and manage your infrastructure. Yevgeniy Brikman

This isn’t an in depth explanation of Terraform. I’ll explain enough of the details so you can understand the script. If you want to take a deep dive I recommend reading the series “A Comprehensive Guide to Terraform”.

For the readers that know what I’m talking about and just want to skip to the Terraform scripts please see the GitHub repo. For everyone else who wants to learn how this is done please keep on reading.

Table of Contents

Things you’ll need to get started
Understanding the Terraform Script
Running Terraform

Things you’ll need to get started

AWS Account

If you don’t have one already signup for the free tier which is adequate for what we’ll be doing here.

Install Terraform

The simplest way to install Terraform on your Mac is with Homebrew.

brew install terraform

Clone GitHub Repo

Clone the GitHub repo for this blog post and initialize Terraform.

git clone git@github.com:kouky/swift-aws-ec2.git
cd swift-aws-ec2
terraform init

IAM User with EC2 Permission

You’ll need an AWS user with access keys and the AmazonEC2FullAccess permission. From your AWS web console create a new user in the Identity and Access Management (IAM) service. You can choose any user name, in the screenshot my username is mike.

Create IAM User

Add the user to a group named Terraform which has the AmazonEC2FullAccess permission assigned. The new user will be used to programmatically create, modify, and destroy resources in the EC2 service.

Create IAM Group

When the user is created store the access and secret access keys on your Mac in the file ~/.aws/credentials. Use a profile named terraform, this namespaces the keys for easier referencing in the Terraform script.

[terraform]
aws_access_key_id=ZKWADCXIEZFDOJYXWMU
aws_secret_access_key=xv5Ok0IzniIKkFjwzqROZZhGBrYVi+dzsLV/TNOV

Key Pair for EC2 Instances

From your AWS web console access the EC2 service and choose the region that matches the AWS provider in the Terraform script. We’ll be using us-west-1 which corresponds with US West N. California. Name the key pair swift-server which is what I specified for key_name in the Terraform script.

Create Key Pair

After creating the key pair your browser will download the private key to a file named swift-server.pem.txt. Store it somewhere convenient as you’ll need it to SSH into the EC2 instance.

Understanding the Terraform Script

Terraform scripts are written in a configuration language called HCL that is both human and machine readable. The script we’ll be running is named main.tf in the GitHub repo, I’ll explain the various sections briefly.

/* main.tf */

provider "aws" {
  region = "us-west-1"
  profile = "terraform"
  version = "~> 1.9"
}

resource "aws_instance" "swift-server" {
  ami = "ami-9cb2bdfc"
  instance_type = "t2.micro"
  vpc_security_group_ids = ["${aws_security_group.swift-server.id}"]
  key_name = "swift-server"
  tags {
    Name = "Swift Server"
  }
  user_data = "${file("user-data.sh")}"
}

resource "aws_security_group" "swift-server" {
  name = "swift-server"
  
  ingress {
    from_port = 22
    to_port = 22
    protocol = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }
  
  egress {
    from_port = 0
    to_port = 0
    protocol = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }  
}

output "public_ip" {
  value = "${aws_instance.swift-server.public_ip}"
}

AWS Provider

The first entry in the Terraform script specifies that we want to use the AWS provider. Credentials can be made available to the provider in several ways. I’ve chosen to store keys in the default ~/.aws/credentials file and to namespace them with a profile named terraform.

/* See https://www.terraform.io/docs/providers/aws/ */
provider "aws" {
  region = "us-west-1"
  profile = "terraform"
  version = "~> 1.9"
}

EC2 Instance Resource

The aws_instance resource specifies the properties of the AWS EC2 instance. The key ami specifies the machine image which I chose from an official Ubuntu list.

/* See https://www.terraform.io/docs/providers/aws/r/instance.html */
resource "aws_instance" "swift-server" {
  ami = "ami-9cb2bdfc" /* Ubuntu 16.04 LTS https://cloud-images.ubuntu.com/locator/ec2/ */
  instance_type = "t2.micro" /* See https://aws.amazon.com/ec2/instance-types/ */
  vpc_security_group_ids = ["${aws_security_group.swift-server.id}"]
  key_name = "swift-server"
  tags {
    Name = "Swift Server"
  }
  user_data = "${file("user-data.sh")}"
}

The script user-data.sh will execute when the instance is booting. It updates the server with apt-get and downloads the prebuilt Swift binary for Ubuntu. It can take around a minute for the script to complete so an alternate faster approach would be to let the instance boot once and then create a custom Amazon Machine Image for future use.

Security Group Resource

By default, AWS EC2 instances don’t allow any inbound traffic. The aws_security_group resource can be used to define what traffic is allowed. We allow incoming tcp traffic on the default SSH port 22. The egress rules allow the server to initiate an outgoing connection which is necessary for user data script user-data.sh to update packages and download Swift binaries.

/* See https://www.terraform.io/docs/providers/aws/r/security_group.html */
resource "aws_security_group" "swift-server" {
  name = "swift-server"
  
  ingress {
    from_port = 22
    to_port = 22
    protocol = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }
  
  egress {
    from_port = 0
    to_port = 0
    protocol = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }  
}

The prior aws_instance resource attaches this security group via the key vpc_security_group_ids.

Output Variables

Once the Terraform script has completed running we can display the public IP address of the EC2 instance by using an output variable.

/* See https://www.terraform.io/intro/getting-started/outputs.html */
output "public_ip" {
  value = "${aws_instance.swift-server.public_ip}"
}

Running Terraform

If you haven’t done so already, run terraform init from the root directory of the GitHub repo you cloned earlier.

terraform init

Plan command

The terraform plan command lets you see what Terraform will do before actually making changes to resources on AWS. You should see something like the following:

➜  swift-aws-ec2 git:(master) terraform plan
Refreshing Terraform state in-memory prior to plan...
The refreshed state will be used to calculate this plan, but will not be
persisted to local or remote state storage.

------------------------------------------------------------------------

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  + aws_instance.swift-server
      id:                                    <computed>
      ami:                                   "ami-9cb2bdfc"
      associate_public_ip_address:           <computed>
      availability_zone:                     <computed>
      ebs_block_device.#:                    <computed>
      ephemeral_block_device.#:              <computed>
      instance_state:                        <computed>
      instance_type:                         "t2.micro"
      ipv6_address_count:                    <computed>
      ipv6_addresses.#:                      <computed>
      key_name:                              "swift-server"
...

Apply command

To create the EC2 instance run the terraform apply command. When the script has completed you’ll see the IP address for the new instance.

➜  swift-aws-ec2 git:(master) terraform apply

...
aws_instance.swift-server: Still creating... (10s elapsed)
aws_instance.swift-server: Still creating... (20s elapsed)
aws_instance.swift-server: Still creating... (30s elapsed)
aws_instance.swift-server: Still creating... (40s elapsed)
aws_instance.swift-server: Creation complete after 49s (ID: i-0aa2435878a7749ad)

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Outputs:

public_ip = 54.219.167.28

Use the IP address to SSH into your machine with the .pem file you created earlier.

ssh -i ~/swift-server.pem.txt ubuntu@54.219.167.28

You should now be logged into your instance. The user data script user-data.sh which downloads and installs Swift may still be running. You can see the progress of the script by tailing the cloud log.

ubuntu@ip-54-219-167-28:~$ tail -f /var/log/cloud-init-output.log

swift-4.0.3-RELEASE-ubuntu16.04/usr/include/lldb/API/SBAttachInfo.h
swift-4.0.3-RELEASE-ubuntu16.04/usr/include/lldb/API/SBCommunication.h
swift-4.0.3-RELEASE-ubuntu16.04/usr/include/lldb/API/SBInstructionList.h
swift-4.0.3-RELEASE-ubuntu16.04/usr/include/lldb/API/SBTypeNameSpecifier.h
swift-4.0.3-RELEASE-ubuntu16.04/usr/include/lldb/API/SBValue.h
swift-4.0.3-RELEASE-ubuntu16.04/usr/include/lldb/API/SBWatchpoint.h
swift-4.0.3-RELEASE-ubuntu16.04/usr/include/lldb/API/LLDB.h
swift-4.0.3-RELEASE-ubuntu16.04/usr/include/lldb/API/SBInstruction.h
Cloud-init v. 17.1 running 'modules:final' at Sun, 25 Feb 2018 05:54:37 +0000. Up 12.03 seconds.
Cloud-init v. 17.1 finished at Sun, 25 Feb 2018 05:56:08 +0000. Datasource DataSourceEc2Local.  Up 103.65 seconds

Once the user data script has completed running you’re ready to use Swift! Invoke the REPL at the command line with swift.

ubuntu@ip-54-219-167-28:~$ swift

Welcome to Swift version 4.0.3 (swift-4.0.3-RELEASE). Type :help for assistance.
  1> let x = "Hello World"
x: String = "Hello World"
  2> x
$R0: String = "Hello World"

Destroy command

When you’re done experimenting remember to stop the running instance and destroy all the associated AWS resources by running the terraform destroy command.

➜  swift-aws-ec2 git:(master) terraform destroy
...

aws_instance.swift-server: Destroying... (ID: i-0aa2435878a7749ad)
aws_instance.swift-server: Still destroying... (ID: i-0aa2435878a7749ad, 10s elapsed)
aws_instance.swift-server: Still destroying... (ID: i-0aa2435878a7749ad, 20s elapsed)
aws_instance.swift-server: Still destroying... (ID: i-0aa2435878a7749ad, 30s elapsed)
aws_instance.swift-server: Destruction complete after 36s
aws_security_group.swift-server: Destroying... (ID: sg-91d6b7e8)
aws_security_group.swift-server: Destruction complete after 2s

Destroy complete! Resources: 2 destroyed.

So that’s it, I hope you’ve learnt something new. If you have any questions raise an issue on the GitHub repo or contact me directly.

Swift flips long-standing Objective-C Cocoa error conventions

Sat, 28 May 2016 00:00:00 +0000

Tony Parker provided this nugget of gold on the swift-corelibs-dev mailing list with regards to translating Objective-C APIs and behaviors to Swift.

Unfortunately the throws syntax in Swift often causes a mixup between two different things, because it flipped the terminology from what all of our documentation and header comments use.

1) Cocoa uses exceptions (@throw in ObjC) to indicate programmer errors and they are generally not intended to be recoverable. Example: passing nil where not expected, passing an invalid argument, failing to meet a precondition of an API.

2) Cocoa uses NSError ** to indicate runtime errors that are recoverable or at least presentable to user. Example: out of disk space, name of file already exists.

The ‘throws’ syntax in Swift is actually for case #2, not #1. In Swift, #1 is fatalError or preconditionFailure. #2 is throw Error.

There are reasons why exceptions were not used in Cocoa to handle runtime errors, also NSError predates native exception handling in Objective C.

Swift throws is safer and more conventional. It’s safer given that you have to deal with the error, you can’t accidentally ignore it. It’s more conventional given that’s how other languages communicate potentially recoverable runtime errors. The change in convention may irritate some of us who are Apple developers, but for someone joining the fray from another language or platform it feels more like home.

MAVLink Radio Telemetry for iOS

Sat, 09 Apr 2016 00:00:00 +0000

I’m envious of Android. You can install Tower from the Google Play Store, plug in a USB OTG cable connected to an SiK radio and viola! Long range telemetry for micro UAVs.

Sadly this simplicity doesn’t exist for iOS. Simply stated, iOS doesn’t provide the required operating system level libraries to communicate with serial port interfaces such as those on SiK radios. You could attempt to join Apple’s MFi program but unless you’re a company who intends to develop an accessory you’re out of luck.

This article will demonstrate how to build an inexpensive Bluetooth bridge between an SiK radio and an iOS app. This will be of interest if you’re building telemetry or ground control station software for iOS.

Pixhawk Primary Flight Display on iPad Mini via Radio Telemetry

Hardware

Solving radio telemetry for iOS involves hardware, and at the core of the solution is an ingenious bit of kit from RedBearLab named BLE Mini.

RedBearLab BLE Mini

Other common Bluetooth modules are simple serial port adapters over Bluetooth, however these are useless for iOS. In contrast, BLE mini provides a Bluetooth peripheral service and a set of characteristics which bridge communication with a serial port connected to its pin headers.

Using Apple’s Core Bluetooth framework we can connect to the BLE Mini peripheral, and discover its associated service and characteristics. Through these characteristics we can read and write serial port data and also alter the baud rate.

If you’re unfamiliar with Bluetooth fundamentals I recommend reading the Core Bluetooth Overview section of the Core Bluetooth Programming Guide.

SiK Radio Ground Station

Illustrated in the image below is the ground-based radio station I constructed for this project. The SiK radio will communicate with an air vehicle, and an iPad or iPhone will communicate with the BLE Mini over Bluetooth Low Energy 4.0.

Ground Station SiK Radio with BLE Mini

Power is provided to the the SiK radio and BLE Mini courtesy of a 5V UBEC. The TX / RX pins on the SiK radio are connected to the RX / TX pins on the BLE mini respectively. Connecting all the components together is a custom wiring harness described in the following section.

Wiring Harness for SiK Radio & BLE Mini

At the core of the custom wiring harness for the ground-based radio station is a DF13 six-pin connector cable for the SiK radio.

Custom Wiring Harness

Take care when connecting wires from the DF13 cable to the rest of the wiring harness. Follow the pinout diagram from the ArduPilot SiK Telemetry Radio page (reproduced below ) to make sure power goes to the correct pins. I ignored the RTS and CTS pins and haven’t encountered any issues.

3DR Radio V2 Pinout Description

If you’re not familiar with soldering or electrical wiring work ask a friend or watch instructional videos on YouTube. Always tin wires before soldering them together, and insulate solder joints individually with heat shrink.

Software

An example iPhone and iPad primary flight display app compatible with the aforementioned hardware setup is available from my GitHub. Follow the brief instructions in the README.md to get the app running.

Pixhawk Primary Flight Display on iPhone 6S via Radio Telemetry

Read on if you’d like to learn more about how an iOS app can communicate with an SiK radio via a BLE Mini. For the fine details please refer to the example app source code.

BLE Mini Bluetooth Peripheral

Out of the box the BLE Mini performs the function of a Bluetooth peripheral. There are four universally unique identifiers (UUID) for the BLE mini which are crucial.

let RBL_SERVICE_UUID   = "713D0000-503E-4C75-BA94-3148F18D941E"
let RBL_CHAR_TX_UUID   = "713D0002-503E-4C75-BA94-3148F18D941E"
let RBL_CHAR_RX_UUID   = "713D0003-503E-4C75-BA94-3148F18D941E"
let RBL_CHAR_BAUD_UUID = "713D0004-503E-4C75-BA94-3148F18D941E"

RBL_SERVICE_UUID identifies a simple TX / RX peripheral service on the BLE Mini for exchanging data with the serial port. The first task for an iOS app will be to scan and connect to a Bluetooth peripheral which advertises a service with this UUID.

RBL_CHAR_TX_UUID and RBL_CHAR_RX_UUID identify characteristics of the service which bridge reading and writing for the serial port.

The final RBL_CHAR_BAUD_UUID identifies a characteristic which when written to alters the baud rate of the BLE Mini serial port.

Scanning and Connecting to BLE Mini

When the Core Bluetooth central manager on the iOS device has powered on, you’re free to start scanning for the BLE mini TX / RX service. By restricting the scan to RBL_SERVICE_UUID other Bluetooth peripherals are filtered out.

let services:[CBUUID] = [CBUUID(string: RBL_SERVICE_UUID)]
centralManager.scanForPeripheralsWithServices(services, options: nil)

When a peripheral with the RBL_SERVICE_UUID is detected, the Core Bluetooth central manager delegate method centralManager(_:didDiscoverPeripheral:advertisementData:RSSI:) is called to notify the app. At this point you can connect to the BLE Mini or present a list to the user to select from. In either case you’ll be connecting to the a CBPeripheral at some stage with the following API method.

centralManager.connectPeripheral(peripheral, options: nil)

BLE Mini Service Characteristics

When the peripheral successfully connects, the Core Bluetooth central manager delegate method centralManager(_:didConnectPeripheral:) is called to notify the app. At this point we need to ask the connected CBPeripheral to discover the same service RBL_SERVICE_UUID, which is repetitive but necessary.

func centralManager(central: CBCentralManager, didConnectPeripheral peripheral: CBPeripheral) {
  ...
  peripheral.delegate = self
  peripheral.discoverServices([CBUUID(string: RBL_SERVICE_UUID)])
  ...
}

Once the peripheral discovers the service, the Core Bluetooth peripheral delegate method peripheral(_:didDiscoverServices:) is called to notify the app. At this point we ask the peripheral to discover the TX / RX and baud rate characteristics of the service. These will facilitate communication with the serial port on the pin headers of the BLE Mini.

func peripheral(peripheral: CBPeripheral, didDiscoverServices error: NSError?) {

  ...

  for service in peripheral.services! {
    let theCharacteristics = [
      CBUUID(string: RBL_CHAR_RX_UUID),
      CBUUID(string: RBL_CHAR_TX_UUID),
      CBUUID(string: RBL_CHAR_BAUD_UUID)]
    peripheral.discoverCharacteristics(theCharacteristics, forService: service)
  }
}

Once the peripheral discovers a requested characteristic, the Core Bluetooth peripheral delegate method peripheral(_:didDiscoverCharacteristicsForService:error:) is called to notify the app. The discovered characteristics should be stored for later use. Notifications for the TX characteristic should be enabled so that the app is notified when new data from the serial port has arrived.

func peripheral(peripheral: CBPeripheral, didDiscoverCharacteristicsForService service: CBService, error: NSError?) {
  ...
  for characteristic in service.characteristics! {
    // Store the characteristic
    self.characteristics[characteristic.UUID.UUIDString] = characteristic
  }

  // App is notified as new serial port data arrives
  if let char = self.characteristics[RBL_CHAR_TX_UUID] {
    self.activePeripheral?.setNotifyValue(enable, forCharacteristic: char)
  }
}

Receiving Data

As new data arrives from the serial port, the Core Bluetooth peripheral delegate method peripheral(_:didUpdateValueForCharacteristic:error:) will be called to notify the app.

func peripheral(peripheral: CBPeripheral, didUpdateValueForCharacteristic characteristic: CBCharacteristic, error: NSError?) {

  ...
  if characteristic.UUID.UUIDString == RBL_CHAR_TX_UUID {
    // Decode the data to get a MAVLink message
    let data: NSData? = characteristic.value.value
  }
}

To decode the MAVLink message from NSData refer to my previous article Decoding MAVLink Messages with Swift.

Writing Data

Writing data to the serial port is accomplished by writing NSData to the RBL_CHAR_RX_UUID characteristic.

func write(data data: NSData) {

    guard let char = self.characteristics[RBL_CHAR_RX_UUID] else { return }
    self.activePeripheral?.writeValue(data, forCharacteristic: char, type: .WithoutResponse)
}

Conclusion

I hope this article was helpful and informative. When I first started working with the Pixhawk autopilot I was frustrated that I couldn’t use my iPhone as a development platform. I’m glad to have finally solved that problem.

If you have any questions please do get in touch.

Primary Flight Display Framework for Mac + iOS

Sun, 20 Mar 2016 00:00:00 +0000

PrimaryFlightDisplay is a Mac + iOS framework for use in ground control station and telemetry systems for micro UAVs (unmanned aerial vehicles).

The framework enables convenient embedding and animation of a primary flight display. Styles and colors are easily tuned whilst maintaining crisp graphics for any screen resolution.

A demo Xcode project for MAVLink speaking autopilots is available from my GitHub.

Primary Flight Display for Mavlink - Default Styles

Key features include:

Artificial horizon
Pitch ladder
Bank indicator
Heading tape indicator
Airspeed / Groundspeed tape indicator
Altitude tape indicator
Crisp procedurally generated graphics
Highly configurable colors, sizes, and tape indicator scales
No library dependenices other than Apple’s SpriteKit
Flight stack and protocol agnostic

How to add a Primary Flight Display

Construct a new PrimaryFlightDisplayView with default styles, and add it to your view hierarchy.

let flightView = PrimaryFlightDisplayView(frame: frame)
flightView.autoresizingMask = [.ViewHeightSizable, .ViewWidthSizable]
addSubview(flightView)

Send flight data to the primary flight display using the following API methods. The new flight data values will be animated immediately, and you’re done!

flightView.setAttitude(rollRadians: 1.0, pitchRadians: 1.5)
flightView.setHeadingDegree(300)
flightView.setAirSpeed(20)
flightView.setAltitude(165)

Customizing Styles

The styles for the default primary flight display are easily tuned, see Settings.swift for all the tuneable styles. As an exercise, let’s set the styles to create the primary flight display in the screenshot below.

Primary Flight Display for Mavlink- Custom Styles

Start with the default settings.

var settings = DefaultSettings()

Change the ground color to brown.

settings.horizon.groundColor = SKColor.brownColor()

Change the sky pointer color to pink, increase the bank indicator arc maximum degree to 75 and reduce the arc radius slightly to 160 points.

let pinkColor = SKColor(red:1.00, green:0.11, blue:0.56, alpha:1.0)
settings.bankIndicator.skyPointerFillColor = pinkColor
settings.bankIndicator.arcMaximumDisplayDegree = 75
settings.bankIndicator.arcRadius = 160

Set the attitude reference index to pink and reduce its size slightly so it fits within the smaller bank indicator radius.

settings.attitudeReferenceIndex.fillColor = pinkColor
settings.attitudeReferenceIndex.sideBarWidth = 80
settings.attitudeReferenceIndex.sideBarHeight = 15

Make the heading indicator wider and slimmer, display a minor marker every degree and a major marker every 10 degrees. Increase the points (virtual pixels ) per unit value to 8, which means the numbers on the tape indicator are more spread out.

settings.headingIndicator.size.width = 800
settings.headingIndicator.size.height = 40
settings.headingIndicator.minorMarkerFrequency = 1
settings.headingIndicator.majorMarkerFrequency = 10
settings.headingIndicator.pointsPerUnitValue = 8
settings.headingIndicator.markerTextOffset = 15

Construct a new primary flight display view with the custom settings, and add it to your view hierarchy.

let flightView = PrimaryFlightDisplayView(frame: frame, settings: settings)
flightView.autoresizingMask = [.ViewHeightSizable, .ViewWidthSizable]
addSubview(flightView)

Demonstration App

MavlinkPrimaryFlightDisplay is a Mac app which demonstrates how to integrate the PrimaryFlightDisplay framework for a MAVLink speaking autopilot. Clone the repo and follow the README to get the app running and connect to your autopilot.

The demo app is useful as a learning tool in several other ways as it demonstrates how to:

connect to Pixhawk over USB, Bluetooth, and 3DR radio telemetry
decode MAVLink attitude, heading, airspeed, and altitude messages
send decoded data to the primary flight display for real time updates

Decoding MAVLink Messages with Swift

Mon, 09 Nov 2015 00:00:00 +0000

Last August I purchased a Pixhawk autopilot for micro UAV research purposes.

Pixhawk is an autopilot for fixed wing and multirotor air vehicles. It packs an impressive array of sensors including a gyroscope, magnetometer, and barometer. The entire software stack is open source. It includes a real time operating system, flight middleware, and ground control station.

Pixhawk autopilot

Communication with Pixhawk occurs according to the MAVLink protocol. MAVLink defines a set of messages enabling duplex communication between Pixhawk and a ground station. Pixhawk can inform a ground station of an air vehicle’s status. Likewise a ground station can send messages to query or alter the air vehicle’s behavior.

This article will show how to decode MAVLink messages using a Swift based Xcode project. This is of interest if you’re attempting to write your own ground control station software for the Mac (or iOS).

Sample Project- MavlinkSwiftConnectDemo

A full sample Xcode project for this article is available from my GitHub. Follow the brief instructions in the README to get the app running.

MAVLink C Library

The MAVLink GitHub project defines a set of protocol messages in XML. Python scripts within the project convert those XML files into language-specific libraries. Language options include C, C#, Java, JavaScipt, Python, and Lua. For an Xcode project use the auto generated C library which has it’s own GitHub project.

To get the MAVLink C library working within an Xcode project you’ll need to follow three steps:

Clone the C Library as Git Submodule

Add the C library to an Xcode project as a git submodule. Submodules are the lowest common denominator of dependency management. It makes it easy to pull in the frequent upstream updates to MAVLink. I prefer to use a Vendor sub directory for third-party libraries. Add the submodule with the following command:

git submodule add https://github.com/mavlink/c_library.git Vendor/Mavlink

Create a Clang Module

Bridging headers are one way of making C code available in a Swift project. A Clang module is another method which is better in this case. Create a Modules subdirectory and add a module.map file with the following contents:

module Mavlink [system] {
    header "../Vendor/Mavlink/common/mavlink.h"
    export *
}

Add Module Path to Xcode

The final step is to inform Xcode of the module. Add the module to the the project setting Import Paths located under Swift Compiler. Use ${SRCROOT} in the module path (e.g. ${SRCROOT}/Modules) so that the project works no matter where it’s checked out.

With that all done you can import the MAVLink library at the top of any Swift file with the following statement:

import Mavlink

Reading the MAVLink byte stream

MAVLink message transmission occurs as a stream of bytes. This is ideal for duplex communication over a radio modem.

To decode messages sent by Pixhawk we’ll need to read a stream of bytes from a serial port interface. The painful way involves using Apple’s I/O Kit. The easy way is to use Andrew Madsen’s modern serial port library for Swift OS X apps, ORSSerialPort.

You can communicate with Pixhawk over USB, Bluetooth or radio telemetry. Regardless of which method you choose, ORSSerialPort provides a simple API to communicate with Pixhawk.

There are a multitude of ways to install ORSSerialPort into your Xcode project. The sample project for this article uses the Carthage dependency manager. Instructions for bootstrapping the dependency are in the README file.

Detecting Mavlink Packets

The sample project details how to detect and connect to Pixhawk’s serial interfaces. It’s straightforward when using ORSSerialPort.

Prior to opening a serial port interface to Pixhawk, configure the baud rate, stop bits, and parity with the values listed below. The sample project uses stored property observers to achieve this.

var serialPort: ORSSerialPort? {
    didSet {
        oldValue?.close()
        oldValue?.delegate = nil
        serialPort?.delegate = self
        serialPort?.baudRate = 57600
        serialPort?.numberOfStopBits = 1
        serialPort?.parity = .None
    }
}

Once the serial port is open, a delegate method will notify your application that bytes are available for parsing.

Pass the value of each byte to the MAVLink helper method mavlink_parse_char()

// ORSSerialPort delegate method
func serialPort(serialPort: ORSSerialPort, didReceiveData data: NSData) {
    var bytes = [UInt8](count: data.length, repeatedValue: 0)
    data.getBytes(&bytes, length: data.length)

    for byte in bytes {
        var message = mavlink_message_t()
        var status = mavlink_status_t()
        let channel = UInt8(MAVLINK_COMM_1.rawValue)
        if mavlink_parse_char(channel, byte, &message, &status) != 0 {
          // MAVLink packet detected, decode here
        }
    }
}

If mavlink_parse_char() returns with a truthy value, it means a MAVLink packet has been plucked from the byte stream. The packet is placed in a struct of type mavlink_message_t.

/* Source https://github.com/mavlink/c_library/blob/master/mavlink_types.h */
MAVPACKED(
typedef struct __mavlink_message {
    uint16_t checksum; ///< sent at end of packet
    uint8_t magic;   ///< protocol magic marker
    uint8_t len;     ///< Length of payload
    uint8_t seq;     ///< Sequence of packet
    uint8_t sysid;   ///< ID of message sender system/aircraft
    uint8_t compid;  ///< ID of the message sender component
    uint8_t msgid;   ///< ID of message in payload
    uint64_t payload64[(MAVLINK_MAX_PAYLOAD_LEN+MAVLINK_NUM_CHECKSUM_BYTES+7)/8];
}) mavlink_message_t;

The most important detail here is the packet msgid and payload. For a detailed anatomy of a MAVLink packet refer to the Pixhawk website.

Decoding Mavlink Messages

The discerning attribute of the packet is it’s msgid. Each type of MAVLink message has a unique id. For example, the heartbeat message has value 0 and the attitude message value 30.

Each MAVLink message has an accompanying struct and decode method. To decode the heartbeat message we use a mavlink_heartbeat_t struct and the mavlink_msg_heartbeat_decode() method.

var heartbeat = mavlink_heartbeat_t()
mavlink_msg_heartbeat_decode(&message, &heartbeat);
print(heartbeat.mavlink_version)

Likewise decoding an attitude message requires a mavlink_attitude_t struct and method mavlink_msg_attitude_decode().

var attitude = mavlink_attitude_t()
mavlink_msg_attitude_decode(&message, &attitude)
print("ATTITUDE roll: \(attitude.roll) pitch: \(attitude.pitch) yaw: \(attitude.yaw)")

The sample project uses a switch statement on the message id to decode a variety of MAVLink messages. These are then printed to a text area for viewing.

For a list of common message ids and their meaning refer to the Pixhawk website. The C library headers are the definitive place to discern what a message id means.

Notes when using sample project

The sample project is only tested with an authentic 3DR Pixhawk running PX4 firmware. Communication with 3DR bluetooth and radio telemetry requires a connection to telemetry port 1.

The Charming Genius of the Apollo Guidance Computer

Sat, 07 Nov 2015 00:00:00 +0000

Brian Troutwine’s talk at Code Mesh hit so many high notes. It’s a fascinating insight into the computing challenges faced by the Apollo space program. Extremely well researched, informative, and enterataining. Well worth the 45 minutes.

Sydney Cocoaheads Talk Links

Thu, 19 Feb 2015 00:00:00 +0000

I talked at Sydney Cocoheads today on the topic of Adaptive User Interfaces for iOS. Below are the links from my presentation.

Adaptive User Interfaces apple design resource.
UITraitCollection class reference
Adaptivity and Layout section of iOS Human Interface Guidelines.
UIPopoverPresentationController manages display of content in a popover for iPhone and iPad.
UIContentContainer protocol to help you adapt the contents of your view controllers.
Stackoverflow answer for size class traits for iPad portrait and landscape modes.
Masonry a light-weight layout framework which wraps Auto Layout with a nicer syntax.
Beyond UXKit by Robb Böhnke.
Adaptive layouts for iPhone 6 by Matthew Sander with a focus on using Interface Builder.
iOS adaptive layouts in code by me with a focus on reproducing Matthew’s adaptive Instagram app in code.

iOS Adaptive Layouts in Code

Mon, 16 Feb 2015 00:00:00 +0000

Matthew Sanders posted an excellent article in September 2014 on Adaptive Layouts for iPhone 6. It was written as an instructive piece so I followed along in Xcode 6 recreating the examples using Interface Builder to produce views and auto layout constraints visually.

Image by Matthew Sanders

The last half of the article focused on building an adaptive layout for a hypothetical Instagram interface that shifted information in landscape orientation. I replicated the final results using Interface Builder however I was not impressed by the tediousness of installing, finding, adjusting, and inspecting auto layout constraints visually across multiple size class traits.

The purpose of this article is to illustrate how that adaptive Instagram interface can be recreated in code. I’ll be using Masonry, a light-weight layout framework which wraps Auto Layout with a nicer syntax.

Simple Squares

To illustrate the succinct layout DSL provided by Masonry we can recreate the coloured squares example from the first half of Matthew’s article.

Image by Matthew Sanders

The code snippet below creates the Auto Layout constraints for the coloured squares in the UIView method updateConstraints. The chainable expressive syntax of Masonry shines through. The entire view code is available as working example on my github.

- (void)updateConstraints
{
    UIView *superView = self;
    UIEdgeInsets padding = UIEdgeInsetsMake(20, 20, 0, 20);

    [self.blueSquareView mas_makeConstraints:^(MASConstraintMaker *make) {

        // Make the view a square
        make.height.equalTo(self.blueSquareView.mas_width);

        // Pin the view to the superview
        make.top.and.left.equalTo(superView).with.insets(padding);

        // Make the blue square width equal to the pink square
        make.width.equalTo(self.pinkSquareView);

        // Pin the blue square right edge to the pink square left edge
        make.right.equalTo(self.pinkSquareView.mas_left).with.offset(-20);
    }];

    [self.pinkSquareView mas_makeConstraints:^(MASConstraintMaker *make) {

        make.top.and.right.equalTo(superView).with.insets(padding);
        make.height.equalTo(self.pinkSquareView.mas_width);
    }];

    [super updateConstraints];
}

Adaptive Instagram Example

Recreating the adaptive layout for Matthew’s hypothetical Instagram interface was straightforward. You can follow along in Xcode by cloning the source for this app from my github.

Recreating Matthew's Adaptive Instagram Example

The graphic below denotes the four main subviews of our hypothetical Instagram application. The challenge will be to manage layout constraints in code as the size class traits change during device rotation.

Layout Subviews

When the interface layout changes to landscape our constraints must slide the AuthorView to the right, and move the LikesView rightwards and upwards. The PictureView will remove its full width constraint meanwhile the HeaderView maintains its layout in both orientations. This process must be reversed as the phone rotates back to portrait orientation.

Note: As of iOS8 all rotation-related methods are deprecated. Instead rotations are treated as a change in the size of the view controller’s view. So when we talk about rotations and orientatons we’re really talking about changes in size class traits which are part of the new UITraitCollection class.

Generic Constraints

Our first task is to install the constraints for the generic size class, and by generic we mean constraints which apply for both regular and compact size class traits. For Matthew’s article which uses Interface Builder this corresponds to the any-width any-height setting.

Generic Constraints

As seen in the generic constraints graphic above, the HeaderView has a fixed height and its left, right, and top edges are pinned to the super view. Our PictureView will always be displayed as a square so we define a constraint equating its height and width. The AuthorView will also have a fixed height and its top edge will always be pinned to the bottom edge of the HeaderView.

The following view controller function when called will create and install these generic constraints.

- (void)installGenericConstraints
{
    [self.headerView mas_makeConstraints:^(MASConstraintMaker *make) {
        make.height.equalTo(@60);
        make.left.right.and.top.equalTo(self.view);
    }];

    [self.pictureView mas_makeConstraints:^(MASConstraintMaker *make) {
        make.height.equalTo(self.pictureView.mas_width);
        make.left.equalTo(self.view);
    }];

    [self.authorView mas_makeConstraints:^(MASConstraintMaker *make) {
        addObject:make.height.equalTo(@50);
        make.top.equalTo(self.headerView.mas_bottom);
    }];
}

Portrait Constraints

The next step is to install the constraints relevant only for the portrait orientation. Determining which constraints are required is a process of filling-in-the-blanks from the generic constraints illustration.

Portrait Constraints

The portrait specific constraints include pinning the AuthorView left and right edges to the super view, which makes it span the full width. Pin the top and right edge of the PictureView to the bottom of the AuthorView and the right edge of the superview respectively. The LikesView does not have any generic constraints so defining them is straightforward: pin its top edge to the bottom of the PictureView and pin its left and right edges to the superview which makes it span the full width.

The following view controller function creates the portrait layout constraints. The Masonry constraint maker MASConstraintMaker conveniently returns the constraint created which we add to an array property. We’ll use this array later to uninstall the constraints as the device changes orientation.

- (void)installPhonePortraitConstraints
{
    NSMutableArray *constraints = [[NSMutableArray alloc] init];

    [self.authorView mas_makeConstraints:^(MASConstraintMaker *make) {
        [constraints addObject:make.left.and.right.equalTo(self.view)];
    }];

    [self.pictureView mas_makeConstraints:^(MASConstraintMaker *make) {
        [constraints addObject:make.top.equalTo(self.authorView.mas_bottom)];
        [constraints addObject:make.right.equalTo(self.view)];
    }];

    [self.likesView mas_makeConstraints:^(MASConstraintMaker *make) {
        [constraints addObject:make.top.equalTo(self.pictureView.mas_bottom).with.offset(5)];
        [constraints addObject:make.left.and.right.equalTo(self.view)];
    }];

    self.phonePortraitConstraints = [constraints copy];
}

Landscape Constraints

The next step is to install the constraints relevant only to landscape orientation. Again determining which constraints are required is a process of filling-in-the-blanks from the generic constraints illustration.

Landscape Constraints

The landscape specific constraints include pinning the PictureView top and bottom edges to the HeaderView bottom edge and super view bottom edge respectively. The left edge of the AuthorView is pinned to the right edge of the PictureView. The LikesView top and left edges are pinned to the AuthorView top edge and PictureView left edge respectively.

Attempting to pin the right edge of the AuthorView and LikesView to the super view will lead to unsatisfiable constraints. The less-than-or-equal-to width constraint allows the views to expand to the intrinsic width of their subviews.

The following view controller function creates the landscape layout constraints. Once again we store the constraints in a view controller array property which we’ll use later to uninstall the constraints.

- (void)installPhoneLandscapeConstraints
{
    NSMutableArray *constraints = [[NSMutableArray alloc] init];

    [self.authorView mas_makeConstraints:^(MASConstraintMaker *make) {
        [constraints addObject:make.left.equalTo(self.pictureView.mas_right)];
        [constraints addObject:make.width.lessThanOrEqualTo(self.pictureView)];
    }];

    [self.pictureView mas_makeConstraints:^(MASConstraintMaker *make) {
        [constraints addObject:make.top.equalTo(self.headerView.mas_bottom)];
        [constraints addObject:make.bottom.equalTo(self.view)];
    }];

    [self.likesView mas_makeConstraints:^(MASConstraintMaker *make) {
        [constraints addObject:make.top.equalTo(self.authorView.mas_bottom)];
        [constraints addObject:make.left.equalTo(self.pictureView.mas_right)];
        [constraints addObject:make.width.lessThanOrEqualTo(self.pictureView)];
    }];

    self.phoneLandscapeConstraints = [constraints copy];
}

Toggling Constraints

The functions we just discussed are concerned with creating constraints. As mentioned earlier the challenge will be to manage layout constraints as the size class traits change during device rotation.

The following function when called will install the constraints matching the device orientation for a trait collection and uninstall the constraints which are no longer relevant. The uninstall prefixed helper methods are simply uninstalling the constraints which we stored a reference to earlier.

- (void)toggleConstraintsForTraitCollection:(UITraitCollection *)traitCollection
{
    if ([traitCollection mk_matchesPhoneLandscape]) {

        [self uninstallPhonePortraitConstraints];
        [self installPhoneLandscapeConstraints];

    }
    else if ([traitCollection mk_matchesPhonePortrait]) {

        [self uninstallPhoneLandscapeConstraints];
        [self installPhonePortraitConstraints];
    }

    [self updateViewConstraints];
}

- (void)uninstallPhonePortraitConstraints
{
    for (MASConstraint *constraint in self.phonePortraitConstraints) {
        [constraint uninstall];
    }
}

- (void)uninstallPhoneLandscapeConstraints
{
    for (MASConstraint *constraint in self.phoneLandscapeConstraints) {
        [constraint uninstall];
    }
}

Note: Helper methods mk_matchesPhoneLandscape and mk_matchesPhonePortrait are from a category on UITraitCollection, see source on my github.

Note: This approach results in the constraints getting installed, uninstalled, and reinstalled as the device rotates back and forth. An alternative approach could be the activate and deactive api methods for MASConstraint however it just didn’t work for me. Your results may vary.

Wiring the View Controller

Connecting all this up to our view controller is straightforward, all the heavy lifting is covered by the previous helper methods.

Override the UIViewController template method updateViewConstraints and install the generic constraints which will always be active. Then call helper method toggleConstraintsForTraitCollection: which will install constraints for the current size class traits.

#pragma mark UIViewController template methods

- (void)updateViewConstraints
{
    if (!self.didSetConstraints) {

        self.didSetConstraints = YES;
        [self installGenericConstraints];
        [self toggleConstraintsForTraitCollection:self.traitCollection];
    }

    [super updateViewConstraints];
}

Note: There’s a potential problem with updateViewConstraints as it can be called more than once when the view initialises and when the size class traits change during rotation. We guard against double installation of constraints with a flag which from my research seems to be current best practice.

The final step is to implement protocol method viewWillTransitionToSize:withTransitionCoordinator: which communicates changes in size class traits for the view controller. Its body calls helper method toggleConstraintsForTraitCollection: which will install and uninstall constraints as required.

#pragma mark UIContentContainer protocol methods

- (void)willTransitionToTraitCollection:(UITraitCollection *)newCollection withTransitionCoordinator:(id<UIViewControllerTransitionCoordinator>)coordinator
{
    [self toggleConstraintsForTraitCollection:newCollection];
}

Final Remarks

Working with Auto Layout and adapting your interfaces to different screen sizes for iOS is more important that ever. Using Interface Builder and Storyboards will get you a long way, and I’m not suggesting that you banish them from your workflow. However for all but the most simple of applications you will need to get into the trenches and write layout constraints in code. I hope this article will help you in that task.

You can download the source for this app from my github for reference.

If you have any questions or comments please do get in touch.

Updates

Soon after drafting this post I watched a keynote on React Native which I highly recommend. The promise React Native holds is a declarative approach to defining our views and their layouts. This means the code is written in such a way that it describes what you want to do, and not how you want to do it.

Andy Matuschak a former UIKIt author put it simply in his tweet.

I say with confidence as a former UIKit author: React's model for the UI layer is vastly better than UIKit's. React Native is a *huge* deal.
— Andy Matuschak (@andy_matuschak) January 28, 2015

Josh Abernathy also wrote a short and sharp post on why reactive native matters.

Double Dispatch Sprite Kit Physics Contacts

Fri, 24 Jan 2014 00:00:00 +0000

I picked the the classic video game Pong to provide a working example of the recommendation in the Sprite Kit programming guide to use Double Dispatch to farm out work associated with node physics body contacts in the simulation.

You can download the source from my GitHub repo.

Scene and Node Setup

Our game consists of a PlayfieldScene with a PhysicsBody edge loop, a BallNode, and two PlayerNodes each comprised of a PaddleNode and ScoreNode. The BallNode and PaddleNodes are configured with physics bodies to allow for contact detection.

To replicate the classic gameplay velocities of the BallNode are manually altered on contact with other bodies, rather than relying on the physics collision capabilities of Sprite Kit. The ball’s vertical velocity is simply reflected when it hits the top or bottom edge of the PlayFieldScene.

When the ball contacts the PaddleNode the horizontal velocity is reflected within an interpolated 90 degree arc based on the contact point. The magnitude of the reflected BallNode velocity is proportional to the speed of the PaddleNode on contact.

Handling Physics Body Contacts Naively

The PlayfieldScene is assigned as the contact delegate for the physics world and implements the contact delegate method didBeginContact.

The main observation to make is that the bodies in a contact can appear in any order. For example the first two clauses in the conditional below are essectially checking for the same thing, that the ball is contacting the PlayfieldScene edges.

- (void)didBeginContact:(SKPhysicsContact *)contact
{
    SKPhysicsBody *firstBody, *secondBody;
    firstBody = contact.bodyA;
    secondBody = contact.bodyB;

    if ((firstBody.categoryBitMask & ballCategory) != 0 &&
        (secondBody.categoryBitMask & playfieldCategory) != 0) {

        BallNode *ball = (BallNode *)[firstBody node];
        // Perform something

    } else if ((secondBody.categoryBitMask & ballCategory) != 0 &&
               (firstBody.categoryBitMask & playfieldCategory) != 0) {

        BallNode *ball = (BallNode *)[secondBody node];
        // Perform the same something

    } else if ((firstBody.categoryBitMask & ballCategory) != 0 &&
               (secondBody.categoryBitMask & paddleCategory) != 0) {

        BallNode *ball = (BallNode *)[firstBody node];
        // Perform something else

    } else if ((secondBody.categoryBitMask & ballCategory) != 0 &&
               (firstBody.categoryBitMask & paddleCategory) != 0) {

        BallNode *ball = (BallNode *)[secondBody node];
        // Perform the same something else
    }
}

The problem with the approach above is two fold.

Firstly embedding all the logic in the scene’s contact delegate method will result in a long unreadable method as the number of nodes in the simulation increases. Farming this work out to contact handlers would be much better.

Secondly the code required to handle the outcome of each contact, needs to be written in or referenced twice. This could be addressed by by combining the double up with an OR operation, not that great for legibility.

if (((firstBody.categoryBitMask & ballCategory) != 0 &&
     (secondBody.categoryBitMask & playfieldCategory) != 0) ||

    ((secondBody.categoryBitMask & ballCategory) != 0 &&
     (firstBody.categoryBitMask & playfieldCategory) != 0)) {

    BallNode *ball = (BallNode *)[firstBody node];
    // Perform something
}

Another approach to counter the double up is the bitwise sorting approach in the programming guide’s rocket contact example code example, reproduced below.

if (contact.bodyA.categoryBitMask < contact.bodyB.categoryBitMask)
{
    firstBody = contact.bodyA;
    secondBody = contact.bodyB;
}
else
{
    firstBody = contact.bodyB;
    secondBody = contact.bodyA;
}
if ((firstBody.categoryBitMask & missileCategory) != 0)
{
    [self attack: secondBody.node withMissile:firstBody.node];
}

This approach will still require further nested conditionals to determine the outcome based on both bodies in the contact, which for all but the most trivial of simulations will most likely be the case.

Physics Body Contacts with Double Dispatch

Using the Visitor pattern we can double dispatch the outcome of the contact based on both bodies. The contact delegate no longer discerns the categroies of the physics body, its implementation shrinks to just the following.

- (void)didBeginContact:(SKPhysicsContact *)contact
{

    SKPhysicsBody *firstBody, *secondBody;
    // Inspect these closely, they're actually private class instances of PKPhysicsBody
    firstBody = contact.bodyA;
    secondBody = contact.bodyB;

    VisitablePhysicsBody *firstVisitableBody = [[VisitablePhysicsBody alloc] initWithBody:firstBody];
    VisitablePhysicsBody *secondVisitableBody = [[VisitablePhysicsBody alloc] initWithBody:secondBody];

    [firstVisitableBody acceptVisitor:[ContactVisitor contactVisitorWithBody:secondBody forContact:contact]];
    [secondVisitableBody acceptVisitor:[ContactVisitor contactVisitorWithBody:firstBody forContact:contact]];

}

The VisitablePhysicsBody class is a simple wrapper for an SKPhysicsBody instance. It implements a method called accept, which accepts the visitor, and which in turn invokes the actual visit. A wrapper is used as acceptVisitor cannot be implemented as a category on SKPhysicsBody given the physics bodies carried by the SKPhysicsContact instance are actually instances of private class PKPhysicsBody.

@implementation VisitablePhysicsBody

- (id)initWithBody:(SKPhysicsBody *)body
{
    self = [super init];
    if (self) {
        _body = body;
    }
    return self;
}

- (void)acceptVisitor:(ContactVisitor *)contact
{
    [contact visit:self.body];
}

@end

Out ContactVisitor base class implements convenience constructor contactVisitorWithBody:forContact which constructs one of its subclasses based on the physics body category of it’s first argument. This is the first part of the double dispatch, we have an instance of a class which is named after one of the bodies in the contact e.g. BallNodeContactVisitor PaddleNodeContactVisitor etc.

@implementation ContactVisitor

+ (id)contactVisitorWithBody:(SKPhysicsBody *)body forContact:(SKPhysicsContact *)contact
{
    if ((body.categoryBitMask & ballCategory) !=0) {
        return [[BallNodeContactVisitor alloc] initWithBody:body forContact:contact];
    } else if ((body.categoryBitMask & playfieldCategory) != 0) {
        return [[PlayfieldSceneContactVisitor alloc] initWithBody:body forContact:contact];
    } else if ((body.categoryBitMask & paddleCategory) != 0) {
        return [[PaddleNodeContactVisitor alloc] initWithBody:body forContact:contact];
    } else {
        return nil;
    }
}

- (id)initWithBody:(SKPhysicsBody *)body forContact:(SKPhysicsContact *)contact
{
    self = [super init];
    if (self) {
        _contact = contact;
        _body = body;
    }
    return self;
}

...

The visit method in our ContactVisitor implements the second part of the double dispatch by sending a message named after the second physics body in the contact to the newly constructed ContactVisitor subclass instance which is named after the first body in the contact e.g. visitBallNode visitPaddleNode etc.

...

- (void)visit:(SKPhysicsBody *)body
{
    // This will generate strings like "BallNode", "PaddleNode", or "PlayfieldScene"
    NSString *bodyClassName = [NSString stringWithUTF8String:class_getName(body.node.class)];

    // This will generate strings like "visitBallNode:", "visitPaddleNode:", or "visitPlayfieldScene"
    NSMutableString *contactSelectorString = [NSMutableString stringWithFormat:@"visit"];
    [contactSelectorString appendString:bodyClassName];
    [contactSelectorString appendString:@":"];

    SEL selector = NSSelectorFromString(contactSelectorString);

    if ([self respondsToSelector:selector]) {
        [self performSelector:selector withObject:body];
    }

}

@end

We now have a class BallNodeContactVisitor which is solely concenred with handling contacts for nodes of class BallNode. The methods within the class follow a naming convention determined by the visit method and allows us to determine the outcome of the contact with other node types.

@implementation BallNodeContactVisitor

// Handles contacts with PlayfieldScene edges
- (void)visitPlayfieldScene:(SKPhysicsBody *)playfieldBody
{

    BallNode *ball = (BallNode *) self.body.node;
    PlayfieldScene *playfield = (PlayfieldScene *) playfieldBody.node;
    // Perform something
}

// Handles contacts with PaddleNodes
- (void)visitPaddleNode:(SKPhysicsBody *)paddleBody
{
    BallNode *ball = (BallNode *) self.body.node;
    PaddleNode *paddle= (PaddleNode *) paddleBody.node;
    // Perform something else
}

@end

On the flip side we have another class named PaddleNodeContactVisitor which handles contacts for nodes of class PaddleNode.

@implementation PaddleNodeContactVisitor

// Handles contacts with BallNodes
- (void)visitBallNode:(SKPhysicsBody *)ballBody
{
    BallNode *ball = (BallNode *) ballBody.node;
    PaddleNode *paddle = (PaddleNode *) self.body.node;
    // Perform something
}

@end

You can handle the same contact in two seperate places, but you only really want to do it in one place. In the examples above the same contact between the BallNode and the PaddleNode will be dispatched to both the instances of BallNodeContactVisitor and PaddleNodeVisitor if they implement the respective methods visitPaddleNode and visitBallNode. These methods don’t have to be implemneted as the ContactVisitor base class visit method checks if they respond to the selectors firstly. In practice you’d only implement either visitPaddleNode or visitBallNode.

References

Sprite Kit Programming Guide and in particular the Simulating Physics chapter.

Visitor Pattern and Double Dispatch in Ruby by Neeraj Singh.

iOS Sprite Kit Pong source code.