Sunday 8 April 2012

The Llamaloc format

I've not got as far as I wanted to with the LlamaTrail reader. Someone emailed me asking about how the .llamaloc format works, so here's a brief description. I've also attached my proof-of-concept, no where near fit for human consumption app that reads them. Unfortunately, it's a Windows app written in C# rather than an Android app written in Java. Android apps are hard and fiddly to write and Java is a pig of a language, so a Windows C# app was the quickest way to check that Llama was logging stuff correctly.

The Llamaloc file format is a continuous stream of timestamped information. Each file is a separate day, so the timestamps are only the time of that day. Following the timestamp is a byte identifying the type of data that follows. After that is the data itself, whose length varies depending on the type of data. There are 3 types of data so far: Llama start, Llama shutdown and a cell change. Eventually, there will be wifi network and Bluetooth changes.

[1-byte datatype ID][4-byte milliseconds since midnight][datatype payload]

  • Datatype 0: Llama start
    • Payload length: 0
  • Datatype 1: Llama shutdown
    • Payload length: 0
  • Datatype 2: Cell change
    • Payload length: 8 bytes
    • [4-byte Cell Id][2-byte MCC][2-byte MNC]

You'll also need to open the Llama_Areas.txt. This is a geeky-human readable format, rather than binary. Each line represents an area, which is stored as a pipe-separated list. The first item in the list is the Area's name. All subsequent items on the line are the beacons (cells, wifi networks, etc). If a beacon starts with something non-numeric, then it isn't a cell*, and you should ignore it for now (it could be W=WiFi-name, M=WiFi-mac, B=Bluetooth or P=Map-point). The cells are colon-separated as CellId:MCC:MNC.

If you want to play with the app, you need to mount your phone's SD card and point the Llama Trail Reader at your Llama folder on your SD card. If you have a shiny new Galaxy Nexus, it doesn't have proper mass-storage support... I don't think Windows assigns it a drive letter. You'll have to copy the Llama folder to somewhere (e.g. your Desktop) and then point Llama Trail Reader at the copy.

As I mentioned, the app and the code is pretty horrible. If you can figure something out from it then great! Do post about it in a comment or email me. You may use the Llama Trail Reader code and app as you wish and at your own risk, but you may not sell anything derived from it. If you do, I'll get angry, but probably won't sue you because lawyers are boring and expensive. However, one day I may study law so watch out. If you want to release a free app with a donate button, then that's fine. If you have any questions or are unclear about anything, then email me.

Download Llama Trail Reader EXE and source

* - Llama was originally never meant to support anything other than cells.