Watch App Development Blog – Week 6

 I’m blogging my progress in developing an Apple Watch App. Read the previous instalments here.

Telstra – grrr!

I had a frustrating week trying to track down an odd issue – I wouldn’t get any train times load when I was walking around (i.e. near the station, where I want to test), but there was nothing showing up in the logs. The app would work perfectly at home when plugged into Xcode. This put a bit of a dampener on the planned Pebble app field testing. Eventually I managed to log an error message (NSURLErrorDomain -1003 – hostname not found). It turns out the tutum.io subdomain assigned to my docker endpoint isn’t resolving on any of Telstra’s DNS servers. I’m running Google DNS at home, which resolves the hostname fine, and so doesn’t exhibit the issue, but on 4G I’m at the mercy of the Telstra DNS. After an hour on the phone with Telstra, this has been ‘escalated to Level 3 support’ and I’ll get a response ‘within 7 days’. I’ve switched back to an IP address so I can continue my testing.

What did we learn here?

While I’m obviously shocked that Telstra’s internet services could be anything less than spectacular, the key takeaway is that leaving logging out of your code DOESN’T SAVE TIME. Swift makes it trivially easy to return a typesafe, idiot-proof error result that forces you to think critically about how you’re managed error conditions in your code. Consider this snippet (the culprit):

func get<T: JSONConvertible>(path: String, f: [T] ->()) {
    Alamofire.request(.GET, hostname + path)
        .responseJSON { (_, _, json, _) in
        if let json = json as? [NSDictionary] {
            f(json.map({ T(dictionary: $0) }))
        } else {
            f([])
        }
    }
}

func getAllStations(f: [Station] -> ()) {
    get("/train", f)
}
  1. I’m ignoring the error object that Alamofire is helpfully returning (the last parameter in responseJSON)
  2. I’m returning an empty array if literally anything goes wrong. Networking error, HTTP error (like a 500 from the server), malformed JSON payload, the lot = empty array.

In this case the empty station array was overwriting the locally cached stations, and my ‘nearestStation’ method was never producing a result. Because it’s just refreshing a local cache of fairly static data, I can safely ignore errors if I already have data. This could be done by testing the array count in the callback, but we should be able to do better.

Let’s change our ApiClient get method to the following:

enum Result<T> {
    case Value(Box<T>)
    case Error(NSError)
}

func get<T: JSONConvertible>(path: String, f: Result<[T]> ->()) {
    Alamofire.request(.GET, hostname + path)
        .responseJSON { (_, _, json, error) in
        if let json = json as? [NSDictionary] {
            f(Result.Value(Box(json.map({ T(dictionary: $0) }))))
        } else if let error = error {
            f(Result.Error(error))
        } else {
            f(Result.Error(NSError(domain: ApiClientErrorDomain,
                code: 1,
                userInfo: [NSLocalizedDescriptionKey: "An unknown error occurred."])))
        }
    }
}

We’re defining a Result type that returns either the requested value, or an NSError. Ignore the Box, this is only a figment of your imagination, and is totally not a hack to work around the Swift compiler’s problems with ‘non-fixed multi-payload enum layouts’. Note I’m also creating an ‘unknown error’ to handle the case where I don’t get back an error object from Alamofire. Just in case.

I use the updated API as follows:

        getAllStations { r in
            switch r {
            case let .Value(s):
                setStations(s.unbox)
            case let .Error(e):
                println("Error refreshing stations from the server: \(e.localizedDescription)")
            }
        }

So we have glorious logging in case of error and a rather annoying ‘unbox’ call. Importantly though, due to the signature of the API, it’s now much harder to lazily ignore error handling.

Watch App Development Blog – Week 4 *cough* 5

 I’m blogging my progress in developing an Apple Watch App. Read the previous instalments here.

So, um, I missed a week. Sorry about that. Sad face.

Step 4: The Pebble

We don’t have access to any Apple Watch hardware yet, so it’s difficult to get a good feel for how you will use your app in context. I was given a Pebble for Christmas though, and thought it may be worthwhile getting the core information displayed on a Pebble app so I can experience and analyse the usage flow behind a watch app with this data.

Pebble: the Palm Pilot of Smartwatches

First, my impressions of the pebble:

  • Battery life is not too bad, I get about a week of normal usage. It doesn’t compare favourably to several years of battery life on a traditional watch (like my trusty Tag 2000), but it should soundly spank most newer-generation smart watches, including the Apple Watch, based on the rumours to date.
  • The screen is awful if you’re used to a high-resolution smartphone display. The B&W 144 x 168 display looks like 90s tech.
  • The Watch itself is plasticky (lasted a whole day before it copped a small but visible scratch on the face), and too large and ungainly for most wrists.
  • The app/watchface marketplace is fairly limited & most of the apps have a ‘hobbyist’ feel to them. I don’t necessarily mean that in a negative manner – it’s great to see the enthusiasm, but without a good mechanism to monetise apps there’s not the same level of investment & innovation that I see in the iOS App Store or the Play Store.
  • The hardware is fairly slow and anaemic.
  • Development for the pebble is difficult. The Pebble C API is very low level, requires a lot of careful memory management, can only run on the device, and can’t be debugged. They’ve released a JavaScript API to try to make the experience a bit better, though I haven’t tried it.
  • If you’re using your pebble with an iPhone, the experience is less than seamless due to Apple’s bluetooth accessory restrictions. Some functionality  (e.g. network access) stops working if the Pebble iOS app has been terminated from the background. Third party iOS apps have a single Pebble connection to share, and communication can only be initiated from the phone.

To me, the product is very reminiscent of the early Palm Pilots – clunky B&W screen, an awkward developer experience, small hobbyist developer community etc. The future’s yet to be written, but the Pebble will need to undergo radical and ruthless improvement to keep pace with the latest smartwatches.

The Pebble App

The general concept behind the watch app is a simple display showing the departure times for the closest station. This should provide the ‘in context’ component of the most important watch app functionality. The initial UI design (pictured) includes the nearest station, and the destination, pattern, and minutes remaining for the next four departures from the station.

Pebble Mockup

The simplest way to manage communication between the phone app & the watch app is the AppSync API. The general semantics of the API involve syncing a dictionary of shared data between the phone & watch; it also makes data storage on the watch more convenient. The downside is that this requires a specific key for each individual data element synced to the watch – i.e. specific numbered departures rather than a variable array of scheduled trains.

With that in mind, the keys were defined thus:

#define KEY_STATION 0
#define KEY_DEST_1 1
#define KEY_TIME_1 2
#define KEY_DEST_2 3
#define KEY_TIME_2 4
#define KEY_DEST_3 5
#define KEY_TIME_3 6
#define KEY_DEST_4 7
#define KEY_TIME_4 8

The main issue I ran into with AppSync was a storage limitation. The sample code includes a 30 byte sync buffer which is insufficient for most data sync requirements, but it wasn’t immediately obvious that’s what the error DICT_NOT_ENOUGH_STORAGE was referring to. Upping the buffer to 128 bytes solved the issue. That should be enough for anybody.

Once the data was synced, I update the UI using the following function:

static void drawText() {
  const Tuple *tuple;
  if ((tuple = app_sync_get(&s_sync, KEY_STATION))) {
    if (tuple->value->cstring[0] == 0) {
      text_layer_set_text(station_text_layer, "Waiting for data");
    } else {
      text_layer_set_text(station_text_layer, tuple->value->cstring);
    }
  }
  for (int i = 0; i < 4; i++) {
    if ((tuple = app_sync_get(&s_sync, i * 2 + 1))) {
      if (tuple->value->cstring[0] == 0) {
        text_layer_set_text(dest_text_layers[i], "");
      } else {
        text_layer_set_text(dest_text_layers[i], tuple->value->cstring);
      }
    }
    if ((tuple = app_sync_get(&s_sync, i * 2 + 2))) {
      if (!tuple->value->int32) {
        text_layer_set_text(time_text_layers[i], "");
      } else {
        time_t departure_time = tuple->value->int32;
        time_t current_time = time(NULL);
        int minutes = (departure_time - current_time)/60;
        char time_str[5];
        snprintf(time_str, 5, "%dm", minutes);
        text_layer_set_text(time_text_layers[i], time_str);
      }
    }
  }
}

…where dest_text_layers and time_text_layers are four element arrays containing references to the text layers on the watch UI.

Can you spot the bug? If you haven’t done much work with embedded systems it’s not obvious. Critically, the documentation for text_layer_set_text says:

The string is not copied, so its buffer most likely cannot be stack allocated, but is recommended to be a buffer that is long-lived, at least as long as the TextLayer is part of a visible Layer hierarchy.

time_str is not copied when passed to text_layer_set_text; the effect being that it goes out of scope and is never displayed on the watch face. The solution is a set of string buffers referenced statically – I used a static char pointer array, and malloced/freed the buffers in window_load/window_unload.

// at the top of the file
#define TIME_LABEL_LENGTH 5
static char *time_strings[4];

// in the window_load() function
  for (int i = 0; i < 4; i++) {
    time_strings[i] = malloc(sizeof(char[TIME_LABEL_LENGTH]));
  }

// drawtext() changes to:
  snprintf(time_strings[i], TIME_LABEL_LENGTH, "%dm", minutes);
  text_layer_set_text(time_text_layers[i], time_strings[i]);

The iOS App

Pebble integration doesn’t require a a substantial amount of code – drag in the frameworks and pull a PBWatch reference from PBPebbleCentral.defaultCentral().lastConnectedWatch(). Because I want to be able to show the number of minutes until a train leaves, I changed the earlier code from a HH:MM string to a ZonedDate/NSDate in the Haskell & Swift code. I then implemented Pebble communication using the following (dest/pattern is abbreviated to economise on transfer bandwidth & Pebble display size):

    func updatePebble(station: Station, _ times : [Departure]) {
        var pebbleUpdate : [NSNumber: AnyObject] = [
            KeyStation : station.name,
        ]
        for i: Int in 0..<4 {
            let destKey = NSNumber(int: Int32(i * 2 + 1))
            let timeKey = NSNumber(int: Int32(i * 2 + 2))
            pebbleUpdate[destKey] = times[i].shortDescription
            pebbleUpdate[timeKey] = NSNumber(int32: Int32(times[i].time.timeIntervalSince1970))
        }
        self.watch?.appMessagesPushUpdate(pebbleUpdate, withUUID: appUUID, onSent: { (w, Dict, e) in
            if let error = e {
                println("Error sending update to pebble: \(error.localizedDescription)")
            } else {
                println("Sent update to pebble!")
            }
        })
    }

There was a problem though: the Pebble showed around -470 minutes for each train (i.e. 8 hours out – suspicious, as local time is +8:00). Turns out Pebble has no concept of timezone at all. The docs spin this as: “Note that the epoch is adjusted for Timezones and Daylight Savings.” Not sure that qualifies as epoch time, but it was clear the conversion is meant to happen on the phone. The following code sorted the issue:

  let adjustedEpoch = Int(times[i].time.timeIntervalSince1970) + NSTimeZone.localTimeZone().secondsFromGMT
  pebbleUpdate[timeKey] = NSNumber(int32: Int32(adjustedEpoch))

Glorious 1 bit UI

The result (I have a promising future as a watch model). I’ll give it a good workout near the train station over the next week.

Pebble Running

As always, the code is available here, here and here.

A last note: The fact that I’m on week 5 of my watch app development journey and am yet to touch WatchKit is not lost on me. I should hopefully start hitting WatchKit code this week. With a bit of luck.

 

The operation couldn’t be completed. (SSErrorDomain error 100.)

If you’re trying to test iOS App Store receipt validation, and you perform a receipt refresh using SKReceiptRefreshRequest, you are almost certainly going to come across the mysterious and enigmatic SSErrorDomain Error 100. There’s not a lot of information on the googles, so here’s what I know/suspect.

As far as I can tell, code 100 is the App Store’s way of telling you “Sorry, I have no receipt for that bundle ID for that user”. That’s unlikely to happen in production unless shenanigans are underway (a receipt is generated even for a free app ‘Get’), but it can happen often in development. The sandbox App Store appears to have the ability to generate fake receipts when requested, but all ducks need to be in a row for this to happen.

In the sandbox (Development/Ad Hoc builds):

  • If you don’t have an app record set up in iTunes Connect, you’ll get a Code 100
  • If you’re signed in with your regular Apple ID instead of a sandbox account: Code 100
  • If you’re signed in with a sandbox account associated with a different iTunes Connect account: Code 100

The story is a bit different for Apple Testflight builds – these are production builds with special handling for in-app purchases, and the App Store (currently) does NOT generate a fake original purchase receipt. I haven’t tested this myself, but from a developer report on the dev forums (login required):

  • If you have a virgin install from TestFlight, you’ll get a Code 100
  • If you’ve previously installed the App Store version of the app, you’ll get a receipt
  • If you have a virgin install from TestFlight but have made an in-app purchase, you’ll get a receipt

Hopefully this saves others some frustration.

Watch App Development Blog – Week 3

In weeks 1 & 2, I got a Transperth-scraping REST API built and deployed to an AWS-based cloud host. This week I’ll get started on:

Step 3: The iPhone App

Third party apps on Apple Watch are very limited and rely heavily on the companion iPhone app for logic, network access, location etc, so the first place to start with the Watch app is on the iPhone.

The phone app itself will need useful functionality otherwise it’s unlikely to be approved. I have a few ideas for cool features for the phone, but for the moment it can just display the live times for the nearest station. This will require:

  1. Getting the list of stations from the server
  2. Finding the nearest station based on the user’s current location
  3. Getting the live times for that station from the server.

Let’s get started. I’m going to be building the app in Swift (of course). Mattt Thompson of NSHipster/AFNetworking fame has written a Swift-only networking framework called Alamofire, so we’ll start with it.

After setting up the framework following the instructions, I created a new Swift file called ‘ApiClient’. Downloading JSON from the server using Alamofire looks like the following:

func getAllStations(f: [Station] -> ()) {
    Alamofire.request(.GET, "\(hostname)/train")
        .responseJSON { (_, _, json, _) in
           if let json = json as? [NSDictionary] {
                let s = json.map({ Station(dictionary: $0) })
                f(s)
            } else { f([]) }
    }
}

struct Station {
    let id : String
    let name : String
    let location: CLLocation

    init(dictionary: NSDictionary) {
        self.id = dictionary["id"] as String
        self.name = dictionary["name"] as String
        let lat = Double(dictionary["lat"] as NSNumber)
        let long = Double(dictionary["long"] as NSNumber)
        self.location = CLLocation(latitude: lat, longitude: long)
    }
}

I’m using a global function (to be more functional) with a callback parameter that takes an array of stations. The returned JSON array is mapped over to convert the NSDictionary instances into Station values. If anything goes wrong, an empty array is passed to the callback – this isn’t brilliant error handling and will probably change, but it’s clearer to show as-is for now.

The user’s location can then be retrieved from a CLLocationManager, and the nearest location calculated like so:

    func nearestStation(loc: CLLocation) -> Station? {
        return stations.filter({ $0.distanceFrom(loc) <= 1500 }).sorted({ $0.distanceFrom(loc) &< $1.distanceFrom(loc) }).first
    }

    // where distanceFrom is defined on Station as
    func distanceFrom(otherLocation: CLLocation) -> CLLocationDistance {
        return location.distanceFromLocation(otherLocation)
    }

This will filter out all stations greater than 1.5km away, and return the nearest of the remainder (or nil if there are no nearby stations).

From there, we can retrieve the live times from the server using the code:

func getLiveTrainTimes(station: String, f: [Departure] -> ()) {
    Alamofire.request(.GET, "\(hostname)/train/\(station)")
        .responseJSON { (_, _, json, _) in
            if let json = json as? [NSDictionary] {
                let s = json.map({ Departure(dictionary: $0) })
                f(s)
            } else { f([]) }
    }
}

Wait – this looks pretty much identical to getAllStations, just with a different URL and return type. Let’s refactor:

protocol JSONConvertible {
    init(dictionary: NSDictionary)
}

func get<T: JSONConvertible>(path: String, f: [T] ->()) {
    Alamofire.request(.GET, hostname + path)
        .responseJSON { (_, _, json, _) in
        if let json = json as? [NSDictionary] {
            f(json.map({ T(dictionary: $0) }))
        } else { f([]) }
    }
}

// we can then redefine the other request methods as:
func getAllStations(f: [Station] -> ()) {
    get("/train", f)
}

func getLiveTrainTimes(station: String, f: [Departure] -> ()) {
    get("/train/\(station)", f)
}

The UI for the app (which I won’t go through here) is just a regular UITableView with a row for each train at the nearest station. However, it’s worth considering how the app will operate at different phases of its lifecycle – I want the live times to be updated in the background (for reasons that will become apparent later).

While the app is in the foreground, the location updates will come through as normal – I have a 50m distance filter on as this is unlikely to change your nearest station. When entering the background, the app will switch to the ‘significant change’ location service – again, accuracy is not super important so the course-grained significant change should work fine.

For the live train times network requests, in the foreground these will be triggered by a 30s NSTimer, in the background using the background fetch API. I haven’t used background fetch before, but it seems like the right technology to use in the case – allow the OS to decide if the app should refresh its data, based on battery life, network connectivity, and usage patterns of the app.

The various services are switched on & off like so:

    func applicationDidBecomeActive(application: UIApplication) {
        locationManager.startUpdatingLocation()
        timer = NSTimer.scheduledTimerWithTimeInterval(NSTimeInterval(30), target: self, selector: "timerFired:", userInfo: nil, repeats: true)
        timer?.fire()
    }

    func applicationWillResignActive(application: UIApplication) {
        locationManager.stopUpdatingLocation()
        timer?.invalidate()
        timer = nil
    }

    func applicationDidEnterBackground(application: UIApplication) {
        locationManager.startMonitoringSignificantLocationChanges()
    }

    func applicationWillEnterForeground(application: UIApplication) {
        locationManager.stopMonitoringSignificantLocationChanges()
    }

This is enough to start road-testing the app functionality out on the phone, and maybe start formulating a few ideas around the best functionality to prioritise on the watch. Speaking of the watch, next week I’ll have a surprise along those lines. As before, the code is available on bitbucket.

Watch App Development Blog – Week 2

In Week 1, I got a (very) basic Haskell REST web service running that scraped the Transperth site for live train times. Now we’re up to:

Step 2: Build & Deployment

Like most developers working on side-projects, I don’t want to pay a bundle for hosting a service during development when it really doesn’t need many resources, however when the product goes live and inevitably becomes a raging success, I need to be able to scale capacity quickly & easily. In the past I’ve used freemium PaaS providers like Heroku and AppHarbor which are designed for exactly this scenario.

I started down the Heroku path using Joe Nelson’s buildpack, however I immediately hit Heroku’s 15 minute build timeout. There are a variety of ways around this, although I got to thinking (as I’ve pondered in the past about AppHarbor) why I need to build on my hosting provider. Heroku was originally designed for deploying apps written in Ruby that didn’t need compilation; pushing source & compiling on the server seems like a hack to me.

Docker is the new hotness in packaging and application deployment, and is better suited to building a compiled web application locally and deploying to a cloud host. I thought I’d give this a go.

Docker Development on OS X

The Docker host relies on specific features of the Linux kernel, which means that working with containers locally on OS X or Windows requires running them inside a Docker host in a Linux VM. This starts to get a bit onioney. My initial inclination was to do docker development using Vagrant – the same method I use for working on other web systems targeting a Linux host. After spending considerable time trying out different methods of running Docker through Vagrant, I ended up coming to the conclusion that it wasn’t worth the hassle for a simple deployment like this one. Instead, my model would be:

  1. While I’m developing locally, just run the service directly on OS X without using Docker.
  2. When I’m ready to deploy, spin up boot2docker and build the container
  3. Commit & push the image to a remote docker repo.
  4. Deploy the image to the cloud host from the repo.

I strongly recommend getting started with Docker using Chris Jones’ “Missing Guide”. I installed using the downloadable installer rather than homebrew, but the only real config change I needed to make was to give the boot2docker VM more RAM – GHC struggles a bit unless it has plenty. Run the command boot2docker config > ~/.boot2docker/profile, then edit the ~/.boot2docker/profile file and change the ‘Memory’ setting (I gave it 4096). I didn’t configure any port-forwarding as I’m only using docker to build the image.

Building a Haskell Docker image

Dockerhub has an official Haskell image, which is a good starting point for development. I implemented a Dockerfile starting from the example at the end of the README. I needed to add an extra step to cater for my gps-1.2 requirement which is (still) not available on Hackage yet at time of writing.

FROM haskell:7.8

RUN cabal update

# Add .cabal file
ADD ./perthtransport.cabal /opt/app/perthtransport.cabal

# Install gps-1.2 from source
ADD gps /opt/app/gps
RUN cd /opt/app/gps && cabal install

# Docker will cache this command as a layer, freeing us up to
# modify source code without re-installing dependencies
RUN cd /opt/app && cabal install --only-dependencies -j4

# Add and Install Application Code
ADD . /opt/app
RUN cd /opt/app && cabal install

# Add installed cabal executables to PATH
ENV PATH /root/.cabal/bin:$PATH

EXPOSE 3000

# Default Command for Container
WORKDIR /opt/app
CMD ["perthtransport"]

I also needed to create a .dockerignore to ensure the cabal sandbox was excluded from the context. Once this was done, my build process consisted of running:

boot2docker up
docker build -t <repo:tag>
docker push <repo:tag>
boot2docker down

Container Hosting in the cloud

Unfortunately the container hosting landscape seems a bit immature at present – I’d love to have a Heroku-like service that lets me deploy scalable containers as simply as using a docker push. Also, while docker is standardised at the container level, most providers (ECS, Digital Ocean etc) seem to be inventing their own clustering layers on top. Maybe swarm will fix that – let’s wait and see.

I ended up going with Tutum – they have a good-looking, self-explanatory web interface, a web service API, and a CLI tool (brew install tutum). They don’t do the hosting themselves though – you need to register your own cloud host account (AWS, Azure, Digital Ocean) with them & they manage the nodes for you. They do give you a private repository, plus the service is ‘free forever’ if you sign up as a developer now. I’m using an AWS t2.micro instance under the free usage tier as the only node at present.

I set up the initial service definition via the web UI, to redeploy the latest image from the repo, I just need to do a tutum service redeploy <imageid>.

Scripting the deployment

I used rake as a build scripting tool, for no other reason than that’s what I normally use for Xcode builds. The process is simple enough that you could probably just use a bash script though.

task :run do
  sh "cabal install --only-dependencies"
  sh "cabal build"
  sh "dist/build/perthtransport/perthtransport"
end

task :deploy do
  version = File.open("perthtransport.cabal").read().match(/^version:\s*([^\s]*)$/)[1]
  puts "Building version #{version}"
  begin
    sh "boot2docker up"
    sh "docker build -t #{DOCKER_REPO}:#{version} ."
    sh "docker push #{DOCKER_REPO}:#{version}"
    sh "tutum service redeploy #{TUTUM_SERVICE_ID}"
    sh "git tag -a #{version} -m 'Build #{version}' & git push origin tag #{version}"
  ensure
    sh "boot2docker down"
  end
end

So now I can build & run locally with a rake run and deploy to an AWS node with rake deploy. Next week we’ll start on the actual watch app functionality. In the interim, the source code is available on bitbucket.

Watch App Development Blog – Week 1

Okay, I’m trying something new – a weekly blog post talking about my progress developing an app. The theory is that the thought of my massive readership expectantly waiting for the next update will give me enough of an incentive to get something finished. Everyone practise their sad face to make me feel guilty if I don’t post an update.

I’m keen to get out an Apple Watch app. To be honest, I don’t think they’ll make much money, but most apps I build are for other people; it would be nice to put out something good, so I can say “I did that!”

The Concept

Over the last few months, I’ve tried to be aware of instances where I need some information off my phone, but pulling it out & launching an app seems like too much of a hassle. One scenario I noticed was when I was heading to the train station – I used to know the departure times off by heart, but now I’m not sure whether to run or dawdle. It would be great if there was an app on my watch that gave me live departure times for my nearest station – challenge accepted!

Step 1: The API

Transperth don’t have a public API, although there’s an unofficial third-party one that scrapes the website. Unfortunately some parts were broken with a recent site update, and the developer now lives in Melbourne. I also have a few ideas for some custom API behaviour, so I made a probably ill-advised decision to build my own scraping API.

I really wanted to try out a web project in F#, but I didn’t want to develop on Windows and I ended up running into significant problems with Xamarin – broken project templates, unimplemented parts of the aspnetwebstack, etc. ASP.NET vNext looks promising, but I had issues with it also.

So I thought I’d give Haskell another go – I’ve tried this in the past, but I’m much gooder at Haskell now. The state of web frameworks in Haskell has also improved significantly since 2010. I went with Scotty – I like the simplicity of the Sinatra/NancyFx model, and there’s a great walk-through by Aditya Bhargava.

Haskell Web Development on OS X

If you’re playing along at home, you’ll need to follow the following steps to run the API:

  1. Install the Haskell Platform
  2. Run cabal sandbox init in your project directory. Cabal sandbox installs dependencies in a project scope, similar to Bundler in Ruby.
  3. Create a cabal file specifying your dependencies. This process I found a little odd – effectively you’re specifying your executable as a library, but it allows you to leverage cabal dependency resolution. Use Adit’s cabal file as a base.
  4. Create a Main.hs and add your Scotty routes (check out the examples).
  5. Run cabal install && .cabal-sandbox/bin/<executable name>

After an extended compile time, you should now have a web server running on localhost:<port>.

JSON Response Types

Returning JSON can be done by defining record types that implement the ToJSON type class (from Aeson):

{-# LANGUAGE DeriveGeneric #-}
module Types where

import Data.Aeson
import GHC.Generics

data Departure = Departure { time :: String, destination :: String, pattern :: String, status :: String } deriving (Generic, Show)
instance ToJSON Station

HTML Parsing

Parsing the DNN-generated web page is done using tagsoup. This differs from most other HTML parsing libraries I’ve used in that it doesn’t define a query API or CSS-like selector syntax over a DOM, it just converts the HTML into a flat list of nodes that can be manipulated using regular list functions.

My scraping function, which is probably not brilliant Haskell, looks like the following (excluding some helpers):

getTrainTimes :: String -> IO [Departure]
getTrainTimes x = do tags <- fmap parseTags $  openURL $ "http://www.transperth.wa.gov.au/Timetables/Live-Train-Times?stationname=" ++ (urlEncode x)
                     let table = head $ tables tags -- first table in page
                     let rowArray = reverse . tail . reverse . tail $ rows table -- strip first & last rows
                     let times = map (f . cells) rowArray -- convert each row into a Departure
                     return times
                  where f cs = Departure (textFromCell $ cellAtColumn 0 cs) (destFromCell $ cellAtColumn 1 cs) (patternFromCell $ cellAtColumn 2 cs) (textFromCell $ cellAtColumn 3 cs)

‘Stations Near Me’

In addition to querying for live times, I also have a flat text file of station names & locations I lifted from Darcy’s project. This is used to respond to the ‘all stations’ API call, and also supports a geospatial query endpoint using the gps package. Initially I started getting build failures with this dependency – it was trying to compile GPX file support, which I don’t need. The latest version (1.2) of the gps code has removed this dependency, but it’s not on Hackage yet.

Happily, this is solvable:

  1. Specify the specific version of the package in your cabal file: gps >=1.2
  2. Put the source code in your project directory (e.g. git submodule add git@github.com:TomMD/gps.git)
  3. Specify the new source directory with cabal sandbox add-source gps

Using the Geo.Computations model, it’s then fairly straightforward to filter the list of stations based on distance to a given point.

Bringing it Together

Once the stations, live times, and geospatial filtering was done, it was just a case of defining the appropriate route functions in Scotty:

  scotty port $ do
    get "/train/" $ do
      list <- liftIO stations
      json list

    get "/train/near" $ do
      y <- param "lat"
      x <-param "long"
      list <- liftIO $ stationsNear y x
      json list

    get "/train/:station" $ do
      stationId <- param "station"
      station <- liftIO $ station stationId
      case station of
        Just s -> do
          times <- liftIO $ getTrainTimes $ name s
          json times
        Nothing ->
          Web.Scotty.status status404

I haven’t touched cache control or more advanced error handling, and it would be nice to fall back on timetables if live times aren’t available, but I now have enough of an API running to support the basic functions of the watch app. One of the things I liked about doing it in Haskell was that once it compiled, it generally worked. It’s a pretty nice feeling.

I’ve put the code up on bitbucket – feel free to have a look through it and send some feedback if you can’t stand my beginner Haskell.

Next Steps

Next is hosting – building and deploying my dinky API somewhere I can reach it. Tune in next week for another thrilling instalment!

FP101x Review

I’ve just finished Erik Meijer’s FP101x “Introduction to Functional Programming” course, and it was a bit of a mixed bag. Note that this was my first MOOC, so take this review with a grain of salt.

Firstly, the good. Erik’s lectures were well-paced and entertaining, and for the most part communicated concepts fairly well. I won’t say he’s the most polished presenter, but his knowledge, enthusiasm and sense of whimsy (a plate of bananas was used as a prop at one point) combined to make the content quite watchable.

The lab format was quite good also. Typically there was a downloadable Haskell file with some unimplemented functions, then the lab questions took you through what each of the functions should do. Once done, you would paste some test code into GHCi that called the function, and then paste the result into the lab quiz. Because this is Haskell, generally once it compiled with no type errors, you got the right answer.

As an aside, it would be nice if you could paste your code into the quiz directly and have some QuickCheck magic running in the background – this can’t be done on the very general-purpose EdX platform, but hopefully that’s how we’ll learn code in the future.

The content was fairly well graduated also – I have some exposure to Haskell and FP, and didn’t have too many problems early on, but started to get a lot more challenged as the course progressed. Once we hit the M word some of the exercises became quite difficult (but mostly in a good way).

Now, the bad. This was ostensibly a 6 week course, but the lectures & exercises dropped two at a time. It might just be the psychological impact of splitting it up in this way, but I often found I’d only get one module done in a week, and I started to fall further and further behind. There was plenty of time to finish all the assessments after the fact, but I wouldn’t have been so down on myself if the content had have been spaced out a little more.

The course was intended to be language agnostic, but in practice it was very much a Haskell course. Certainly the FP concepts covered in the lectures were generic and widely applicable, and Erik did a good job of demoing functional style in other languages, but the assessments were nearly all Haskell-specific, and I can’t imagine anyone would have made it through without doing Haskell.

And now, the homework. There were a number of problems with this. Here’s a typical question, for context:

Higher Order Functions question

Answering this question format generally involved laboriously typing the possible answers (they’re images, so they can’t be copy & pasted) into GHCi, and running each one to see if it worked – it felt like a fairly mind-numbing chore, had a high chance of transcription errors, and didn’t really aid understanding at all. For the simpler examples, like this one, it was sometimes more reliable to try to reason about the code in your head than chance typing it incorrectly. Occasionally I found I would correct the intentional errors in the functions subconsciously while typing! This really only affected the scores, but it definitely detracted from the enjoyment of the course.

I can understand the value of including a few  ‘choose all the correct implementations’ questions early on while people are getting to grips with different features of the language, but for the most part I wanted to see what the idiomatic Haskell code should look like (i.e. I’m fairly confident some of those solutions to any wouldn’t be written by any self-respecting Haskell developer).

In some cases, the question was very abstract and it wasn’t really clear what the code was actually meant to do. These questions were really crying out for examples of inputs, or how the function is intended to be used – one example that I struggled with:

Consider expressions built up from non-negative numbers, greater or equal to zero using a subtraction operator that associates to the left.

A possible grammar for such expressions would look as follows:

However, this grammar is left-recursive and hence directly transliterating this grammar into parser combinators would result in a program that does not terminate because of the left-recursion. In the lectures of week 7 we showed how to factor recursive grammars using iteration.

Choose an iterative implementation of left-asociative expressions that does not suffer from non-termination.

Lastly, there were a number of instances where entirely new concepts were introduced in the homework that hadn’t been mentioned at all in the lectures  (e.g. redexes). I think some of these were covered in the book, but it had been mentioned earlier in the course that the book wasn’t really necessary, so I hadn’t been keeping up to date.

To sum up, I definitely know more Haskell now than when I started, so I’d have to call that a win. The course itself shows some promise, and I’d like to see the homework issues improved. I think the excessive genericness and one-size-fits-all of the EdX platform detracts from it a bit, but not terminally so. If you want to dip your toes into FP, don’t mind using Haskell to do it, and think you can cope with somewhat laborious homework tasks, you’ll definitely get value out of this.