Simple Audio Analysis with pyAudioAnalysis

I had a need to do some classification of sets of environmental audio files so started looking for an easy to use Python library that was up for the task. Here are my notes on setting up the pyAudioAnalysis Library for simple audio classification task.


This library relies on Python 2, so do a quick python –version to make sure you are not on Python 3. If both are installed on your machine they may be accessible as python and python3


You will need to make sure the following modules are installed:

  • numpy
  • matplotlib
  • scipy
  • gsl
  • mlpy
  • scikit-learn (v 0.16.1)
  • Simplejson

Note that the Anaconda Python 2.7 distribution has many of these packages already included, but you need scikit-learn (v 0.16.1) and the latest Anaconda distribution delivers the 0.17.1 version. If you get an error message referencing a missing hmm component, you likely have the 0.17.* version of scikit-learn, as hmm was deprecated in that version.

When the dependencies are all verified or installed, simply clone the repo into a directory you want to use for development.

mkdir ~/audioClassification
cd audioClassification
mkdir trainingData
mkdir sampleData
git clone

Training Data

The simplest way to get started it to create sub directories under trainingData for each sound category you wish to recognize. For this example lets use these

mkdir trainingData/breaking_glass 
mkdir trainingData/bubbles 
mkdir trainingData/vacuum

Next do a Google search looking for free audio files to add to the trainingData directory: e.g. breaking glass audio wav free, then for bubble sounds try bubbles audio wav free, finally for vacuum sounds try vacuum audio wav free. Save a dozen or so examples of each sound into the corresponding sub-directory under trainingData. The pyAudioAnalysis library requires wav files, so make sure any files you save to trainingData are wav files.

Sample Data

Next add some audio samples that can be used to test the training. The search is the same as above, but just choose different sample files, so you can test how well the classification model works. You can save them directly under the sampleData directory for this example. It is also good to choose a few random other sounds to see how they are interpreted by the classification model.


I wrote two quick scripts to do the classification and test a file against the classification model.

createClassifierModel Script

From inside the audioClassification directory

touch createClassifierModel
chmod +x createClassifierModel

In your favorite editor open createClassifierModel and add the following code:

from pyAudioAnalysis import audioTrainTest as aT
import os
from sys import argv
script, dirname = argv

subdirectories = os.listdir(dirname)[:4]

subdirectories = [dirname + "/" + subDirName for subDirName in subdirectories]

aT.featureAndTrain(subdirectories, 1.0, 1.0, aT.shortTermWindow, aT.shortTermStep, "svm", "svmModel", False)

testClassifierModel Script

From inside the audioClassification directory

touch testClassifierModel
chmod +x testClassifierModel

In your favorite editor open testClassifierModel and add the following code:

from sys import argv
import numpy as np
from pyAudioAnalysis import audioTrainTest as aT
script, filename = argv
isSignificant = 0.8 #try different values.

# P: list of probabilities
Result, P, classNames = aT.fileClassification(filename, "svmModel", "svm")
winner = np.argmax(P) #pick the result with the highest probability value.

# is the highest value found above the isSignificant threshhold? 
if P[winner] > isSignificant :
  print("File: " +filename + " is in category: " + classNames[winner] + ", with probability: " + str(P[winner]))
else :
  print("Can't classify sound: " + str(P))

Run the createClassifierModel Script

To create a classification model simply run the createClassifierMode script and pass in the name of the training directory as an argument to the script.

createClassifierModel trainingData

Below is an example output of the script.

                breaking_glass                  bubbles                 vacuum          OVERALL
        C       PRE     REC     F1      PRE     REC     F1      PRE     REC     F1      ACC     F1
        0.001   58.1    100.0   73.5    100.0   56.0    71.8    33.3    0.0     0.0     64.0    48.4
        0.010   83.7    100.0   91.1    100.0   95.0    97.4    98.5    65.0    78.3    90.0    89.0     best F1         best Acc
        0.500   80.0    94.0    86.4    100.0   99.0    99.5    81.8    54.0    65.1    85.2    83.7
        1.000   79.8    98.5    88.1    100.0   91.0    95.3    91.9    57.0    70.4    86.2    84.6
        5.000   79.4    94.5    86.3    100.0   93.0    96.4    81.2    56.0    66.3    84.5    83.0
        10.000  77.7    97.5    86.5    100.0   89.0    94.2    90.0    54.0    67.5    84.5    82.7
Confusion Matrix:
        bre     bub     vac
bre     50.0    0.0     0.0
bub     1.0     23.7    0.3
vac     8.8     0.0     16.2
Selected params: 0.01000

Run the testClassifierModel Script

To categorize an audio file simply pass the file name as an argument to the testClassifierModel script. In the example below a sample was named bubbles1.wav

testClassifierModel sampleData/bubbles1.wav

Below is an example output of the script.

File: sampleData/bubbles1.wav is in category: bubbles, with probability: 0.95486693161

Potential GOTCHAS

One issue is that not all wav files will be understood by the library. If the classification hangs or aborts then it is possible one of the downloaded wav files is the issue. I found the simple solution was to add a line to that printed the filename currently being worked on so I could see what was happening the first time using a new set of training files.

for me this is the location

datadef read(filename, mmap=False):
    Return the sample rate (in samples/sec) and data from a WAV file

    filename : string or open file handle
        Input wav file.
    mmap : bool, optional
        Whether to read data as memory mapped.
        Only to be used on real files (Default: False)

        .. versionadded:: 0.12.0

    rate : int
        Sample rate of wav file
    data : numpy array
        Data read from wav file

    * The file can be an open file or a filename.
    * The returned sample rate is a Python integer.
    * The data is returned as a numpy array with a data-type determined
      from the file.
    * This function cannot read wav files with 24 bit data.

    print("FILENAME: " + filename)


This was a basic intro to help you get started with pyAudioAnalysis library, check out the project wiki page for more use case for the library including other classification model options, as well as feature extraction, segmentation and visualization capabilities.

Org Export Configurations

Emacs org mode offers a variety of export options that make it easy to look at your notes in different formats, or perhaps make them available for others to view. Three I use regularly are markdown, mindmap, and reveal presentation.

My approach to Note Taking

The best way to learn something is to sumarize the topic in your own words, in your own context, and present it to others with concrete examples. But in many cases notes must also serve to provide details that are easily forgotten like code snippets, checklists, etc. Even with detailed notes it is important to refactor the information into your own context to aid learning the topic. For this reason many of my notes on a topic have a summary section and a details section both organized in an org document.

Another purpose for notes is information logging, such as meeting notes, project team notes, daily journal, etc. Although org does an excellent job of supporting information logging and task management, I will leave that as a topic for a future post.

Ideally the summary of a topic can easily be converted to a presentation, and the details can be converted to a markdown document. I will describe below how to accomplish this. Further I will describe how to convert the notes to OPML so it can be explored as a mindmap. Also see Deft + Org for Notes for information on quick search of all notes.

Setting Export Directory

I want to keep everything under the org directory but to keep things tidy create sub directories by export type. The code snippet below when placed in init.el will set the correct export directory based on export type. Thus opml documents will be kept in ~/org/export_opml/, markdown documents in ~/org/export_md/, and html documents in ~/org/export_md/

(defvar org-export-output-directory-prefix "export_" "prefix of directory used for org-mode export")

(defadvice org-export-output-file-name (before org-add-export-dir activate)
  "Modifies org-export to place exported files in a different directory"
  (when (not pub-dir)
      (setq pub-dir (concat org-export-output-directory-prefix (substring extension 1)))
      (when (not (file-directory-p pub-dir))
       (make-directory pub-dir))))

Exporting to Markdown

The configuration below will export markdown every time an org file is saved. It will also save a copy of the exported file to my Google Drive folder. This way my notes are always available from any web browser. The Minamalist Markdown Editor is a nice tool for viewing these documents on a Chromebook.

The (C-c m) keyboard sequence will open the markdown version of the current buffer in Marked 2. Because all notes are automatically converted the Marked 2 app will also allow you to follow note links to any interlinked notes. Marked 2 provides a very nice reading interface for detailed notes so having this option is handy.

(defun export-org-md-command-events ()
  (let* ((md-original-filename (concat (file-name-directory buffer-file-name) "export_md/" (file-name-sans-extension (file-name-nondirectory buffer-file-name)) ".md"))
         (google-drive-filename (concat  "../Google Drive/notes/" (file-name-sans-extension (file-name-nondirectory buffer-file-name)) ".md"))) 
    (execute-kbd-macro (kbd "C-c C-e m m"))
    (copy-file  md-original-filename google-drive-filename t)
    (message  "Saved to Google Drive: %s" (concat (file-name-sans-extension (file-name-nondirectory buffer-file-name)) ".md")) )

;; Auto-export org files to Markdown when saved
(defun org-mode-export-hook ()
  (when (equal major-mode 'org-mode)
    (add-hook 'after-save-hook 'export-org-md-command-events t t)

(defun markdown-preview-file ()
  "run Marked on the current file and revert the buffer"
  (execute-kbd-macro (kbd "C-c C-e m m"))
   (format "open -a /Applications/ %s" 
       (shell-quote-argument (concat (file-name-directory buffer-file-name) "export_md/" (file-name-sans-extension (file-name-nondirectory buffer-file-name)) ".md"))))

(global-set-key (kbd "C-c m") 'markdown-preview-file)

The markdown conversion works well but if you need to you can embed markdown directly into your org document at any time using a markdown block. This will allow the markdown to pass through during export so it will be handled properly by the markdown rendering app.

#+BEGIN_SRC js  :results output drawer
  var s = "JavaScript syntax highlighting"; 

Exporting to Mindmap

Mindmaps are a visualization of an outline, and since org mode specializes in keeping notes in a hierarchical fashion it is fairly easy to convert notes to mindmaps. OPML is an XML format for outlines that is supported by all mindmapping apps. You can use org-freemind to do mindmaps, but I use org-opml instead. Follow the org-opml installation instructions.

I also use a slight customization of the ox-opml.el file delivered with org-opml, because I use iThoughtsX and think it is cleaner to put paragraph blocks in notes rather than have them forced into a topic bubble.

;; modify original ox-opml.el to put paragraphs into the notes attribute of a topic
;; instead of displaying paragraph as topic name.  
(defun org-opml-paragraph (paragraph contents info)
  (let* ((parent (org-element-type (org-export-get-parent paragraph)))
         (text (clean-text contents)))
    ;; Only display paragraphs when not in a list item
    (unless (eq parent 'item)
      (format "<outline text='notes' note='%s' structure=\"paragraph\"/>"  text))))

(defun org-opml-item (item contents info)
  (let* ((p (car (org-element-contents item)))
         (elements (org-element-contents p))
         (text (mapconcat
                (lambda (el)
                  (cond ((stringp el) (clean-text el))
                        ((equal (car el) 'link)  
                         (let ((url (org-element-property :raw-link el))
                               (text (org-element-contents el)))
                           (clean-text (format "%s" (car text)))))
                        ((equal (car el) 'italic)
                         (format "/%s/" (car (org-element-contents el))))
                        ((equal (car el) 'bold)
                         (format "*%s*" (car (org-element-contents el))))
                        ((equal (car el) 'verbatim)
                         (format "=%s=" (org-element-property :value el)))))
                elements " ")))
    (format "<outline text='%s' structure='list'>%s</outline>" text contents)))

A second modification I use is to change the key-bindings for export because they conflict with markdown export. Below I changed the ?m in the original ox-opml.el file to ?g so Export to OPML will appear in the org export menu under the g key, and not m key

:menu-entry '(?g "Export to OPML"
                 (lambda (a s v b) (org-opml-export-to-opml a s v b)))

The Lisp snippet below can be added to init.el and will allow viewing an org buffer as a mindmap using iThoughtsX with the (C-c o) keyboard sequence.

(defun opml-preview-file ()
  "run iThoughtsX on the current file and revert the buffer"
  (execute-kbd-macro (kbd "C-c C-e g"))
   (format "open -a /Applications/ %s"  
       (shell-quote-argument (concat (file-name-directory buffer-file-name) "export_opml/" (file-name-sans-extension (file-name-nondirectory buffer-file-name)) ".opml"))))

(global-set-key  (kbd "C-c o") 'opml-preview-file)

Exporting to Reveal Presentation

Another useful feature is exporting the current org buffer as a Reveal Presentation and opening it in a browser. To do this you need to install and configure org-reveal. Once installed you can use the Lisp snippet below, the (C-c p) keyboard sequence will open the the current buffer as a Reveal Presentation in Safari (I use Mac).

(defun 'presentation-preview-file ()
  "run export with ox-reveal on the current file and open browser"
  (execute-kbd-macro (kbd "C-c C-e R R"))
   (format "open -a /Applications/ %s" 
       (shell-quote-argument (concat (file-name-directory buffer-file-name) "export_html/" (file-name-sans-extension (file-name-nondirectory buffer-file-name)) ".html"))))

(global-set-key  (kbd "C-c p") 'presentation-preview-file)

Hiding Content

I mentioned above that I like to organize my notes with both a summary for presentation, and details that would not work well in a presentation. To make it easy to hide content from the various export modules I added the code below to my init.el file.

 (defun set-ignored-headlines-tags (backend)
 "Remove all headlines with tag ignore_heading in the current buffer. 
    BACKEND is the export back-end being used, as a symbol."
 (cond ((org-export-derived-backend-p backend 'md) (setq  org-export-exclude-tags '("noexport" "mdignore")))
       ((org-export-derived-backend-p backend 'reveal) (setq  org-export-exclude-tags '("noexport" "revealignore")))
       ((org-export-derived-backend-p backend 'opml)  (setq  org-export-exclude-tags '("noexport" "opmlignore"))) 
       (t (setq  org-export-exclude-tags '("noexport")))

Now I can hide content from reveal by adding a :revealignore: tag to the heading. The :opmlignore: and :mdignore: work similarly. :noexport: means hide from all exports. The tags support hierarchy so will hide any sub-headings.

* My Slides :mdignore:opmlignore:
 ** Topic 1
    Slide content
 ** Topic 2
    Slide content
* My Detailed Notes  :revealignore:
 ** Chapter Notes
 ** Code Experiments :opmlignore:


With this setup is is easy to keep notes in a fashion that makes them easy to use in a number of formats, including presentations, mindmaps, and markdown documents. Org mode also supports the concept of publishing that is useful when sharing specific content, for example exporting specific notes to a web site along with images and attachments used in the notes.

Deft + Org for Notes

In the nvALT and Emacs post I described an integration between nvAlt and Emacs using Deft for markdown notes. I the past year I have moved to using Deft for org notes rather than markdown notes. The nice thing about combining Deft with Org is that your notes are indexed and easy to find using Deft, but also retain all of the power of Org to orgainize and present information. For example typing decision boundary into deft quickly cuts down hundreds of org text notes to the handful that contain the words decision and boundary in them.

Deft also supports regular expression search mode to provide more precise searches (use C-c C-t to toggle search modes). Deft makes it easy to create new notes also, simply type a title and hit ctrl-return to create a new note with that title. See the UI in action in the animated gif below (image by Jason Blevins via Deft ). See the Documentation for other handy features.


Below I describe setting up Deft for emacs, and show my current customization’s. Org also supports export to many different formats. In a future posts I will cover my setup for exporting notes to markdown documents, reveal presentations, and even mindmaps.

Installing Deft

Follow the instructions at Deft to install from source (usually the latest version this way) or use the Emacs package installer as shown below.

M-x package-install deft

Configuring Deft

I prefer to use Deft for org files and not others (txt, md, etc), so that is reflected in my configuration below. Using this technique I converted the tab key into a hyper-key (C-M-S-s), so with the key mapping below Deft can be called up with tab-d This technique is nice, because the tab key still works for tabbing, but when held down it acts like an additional modifier key that can be use in emacs key bindings.

(require 'deft)
(setq deft-default-extension "org")
(setq deft-extensions '("org"))
(setq deft-directory "~/org")
(setq deft-recursive t)
(setq deft-use-filename-as-title nil)
(setq deft-use-filter-string-for-filename t)
(setq deft-file-naming-rules '((noslash . "-")
                               (nospace . "-")
                               (case-fn . downcase)))
(setq deft-text-mode 'org-mode)
(global-set-key (kbd "C-M-S-s-d") 'deft)
(global-set-key (kbd "C-x C-g") 'deft-find-file)

Org Mode ES2015+ Code Blocks (updated)

  • Note: In this post I have updated the instructions for use with Babel 6x. For Babel 5x see the original post.

Babel 6x is a significant change from Babel 5x, as the cli is now a separate node module called babel-cli and transforms are now also delivered as separate packages.

First make a few changes to the emacs environment so you can use JavaScript in org mode, as well as find local node.js modules you have installed. Replace ”~/org/node_modules” in the configuration below with the location of any local node modules you want to use. Using this approach you don’t have to pollute the global node_module directory if you don’t want to.

Add the following to your emacs init.el file and evaluate it (or restart emacs). Make sure the $HOME environment variable is set in your environment; or you could just hard code the absolute path to the node_modules directory in the code below.

(setenv "NODE_PATH"
   (getenv "HOME") "/org/node_modules"  ":"
   (getenv "NODE_PATH")

 '((js . t)))

You can choose to install the Babel modules globally, or you can do it locally. In this example I will install them locally in the org directory (~/org/node_modules).

Next install the babel-cli module, this allows you to call Babel from the command line. You will also want to install the transforms you plan to use, the example below installs the common preset transforms used with Babel 6. Also install any local modules you need to use. I chose to install them from the ~/org directory where my notes are kept, but anywhere works as long as you have the correct path to node_modules set above.

npm install --save-dev babel-cli
npm install --save-dev babel-preset-es2015
npm install --save-dev babel-preset-stage-0
npm install --save-dev babel-preset-stage-1
npm install --save-dev babel-preset-stage-2
npm install --save-dev babel-preset-stage-3
npm install --save-dev babel-preset-react
npm install --save-dev mongodb
npm install --save-dev bluebird

Next you want to set up a symbolic link to the babel-cli script you just installed so it can be found from the command line. I decided to call it org-babel-node so it won’t interfere with a babel-node executable linked to a global module of the same name.

ln -s ~/org/node_modules/babel-cli/bin/babel-node.js /usr/local/bin/org-babel-node

The default org-mode interpreter for JavaScript is Node, so you need to have that installed and its path set. But the cool thing is that you can change the interpreter inline in your code blocks in the cases you want to experiment with upcoming language features. To do this you simply tell org mode to use an alternative interpreter; in this case the babel-node transpiler installed earlier and linked as org-babel-node.

Adding :cmd “org-babel-node” after the #+begin_src js tells org mode to use the org-babel-node transpiler instead of the default JavaScript interpreter. Because Babel 6 uses external modules for transforms you need to also tell Babel which preset or plugins you wish to use with either the –presets or –plugins options. The :results output tells org mode that the results will be from an output statement (using console.log() for JavaScript)

   #+name: db.activities.findOne
   #+begin_src js :cmd "org-babel-node --presets stage-1" :results output drawer
      (async function(){
          try {
              let MongoDB = require('mongodb');
              let Promise = require('bluebird');
              let db = await MongoDB.MongoClient.connectAsync(process.env.MY_DB);
              let activityCol = db.collection('activities')
              let result = await activityCol.findOne();
              console.log(`The first activity name is ${}`);
             throw err;

Now, simply place the cursor anywhere in the block and execute it using C-c C-c. The results will be placed under the block in second block entitled: #+RESULTS:

The block can be executed as often as you like and the results will be refreshed. See the updated example with its results block below.

   #+name: db.activities.findOne
   #+begin_src js :cmd "org-babel-node --presets stage-1" :results output drawer
      (async function(){
          try {
              let MongoDB = require('mongodb');
              let Promise = require('bluebird');
              let db = await MongoDB.MongoClient.connectAsync(process.env.MY_DB);
              let activityCol = db.collection('activities')
              let result = await activityCol.findOne();
              console.log(`The first activity name is ${}`);
             throw err;

   #+RESULTS: db.activities.findOne
   The first activity name is Shopping

You can see several new and experimental language features including async functions, the await keyword for performing a non-blocking wait on a promise to complete, and template strings.

ANCS Example on BLE Nano

I decided to try getting Apple Notification Center Service (ANCS) working with the RedBearLab BLE Nano, and this post describes one way to get the Nordic ANCS demo running on a BLE Nano. This post shows how to get an ARM development environment and toolchain up and running on OS X in order to develop apps for the Nordic BLE SoC’s (e.g. nRF51822 based boards like the BLE Nano).

There are a few options for developing applications for the BLE Nano:

  1. Using the Nordic nRF5 BLE SDK along with the arm-gcc compiler. This requires setting up a toolchain on your local development machine (Mac OS X in my case).
  2. Using and the mbed Bluetooth Low Energy API. This is the fastest way to get started, but unfortunately at the time of this post the API does not yet support peripherals as GATT Clients, and thus does not support ANCS development.
  3. Using the Arduino SDK along with the nRF51822-Arduino add-on. I am not sure whether this add-on would support peripherals as GATT Clients either, and haven’t yet investigated the option.

I decided to start with approach 1 since it seemed like the most stable approach to development. Below I describe my steps to getting the environment set up on OS X. For more on approach 2 & 3 see Getting Started with nRF51822

Setting Up the Tool Chain on OS X

Install the arm-gcc compiler for OS X so you can compile for ARM devices. Fortunately both HomeBrew and MacPorts have recipes for installing the compiler. Pick the one that works for you. If you don’t have either HomeBrew or MacPorts installed please install one of them before proceeding.

Install the gcc-arm compiler using either brew command (HomeBrew) or port command (MacPorts):

brew install gcc-arm-none-eabi


port install arm-none-eabi-gcc

Note: If you get a permissions error you may need to prepend the sudo command to provide brew/port with enhanced security privileges.

You will need to save the location of the arm-gcc compiler for updating the nRF5 toolchain config files later. In my case it was located in


you will also need the compiler version number, just run the command below and write down the resulting version number

/usr/local/gcc_arm/gcc-arm-none-eabi-5_2-2015q4/bin/arm-none-eabi-gcc  --version 

In my case the /arm-none-eabi-gcc version was 5.2.1

Download the Nordic SDK

The next step is to download the Nordic nRF5 SDK I chose nRF51_SDK_v10.x.x. Unzip into a location that will be your working directory for the project.

Download the Nordic Soft Device BLE Protocol Stack

Nordic uses the term Soft Device to refer to its BLE protocol stack. I chose to use S130-SD, it can be downloaded from the Nordic Download Page under soft devices.

You will need to reference the soft device later, so I suggest saving it in your working directory at the same level you saved the SDK so it is easy to find.

Updating the SDK configuration

The next step is to modify the SDK configuration to point to your arm-gcc compiler. In your SDK directory edit components/toolchain/gcc/Makefile.posix to correct the GNU_INSTALL_ROOT and GNU_VERSION. GNU_INSTALL_ROOT should be the location of the arm-gcc compiler directory. *GNU_VERSION* should be the version number of the arm-gcc compiler that I mentioned above. My Makefile.posix file looks like this:

GNU_INSTALL_ROOT := /usr/local/gcc_arm/gcc-arm-none-eabi-5_2-2015q4/
GNU_VERSION := 5.2.1 
GNU_PREFIX := arm-none-eabi

Compile the ANCS example

The ANCS example is located in the sdk driectory under the examples subdirectory. Change to the subdirectory for the ble_app_ancs_c example. For example from the main SDK directory:

cd examples/ble_peripheral/ble_app_ancs_c

Like all the examples the ble_app_ancs_c directory contains board package subdirectories that are set up for the various development boards. For my test I changed to subdirectory:


This is essentially choosing the example created for board package pca10028 and soft device s130 and finally the armgcc build directory.

In this directory your will find a Makefile for compiling this example, so run make to compile the example.


The compilation process will create a new subdirectory called _build that will hold the output of the compile. The key file for our purposes will be the one with a .hex extension. In my case is was named nrf51422_xxac_s130.hex. This is the hex code that will be loaded by the bootloader on the BLE Nano’s nRF51822 SoC.

Since the nRF51 device is completely flash based. All the executable code, including Nordic’s “Soft Device” protocol stack and your applications, is programmed in this flash memory. The soft device is always in the lower region of the flash, using up to 128 kB, and the rest of the upper region of flash is available for your application. So before your applications hex code can be loaded on the BLE Nano, it must be merged with the hex code for the soft device, in this case the S130 hex code.

To manipulate hex code you will need the srecord tool, which can be installed with HomeBrew or MacPorts.

brew install srecord 


port install srecord

Merging application Hex Code with Soft Device Hex Code.

Assuming the S130 Soft Device code was uncompressed into the same working directory as the sdk and was named s130_nrf51_1.0.0 and the example application hex code file was named nrf51422_xxac_s130.hex. Then from inside the _build directory created above we could merge the hex code files with the following command.

srec_cat <SDK_DIRECTORY>/s130_nrf51_1.0.0/s130_nrf51_1.0.0_softdevice.hex -intel nrf51422_xxac_s130.hex  -intel -o ancs.hex -intel --line-length=44

The above command would create a new (combined) hex code file in _build named ancs.hex

Loading the code on the BLE Nano

This is the easy part. With the BLE Nano piggy backing on its MK20 USB board and plugged into a USB port, a folder named MBED should appear on your desktop (at least that is what it is named in my case). Just drag the combined hex file we created above (ancs.hex) to the MBED folder associated with the Nano device. The bootloader should load the new code, and the USB device may disappear momentarily from the desktop, then reappear.

Test that the ANCS application was loaded correctly

On an iPhone, open the Settings app, and choose Bluetooth and make sure Bluetooth is on. Under Devices you should see ANCS appear, and by tapping ANCS you should be able to successfully pair with the device.

Next Steps

The goal of this process was to get the ARM toolchain and Nordic SDK set up, next steps would be to use the ANCS example as a starting point to develop a custom ANCS app for some device that utilizes the BLE Nano. I hope to post some examples in the future as I work with the Nano more.

ANCS Message Display


Ever want to see that last iPhone message without checking your phone. It is actually fairly easy to create a secondary message display using an Arduino, BLE, and an LCD display to conect to the Apple Notification Center Service on your iPhone.

For this project I used the Blend Micro from RedBearLab, combined with an AdaFruit ST7735R TFT LCD display The Blend Micro combines an Atmel ATmega32U4 micro-controller with a Nordic nRF8001 BLE chip. Simply hook up the LCD using SPI and you are in business. For this project I added a piezo buzzer for sound effects and a button to wake up the display if it has timed out.

The basic idea is to have the iPhone pass along alerts to the device using BLE/ANCS and to have the device play a tone and display the alert information. There is a timeout to power down the backlight on the display after a minute, and a button that can be pressed to turn the display’s backlight on, so the last message can be viewed after the one minute timeout. This power savings mode could allow the device to be powered by a battery.

I created a demo project on codebender to make it easy to replicate. You will need to import a few libraries into your personal libraries on codebender to get the project to work. It would be easy to enhance the project to save the last several messages and use a 2-Axis Analog Thumb Joystick to control a simple interface that scans through messages.

Unfortunately the Blend Micro does not have an on-board LIPO charging circuit, so if you want to enable a combined USB/Battery solution a charging circuit would have to be added. RedBear warns that connecting a battery to VIN and USB simultaneously could damage the board.

I printed up a simple enclosure on the 3D printer and here is the enclosed LCD panel.


  VIN & GND -> to LIPO battery (DO NOT use USB power when battery connected)
  PIN 2     -> ST7735R LITE
  PIN 8     -> ST7735R D/C
  PIN 9     -> ST7735R Reset
  PIN 10    -> ST7735R TFT_CS
  PIN 11    -> ST7735R MOSI
  PIN 13    -> ST7735R SCK
  PIN V33   -> ST7735R VCC
  PIN GND   -> ST7735R GND

  Button -> PIN 5, GND
  Buzzer -> PIN 3, GND

Detailed Instructions

Follow the instructions for using Blend Micro on codebender. You should be able to get the LED Blink example working before continuing.

Add key libraries

To compile the code in the project above you will need to add several libraries to your personal libraries on codebender. Go to and you will see the *Upload Libraries button on the upper right side of the page. There are four libraries you need to add.

Just download each of these as a zip file from github, and upload them to your codebender personal library. I created a fork of the ANCS-Library to thin it down a bit as memory was tight on the Blend Micro for another version of the project I am working on. It is on a branch called code-diet available on github ANCS-Library on a code-diet zip

Finally, clone my codebender ANCS_Display_ST7735 project and verify the code compiles with the libraries you uploaded, and run the project on Arduino.

Open the iPhone Settings app and select Bluetooth. If everything is working correctly you should see ANCS_RUSK listed under MyDevices. Select it and choose pair.

Once paired you should hear a tone on the device, and the display will change from Status: Not Connected to Status: Connected. If you receive any alerts on your iPhone you should now hear a tone on the device and the screen should display a message.

You can update the code to support custom tones and messages for different alert types, or add other interesting features.

Additional Notes

  • The Blend Nano from ReadBearLab is a tiny alternative to the Blend Micro but it is based on the ARM Cortex-M0 SoC and uses the newer Nordic nRF51822 BLE chipset. The ANCS-Library is only compatible with the Nordic nRF8001 BLE chipset, so some work would be needed to port the library to the new platform.
  • Adafruit has just announced a few similar Arduino+BLE boards. The Feather 32u4 Bluefruit LE using the ATmega32u4, and the Feather M0 Bluefruit LE using the ATSAMD21G18 ARM Cortex. Both these boards provide a built in 100mA lipoly charger, so either would be a better choice for a mobile device. Both these boards use the nRF51822 BLE chipset so like the Blend Nano would require porting the ANCS-Library before the code above could be used.
  • I have a SHARP Memory Display Breakout from adafruit, which is a really nice eInk type display, but was unable to get it working with this demo on first try. This codebender sketch was my first attempt. It seems that there is a conflict between the Adafruit_SharpMem library and the ANCS Library, because instantiating the Adafruit_SharpMem display object causes calls to notif.setup() to hang. I may look at it a bit more if I get a chance, but this was to be a quick experiment. There were some memory size issues initially, but I believe the hang may be an SPI issue, but I haven’t yet had time to investigate further.
  • I also started to play with a headless version that instead uses neoPixels. I will post when I finish it. I like the idea of a fun neoPixel and sound only display connected with an iOS app that allows the user to customize what notifications the display responds to and how it responds. This would allow cheap simple peripheral displays to be created that respond to different notifications in different ways.
  • The ESP32 should make for an interesting platform for these types of displays because they could allow BLE for notifications, and use WiFi for connection to the home network. This could allow control a wide range of WiFi enabled home devices based on iOS app notifications. That sounds fun.

Org Mode ES2015+ Code Blocks

  • Updated: I have updated instructions for installing and using the recently released Babel 6 with org mode.

I use emacs org mode to keep notes including code nodes that support inline execution. It is convenient for keeping useful code snippets, as well as experimenting while taking notes. Because of features like Org + Deft it is really easy to find the sweet spot between keeping coding notes organized but also easily searched.

As I have started to explore more ES6 and even ES7 features I wanted a way to transpile on the fly in my coding notes. It turns out it is very easy.

First make a few changes to the emacs environment so you can use JavaScript in org mode, as well as find local node.js modules you have installed. Replace ”~/org/node_modules” in the config below with the location of any local node modules you want to pick up. Using this approach you don’t have to pollute the global node_module directory if you don’t want to.

Add the following to your emacs init.el file and evaluate it (or restart emacs).

(setenv "NODE_PATH"
   "~/org/node_modules" ":"
   (getenv "NODE_PATH")

 '((js . t)))

Next install the babel npm module globally, this allows you to call babel from the command line also. Then install any local modules you need to use. I chose to install them from the ~/org directory where my notes are kept, but anywhere works as long as you have the correct path set above.

npm install -g babel
npm install mongodb
npm install bluebird

The default org-mode interpreter for js is node, so you need to have that installed and its path set. But the cool thing is that you can change the interpreter inline in your code blocks in the cases you want to experiment with upcoming language features. To do this you simply tell org mode to use an alternative interpreter; in this case babel-node, which also transpiles.

Adding :cmd “babel-node” after the #+begin_src js tells org mode to use the babel_node command instead of the default JavaScript interpreter. The :results output tells org mode that the results will be from an output statement (using console.log() for JavaScript)

   #+name: db.activities.findOne
   #+begin_src js :cmd "babel-node" :results output drawer
      (async function(){
          try {
              let MongoDB = require('mongodb');
              let Promise = require('bluebird');
              let db = await MongoDB.MongoClient.connectAsync(process.env.MY_DB);
              let activityCol = db.collection('activities')
              let result = await activityCol.findOne();
              console.log(`The first activity name is ${}`);
             throw err;

Now, simply place the cursor anywhere in the block and execute it using C-c C-c. The results will be placed under the block in second block entitled: #+RESULTS:

The block can be executed as often as you like and the results will be refreshed. See the updated example with its results block below.

   #+name: db.activities.findOne
   #+begin_src js :cmd "babel-node" :results output drawer
      (async function(){
          try {
              let MongoDB = require('mongodb');
              let Promise = require('bluebird');
              let db = await MongoDB.MongoClient.connectAsync(process.env.MY_DB);
              let activityCol = db.collection('activities')
              let result = await activityCol.findOne();
              console.log(`The first activity name is ${}`);
             throw err;

   #+RESULTS: db.activities.findOne
   The first activity name is Shopping

You can see several new and experimental language features including async functions, the await keyword for performing a non-blocking wait on a promise to complete, and template strings.

ESP8266 Initial Notes

Here are a few notes from my experiments with the ESP8266

I have started testing the ESP8266 as an inexpensive WiFi enabled IoT device platform. I will added specific how-to notes later but wanted to capture a few items from my initial experiments.

I started with the Sparkfun Thing, which is a nice ESP8266 dev board that supports integrated LiPo battery management. They have a nice Hookup Guide to get you started.

My use case is a very simple IoT type device that will send data to a cloud service that I have developed. The cloud service will aggregate the data from multiple personal IoT devices for a user. These devices will generally be powered via LiPo battery when in use for interaction and placed in a charging tray when not in interactive use. The devices are always active but have special meaning when in interactive use.

These constraints mean that battery life is a critical factor, but I do not need days, months, or years of battery life. The ESP8266 is a fairly power hungry device, especially when transmitting data, but it does have some power management features, most notably deep sleep.

Notes from my initial experiments:

The Kit

I used the Sparkfun Thing, FTDIBreakout for uploading code, and LiPo battery.


An easy way to get code running is to use the Arduino Addon that lets you leverage the Arduino libraries in programming the ESP8266. An alternative I will try in the future is the Lua based firmware

When using the FTDI to program the board take note that GPIO0 is used to set the run mode of the firmware. 3.3V puts it in run mode and 0V puts it in program mode (bootloader). This is easy to miss in the instructions, so be sure to connect the 0 pin to ground when you wish to upload the code from the Arduino IDE.

Power Management

To use the deep sleep mode on the Sparkfun Thing you must connect XPD to DTR. Sparkfun connected DTR to RST on the Thing so a short negative voltage will reset the device. When in deep sleep most system services are powered off, but the RTC and timer interrupt remains active for the purpose of waking the device from sleep. This is handled by the firmware once these pins are connected, however this means you will have to remove the FTDI programmer to test the deep-sleep mode.

The deepsleep() call looks a lot like a delayMicroseconds() call, simply pass it the number of microseconds before it should wake up again. In deep sleep mode, the ESP8266 hits about 60 µA of power draw, down from its average of around 75mA, and the 200mA used while transmitting.

It should be possible to connect a button or some other independent sensor as an alternative to a timer based wakeup, so the device can be awaken by a button press or some physical world event.

  ESP.deepSleep(1000000);  //sleep for 1 second

Saving State

Unlike a call to delay() or delayMicroseconds(), the deepsleep() function actually causes the device to power down everything except the RTC and related services. Wake is essentially a device reboot and previous state is not maintained. This means any state will need to be stored in the ESP8266 EEPROM. For this there is an EEPROM library and EEPROM.get()

  //some struct for saved object
  struct BackupObj{
    int setting;
    int data;

  int eeAddress = 0;
  EEPROM.begin(4096);  //set up memory allocation
  EEPROM.put( eeAddress, backupObj );

  int eeAddress = 0; 
  EEPROM.get( eeAddress, backupObj );

Adding Components

The device works well for I2C, in my case I tested with an MPU-6050.

  #include <Wire.h>

  void setup() {
    // ... other setup code
    Wire.write(0x6B);  // PWR_MGMT_1 register
    Wire.write(0);     // set to zero (wakes up the MPU-6050)

  // using arduino's loop mechanism
  void loop(){
    // ... other loop code
    Wire.write(0x3B);  // starting with register 0x3B (ACCEL_XOUT_H)
    // ... other loop code

I tested using GPIO with a piezo used as a speaker. The Speaker is capable of playing simple notes using frequency of note mapped to cycles of sound and delay.

  #define NOTE_C5  523 //middle C
  #define NOTE_D5  587

  const int SPEAKER_PIN = 5;
  void playNote(int targetPin, long frequency, long length) {
    long delay = 1000000 / frequency / 2; 
    long cycles = frequency * length / 1000; 
    for (long i = 0; i < cycle; i++) { 
      digitalWrite(targetPin, HIGH); 
      digitalWrite(targetPin, LOW); 

  long noteDuration = 500;
  long frequency = NOTE_C5;

  playNote(SPEAKER_PIN, frequency, noteDuration);

I tested analog sensor input in the form of a second piezo connected to the ADC pin as a knock sensor. ADC is the only analog input pin on this device.

  const int KNOCK_SENSOR = A0;
  const int KNOCK_THRESHOLD = 70;

  sensorReading = analogRead(KNOCK_SENSOR); 
  if (sensorReading >= KNOCK_THRESHOLD) {
    long noteDuration = 500;
    long frequency = NOTE_E5;
    playNode(SPEAKER_PIN, frequency, noteDuration); 

Finally there were enough pins remaining to hookup an RGB LED breakout. I added this test using the RGB Tools Lib.

  #include <RGBTools.h>

  const int RED_PIN = 4; 
  const int GREEN_PIN = 12; 
  const int BLUE_PIN = 13;

  // set the RGB pins - here I used pins 4, 13, and 12
  // use RGBTools rgb(4,13,12, COMMON_CATHODE); if using a cathode RGB
  RGBTools rgb(4,13,12); 

  //set a nice red

##Conclusion This was a quick run through to test some of the feature of the device, but even with a few sensors/actuators and a simple setup there is a nice combination of status and interaction feedback that can be performed with a simple and relatively inexpensive device. The Sparkfun Thing retails for around $15 right now but the Huzzah is under $10, and others can be found closer to $5.

Self Updating Edison Apps

One of the challenges I have had in handing out prototype devices is keeping the software up to date. Solutions like <a href-“” target=”_blank”></a> do a nice job of deploying bundler images onto devices like the Edison. The primary issue I had was the overhead of pushing bundler images around when the only thing that was changing was the node app. It seemed easier to just use git and npm to handle the updates. I may go the route later, but this early in dev and testing the git route seems simpler.

Overview of What I Did

The product I am prototyping has two parts, an Edison device (with additional sensors and actuators) running a node app, and a node web service for managing device configuration and data running in the cloud.

  1. The device’s node app is published in a private github repository.
  2. I installed and configured git on each of the Edison devices.
  3. I cloned the github repository onto each of the Edison devices.
  4. I installed the forever module on each of the devices to keep the app up and allow easy restarting of the app.
  5. I created a startup script that starts the app using forever.
  6. I created and enabled a linux service that runs the startup script on boot.
  7. I added code to the app to periodically ask the web service what the latest version of the app should be.
  8. If a new version is available the app will do a pull and use forever to do a restart using the new version.

The Details

Initial Cleanup

  • Remove any app from the default Edison node_app_slot directory so you don’t accidentally start the app using the default Edison process.
mv /node_app_slot /node_app_slotbk
mv  ~/.node_app_slot/ ~/.node_app_slotbk

Install Git

#### Update /etc/opkg/base-feeds.conf with these 3 lines src all src x86 src i586 #### Update opkg and install git opkg update opkg install git

Option 1: Modify Edison’s default port

I wanted to use port 80 for the node app so I moved the default Edison config service to port 8080

Change default port in edison-cofig-server

Edit /usr/lib/edison_config_tools/edison-config-server.js and change the last line to use a port other than 80.


Option 2: Disable the Edison config web service

systemctl disable edison_config
systemctl stop    edison_config

Setup to use github

Generate a key for use with github

  • ssh-keygen -t rsa -b 4096 -C “”

Follow the directions, easiest is just to hit return at the prompts. I chose to not do a passphrase for my small pilot.

Generate a deployment key for the github repository

  • Go to your app’s github repository, choose settings, choose deployment keys
  • Click the Add Deployment Key button
  • Give it a title (the host name for the device works)
  • Back on the Edison run cat /home/root/.ssh/ to get the text for the public key
  • copy the text for the public key to the Key input box back on github.

Clone your repo

Back on the Edison

cd /
git clone <your repo> AppDirName
cd /AppDirName

Pull Latest code

Now any time you update code on master a simple git pull will update the latest code.

git pull

Install forever module using npm

Forever will automatically restart a node app if it crashes. It also has some handy restart features.

npm install -g forever

Create a startup script & service

Creating a startup service will allow your app to start automatically using forever.

Create to start node app (server.js in this case)

cd /AppDirName 
forever start server.js

Make executable

chmod +x

Create a startup service file at /lib/systemd/system/startup.service


Enable startup service

systemctl enable /lib/systemd/system/startup.service

Enable your node app to update itself

By using a simple update function you can get your app to update itself and restart.

var spawn = require('child_process').exec;
var semver = require('semver');
var bunyan = require('bunyan');
var log = bunyan.createLogger({
    name: 'app',
    streams: [{
        type: 'rotating-file',
        path: '/var/log/app.log',
        period: '1d',
        count: 7        
var pjson = require('./package.json');

var checkVersion = function(){
  var currentVersion = pjson.version;
  var options = {  hostname: '',
                             port: 80,
                   path: '',
                   method: 'GET',
                   headers: {'Content-Type': 'application/json'}
  var callback = function(response) {
    var dataStr = '';
    response.on('data', function (chunk) {
      dataStr += chunk;

    response.on('end', function () {
      var versionInfo = JSON.parse(dataStr);
      var latestVersion = versionInfo.client_version || "0.0.0"; //don't update if missing version info"current version: ", currentVersion);"latest version: ", latestVersion);
      if (, currentVersion)){"pulling newer versions");
        spawn('git pull', function(error, stdout, stderr) {
          if (error){
            log.error("ERROR pulling latest: ", error);
  "updating packages");
            spawn('npm update', function(error, stdout, stderr){
              if (error){
                log.error("ERROR updating packages: ", error);
              else {
      "restarting node");
                spawn('forever restartall', function(error, stdout, stderr){
                  if (error){
                    log.error("ERROR restarting: ", error);
                  else {

//check for updates at app startup

//then check for updates every hour;
setInterval(function() {
  }, 3600000);

On the server

You will need to add a route on your server to provide the version info. In this example the route was a GET request to the /device_version route. For simplicity I just use an env_var on the service. I simply update the env_var when a new version is available. Then in the logic for the /device_version route I pass back the version found in the env_var.

The logic for comparing versions is very basic and flawed, but will work in this simple case.


Ideally instead of a straight git pull you can instead download a tagged version, and keep the current and next version info for each device in the web service db. This would allow rolling out upgrades to specific devices, etc. Another approach would be to pass back version info to the device so updates could roll out immediately if the device is in use. Finally more logic on the device to schedule an update when not active would be ideal. In that case maybe adding more than versionNumber of the latest version to the server response, maybe a priority value also.

This was a quick experiment it getting updates to percolate out to devices prototype devices, and so far it seems to be working well.

Workbench Replaces My Desk

I changed my desk out for a workbench and am very pleased with the results. I made the switch for two reasons:

  1. I spend a lot of time at my desk and wanted to mix in sitting and standing throughout the day.
  2. I started to work more frequently on small hardware projects and found that being able to stand and move about the bench was more comfortable.

A few additional changes I made:

  • I found that I needed more tools at hand when I was working on hardware projects, so I brought in a small tool cabinet from the garage.
  • I wanted to have access to a large number of “Maker” materials in my office vs. the garage, so I also added an IKEA Alex cabinet. These can often be found in their discount section for around $60 if you don’t mind a few minor marks. This cabinet holds larger hardware components (like Arduino boards) as well as design/art supplies like paper, ink, paint, cutting/carving tools, etc.
  • I wanted to have some smaller supplies at hand on top of the desk so I added a few Art Supply Drawers for the top of the bench. The one to the left of the monitor holds small electronic components. The one to the right holds drawing pencils, pens, markers, etc that I use frequently.
  • I added a digital soldering station and exhaust fan. I still have a soldering station in the garage, but having one at hand is very convenient.
  • Another handy addition is the USB Microscope, as some solder joints just require very careful inspection. This is especially true with soldering of small components and SMD components.
  • I also had to add a bench height chair.
  • The workbench is a Gladiator 8 ft. maple workbench I had in the garage for a long time. The new ones allow height adjustment, and there are also less expensive bamboo top options.

I am very pleased with the setup. One nice feature is the workbench depth is less than a traditional desk, so I gained some space back in the office. The main benefit is just better productivity, I find certain tasks are just easier to accomplish when standing. The final benefit? With two greyhounds in the house, having a tall desk means fewer expensive pens and markers go missing.

I2C MPU-6050

I am using an accelerometer in my most recent device to capture gesture and orientation information, as the device itself has no traditional user interface. Since the device is running a node.js app to capture data and push it to a cloud service the first prototype required a quick solution to getting data from an MPU.

To capture data I am using a few node modules. In particular the cylon.js module, along with the cylon-i2c module. This allows accelerometer data to be easily used by the following code block

  .connection("edison", { adaptor: "intel-iot", i2cPort: 1})                  
  .device("accel", { driver: "mpu6050" })                                     
  .on("ready", function(bot) {                                      
    setInterval(function() {                                        
      bot.accel.getAcceleration(function(err, data) {
        //use data

The MPUs

The first prototype of this device is using a SparkFun Edison stack with the SparkFun I2C block connected to an MPU-6050, rather than the SparkFun Accelerometer block. At the time of this writing the cylon-i2c implementation of the lsm9ds0 driver is not working correctly with the SparkFun Accelerometer block, so I went the I2C route. The second an perhaps more important reason I went the I2C route is that MPU-6050 boards can be had for as low as $4, which is appealing for a low cost prototype.

I have a handful of MPUs I have tried and here is some info on them.

SparkFun MPU-6050 Breakout

This is great accelerometer breakout that works well with the Edison and Cylon module, but much less expensive options exist.

RioRand Triple Axis MPU-6050 Breakout

This is currently my go to accelerometer. It is relatively low priced at $11 and arrives in 2 days via Amazon Prime. These work well with both the Edison 3.3V boards, and the cylon i2c module. Unfortunately the default I2C address for this board is 0x69, instead of the more common 0x68 (used by the cylon mpu6050 driver) so you will need to solder the AD0 jumper plate on the top of the board.

Kootek GY-521 MPU-6050 MPU6050 Module

At $4 with free shipping these look like a great option. They are reported to work well with 3.3V VCC. The down side is very slow delivery via the slow boat. I have a handful on order, I will provide an update when they arrive.

GY-521 6DOF MPU6050 Module

At a little over $5 with free shipping this seems like a great option, unfortunately the onboard voltage regulator in the GY-521 is designed for the Arduino 5V VCC and when used with a 3.3V VCC of the Edison blocks results in too low power on the I2C SDA/SCL pins to register as proper high and low voltage values. It is possible to give the board a separate 5V VCC supply, but that just seems overly complicated for the prototype device. Another feature of this board is the breakout of AD0 into a pin, allowing easy switching between I2C 0x68 and 0x69 addresses using either a ground or VCC connection.

Connecting the MPU

For the first prototype I am using SparkFun Edison blocks, as I have a a few sets of these interchangeable blocks that are quick to assemble into a prototype. In this case I am using the SparkFun I2C block with an Edison. This block allows the Edison to be snapped onto the block, and the MPU-6050 board to be connected with 4 jumpers (VCC, GND, SDA, SCL).

Checking I2C Address

Most MPU-6050 boards will have an I2C address of 0x68, but if you choose a different MPU and it isn’t working with Cylon, the first thing to check will be whether the address is 0x68. The error message from Cylon will be a “RangeError: Trying to access beyond buffer length” for most errors where the MPU is not connected properly. To check the address use the following command when the MPU is connected via I2C.

i2cdetect -y -r 1

The result will look something like:

     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
00:          -- -- -- -- -- -- -- -- -- -- -- -- -- 
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
60: -- -- -- -- -- -- -- -- 68 -- -- -- -- -- -- -- 
70: -- -- -- -- -- -- -- --

You will see either a 68 or a 69 if the MPU-6050 is connected properly. If the address displayed is 69, you will need to change the address to 68 using the technique recommended for your board (AD0 jumper). You may see other numbers in the results if you have other I2C components included in your assembled device, but if you are using an MPU-6050 and it is connected correctly either a 68 or a 69 should appear in the i2cdetect results.

I won’t get into calibration or gesture recognition in this post, but will try to post more on MPU calibration, gesture recognition, etc in future posts. Given not all MPU-6050 breakouts work with the Edison because of their compatibility with 5V Arduino boards I wanted to post the notes of my experience with a few of them.


I have been building a few prototype devices with the following parts:

The device runs a node.js app that handles configuration and also posting data to a web service running in the cloud. Each user has an account and can have 1 or more devices. I won’t get into the purpose of the device here (or a few more components it has) but the device is working for its intended early prototyping purpose.

I have a drawer full of SparkFun Edison blocks, and often use them with an Edison for the first prototype of a device because it is such a powerful prototyping platform if you know Linux well. They Sparkfun boards are rather expensive, but so quick to use for rapid prototyping that I tend to always start with them. They also integrate well with various node libs including cylon and nodered.

But when it is time to build more than a few prototype units, cost does start to matter. Replacing the Sparkfun boards with a PCB approach is the next obvious step to lowering cost and customizing the device, but in this latest device the Edison platform itself is too expensive to create the devices at the price point I am targeting. It is the perfect physical size, but the price is too high.

After some analysis I have decided to try to reproduce the behavior of the current device using an ESP8266 instead of the Edison. I ordered some very inexpensive ESP8266 that are coming via the slow boat, but in the mean time my Sparkfun ESP8266 Thing arrived. It is a breakout board featuring the ESP8266.

I hope to get time over the next week to dive into coding the ESP8266, but if anyone has previously hooked up an MPU-6050 to an 8266 I would love to hear about your experiences and any issues, etc.

Edison Wi-Fi Configuration

I built a handful of prototype devices using Intel Edison boards to hand out to testers, but one challenge is each tester will bring the devices to their own Wi-Fi environment (home, work, etc). The default method for configuring an Edison is to use a console and the command line configuration tool to add a Wi-Fi access point.

configure_edison --wifi

The configure_edison app will scan for Wi-Fi networks and provide a list of networks for the user to pick from, and then prompt the user for the access point password. Since my headless IoT device has no traditional interface, let alone terminal interface this posed a problem. I needed a way for users to configure the device for new Wi-Fi networks as they were encountered, and make it accessible using a web page presented by the Edison. I will post the code once I have it completed and tested with users but for a quick hint the trick is to allow the running node.js app to switch the device between access point mode and client mode so if no network is available the device becomes an access point allowing the user to use any Wi-Fi enabled device to connect with it. Once connected the user can use a standard web browser to update the configuration to include the new Wi-Fi network they are intending to use.


The Edison uses the wpa_supplicant service to manage the client-mode Wi-Fi. The wpa_supplicant configuration file is located at: /etc/wpa_supplicant/wpa_supplicant.conf

Wi-Fi networks are added and removed by updating this configuration file. Se an example configuration below.

config_methods=virtual_push_button virtual_display push_button keypad

  pairwise=CCMP TKIP
  group=CCMP TKIP WEP104 WEP40

  pairwise=CCMP TKIP
  group=CCMP TKIP WEP104 WEP40

As you can see I have added two networks to the configuration, and given the network associated with my phone (in personal hotspot mode) a lower priority so it will be a fallback only. Note: you can change the name of your iPhone (and thus its personal hotspot) using itunes, and you can find the hotspot password in the hotspot settings on the iphone.

You can also add support for connecting to any open network (at your own risk) with an empty network statement


If the network you are connecting to has a hidden ssid then you need to add scan_ssid=1 to the configuration description. Because scan_ssid=0 is the default setting and is used for a broadcast ssid it can be omitted from the configuration of networks using a broadcast ssid.

  pairwise=CCMP TKIP
  group=CCMP TKIP WEP104 WEP40

Switching to AP mode and back

The Edison comes pre-configured for AP mode but if you are curious about changing the settings the configuration file can be found at /etc/hostapd/hostapd.conf. The other key networking file that should require no changes for this configuration is /etc/network/interfaces.

In the case when no configured network is available it is possible to connect a gesture (my device has an mpu-6050) to force the device into AP mode so it can get information from the user about how to connect to a new local network. The gesture observer thread can inform the node app when the preconditions of an AP mode switch should occur, the node app can then switch the Wi-Fi network temporarily to AP mode.

This is accomplished by stoping the wpa_supplicant service and starting the APN services using these two system commands that can be executed in exec() or spawn() calls.

systemctl stop wpa_supplicant
systemctl start hostapd

Adding a network

Now the device is in AP mode and the user can connect to the device by selecting it from the list of available networks, and go to the device confguration page for information about available networks and choose one to connect to. I won’t get into the scanning now but you can look here for more info on using _wpa_cli scan__ and wpa scan_results for getting info on available networks.

Once the user chooses a network and provides a password you can configure the device to use the network. My preference is to add the network and a config entry in the wpa_supplicant.conf file so the network can be used again in the future, but you can also use the wpa_cli to configure the network directly. Just use the format shown above to append your entry to the file.

Switch back to Wi-Fi client mode to connect to the newly added network.

wpa_cli reconfigure
systemctl stop hostapd
systemctl start wpa_supplicant

I will add my code for the entire process to a public gist when I have fully tested it out, and update this post.

Popup Workbench

We are down to one car, as we can walk/bike to about anything we could possibly need including caltrain and light rail. So the garage is now empty of cars, and filled with toys. While playing ping pong one day I decided a beverage table would be nice in the garage, but something that could also serve as a work surface in a pinch. Something to put some tools on, etc. I wanted it to be something that could be folded out of the way when not needed, and something that didn’t cost a lot since I wasn’t sure if it would really prove useful. Sort of a prototype 1 of a collapsable work surface concept.

I had some left over bamboo flooring from an old home improvement project that I thought would make a great table top, and I always have a few sheets of plywood around. All I was missing was the folding legs. After some searching I found some Folding Shelf Bench Brackets. I ordered 2 and installed them into a couple of wall studs in the garage and mounted a plywood top. I then cut and glued the strand bamboo flooring to the top to make a nice hard surface.

For a true folding workbench something like this looks very cool. If I decide I need something larger and more heavy duty I may go that route, but I have other benches already. I was looking for something that could add another table/work surface in a pinch in that particular location in the garage.

Now I also have a nice place to put cold drinks during ping pong matches.

Revisiting Buyer's Agent app using React.js

In a past post I showed a Mobile Real Estate App that was built with Polymer. This time around I will revisit the app but instead use react.js. The Mobile Buyer’s Agent is a simple web based application used to demonstrate a basic React.js mobile web app.The goal is to allows a real estate buyer’s agent to deliver a personalized mobile app experience to their clients by adding data to a Google spreadsheet. The agent updates a Google spreadsheet, and the web app loads its data from the spreadsheet.

This is a demonstration of using a shared Google Spreadsheet as the data source for a simple web based application. By using and React.js it is extremely easy to create a web application like the Mobile Buyer’s Agent.

The Real Estate Shopper List Google spreadsheet contains properties the agent wishes to present in the app. The neighborhood column is associated with the dropdown box, and allows a simple grouping/categorization of properties. The agent also provides other features and details associated with the properties.

Note: if you duplicate the example spreadsheet you must remember to publish it so it can be accessed by the Mobile Buyer’s Agent app. If you get an error it is likely you forgotto publish the spreadsheet. To publish a spreadsheet while viewing it, use the file menu on Google Docs and choose “publish to the web”, and follow the instructions.

Trying your own spreadsheet

If you publish your own copy of the spreadsheet you can easily substitute it in the app with a simple url parameter called sheetid.

For example if the link your are given when you plublish your spreadsheet is

Then your sheetid is 1kv5haqhS8bUY_6IoJ6KBY5j42pN2WsY_wscDZSHb_m8, and you can use it in this app by using a url with sheetid parameter as shown below:

This will substitue your spreadsheet for the default spreadsheet used in the app.

For info on the code take a look at the README document.

Setting Up a New Intel Edison

The Edison is a tiny and amazing computer, and ideal prototyping tool for wearable and IoT experiments. Here are the steps I am currently following to set up the Edison.

Flashing the Edison

Like many developers I have Mac, Windows, and Linux laptops but I find that Linux is the best environment for flashing the Edison, even though I do most development on my Mac. I came to this conclusion after trying to recover an Edison with a lost password, the only platform that worked was Linux.

The first step is flashing the Edison. Follow Flashing Edison Linux. You can also try Flashing Edison Mac.

The only change I would recommend is to create a folder that contains the Edison images, and then unzip the downloaded folder into a sub directory named after the build number. Over time you may find yourself flashing to older or newer images based on the project needs.

Setting up WiFi

Sparkfun offers a great guide for Setting up WiFi on the Edison. This takes only a few minutes and even if you don’t plan to use WiFi in your projects it makes working with the Edison easier because you can use SCP and SSH to connect with the Edison over the network.

Connect to Edison

For OSX or Linux the best way to connect to the Edison is via SSH. On OSX you can use the name you gave the Edison in the step above. For example ssh root@edison2.local where edison2 is the name you gave your Edison. On Linux you will use the Edison’s IP address, for example ssh root@

Using Emacs

If you are an Emacs user then once WiFi is setup you can use Emacs Tramp to work with files on the Edison. Just use C-x C-f as usual, but instead of a directory use root@edison2.local or use the ip address for Linux.

Emacs will present a directory of files on the Edison that you can open, or just keep typing the name for auto suggest feature. For example root@edison2.local/home/root/

Setup Bluetooth

Bluetooth is available in the Edison, but in the default configuration is not enabled at boot. If you are using Bluetooth you will likely want to enable it on every reboot or power cycle.

Enable Bluetooth at Boot

Use the systemctl command to cause Bluetooth to start automatically

 systemctl enable bluetooth

Create a BT startup script

Create a script file with the following five lines (/home/root/

 /usr/sbin/rfkill unblock bluetooth
 /usr/bin/hciconfig hci0 up
 /usr/bin/hciconfig hci0 piscan
 /usr/bin/hciconfig hic0 sspmode 0

Make the script executable

 chmod +x /home/root/

Create a new service file (/lib/systemd/system/btup.service).


Enable the service

 systemctl enable /lib/systemd/system/btup.service

Reboot the Edison


Create a Backup

Now is a good time to create a backup of the Edison that can be recovered if you need to return to a clean install. For example you may want to update nodejs, or install node modules, or even other drivers that may cause an issue you want to start over from.

Place a MicroSD card with at least 4GB of available space into the MicroSD slot on the dev kit board where the Edison is installed. Backup the Edison to an image file on the MicroSD. In the example below it is named edison2_backup.img. Make sure the file name has a .img extension. If you have a large MicroSD card you can store multiple backup images from multiple Edisons, making it quick and easy to recover each of them. It is wise to consider a consistent naming system.

 dd if=/dev/mmcblk0 of=/media/sdcard/edison2_bk.img

Restoring an Edison from Backup

If you need to restore the Edison from backup just reverse the process

 dd if=/media/sdcard/edison2_bk.img of=/dev/mmcblk0

Photo Caption Challenge - using Facebook Login, S3, and DynamoDb in browser app

One of the challenges of building small mobile web apps without a traditional back-end server is storing global state in a secure way. In my exploration of ways to store state I decided to build a very simple multi-player social app that allows players to participate in a simple photo challenge game. The game author specifies a photo caption and then invites friends to add photo responses that most creatively match the caption. The second feature is to allow people to vote on their favorite photo responses.

Such a game would typically require a server to support a few key behaviors:

  • player login: is needed to connect players with their uploaded photos, and also to limit their votes so as to keep voting fair.
  • photo storage: photo upload and storage is needed to store the photos so they can be displayed when the page is loaded. In addition a back-end service is typically used to re-size uploaded images before storing them to reduce storage costs.
  • global state: is generally provided by a database that stores information such as: which players have uploaded photos, and where the corresponding photos are located.

There are many challenges to running a back-end server to support an app, including configuration, maintenance, and security. In the ideal case one could build all sorts of small fun apps without having to manage any such servers. With the Photo Caption Challenge app I explored using the following services instead of running an app server.

  • player login: I used Facebook for player login as a way to differentiate players, and connect ids to votes and photos.
  • photo storage: I used Amazon S3 for storing photos uploaded by players, and used canvas and canvas.toBlob() (using JavaScript Canvas to Blob polyfill) to re-size images and store them in a blob for upload to S3. Thus all image re-sizing is done in the client.
  • global state: I used Amazon DynamoDB to provide state via a table that stores information about photo entries and votes.

I also used the Amazon IAM is the way to limit privileges from the client app to the data services (S3 and DynamoDB). For example you want the user to have write/delete access to only their information in the data services, but client API calls to the server can be manipulated, thus authentication information is critical to limiting privileges in accessing the data services.

IAM policies can specify an identity provider like Facebook to make sure to limit access based on current session identity information, and not the API request data. For example you can configure an IAM policy for S3 that secures S3 bucket privileges so that sub-folder privileges are connected to user identity. In the case of “Photo Challenge” the policy states any logged in Facebook user running the Photo Challenges app will be able to view photos in any sub-folder, but only upload, modify, or delete items that are in a folder that matches their identity provider’s assigned userid. It also states that any user can create a folder in the bucket as long as the folder name matches their identity provider’s assigned userid.

The Amazon IAM policy for DynamoDB works similarly. Any logged in Facebook user running the Photo Challenges app will be able to query the DB index for the current list of photo entries, but can only add/delete records that have a userId value that matches their identity provider’s assigned userid. Thus a user can’t spoof who added the record, it is connected to their userId or it is rejected by the IAM policy assigned to the DynamoDB table. For more information see Fine-Grained Access Control for DynamoDB.


In Mobile Real Estate App and Spreadsheet Driven Web Apps I described a technique for using a Google Spreadsheet to provide web application data, but this works best when the application data is read only. For an app that requires both read, write, and query transactions, a database like DynamoDB is a great solution.

Like many examples on this blog, I built this app using because poggs are incredibly flexible and require zero configuration. Use this app at or if you have a poggr account you can clone this pogg and use its configuration tool to set up Facebook, S3, IAM, and DynamoDB and have your version of the game running in less than 5 minutes. If you don’t have an account you can still check out the pogg’s README to learn more about how it was build and view the source documents.

Mobile Real Estate App - Version 1

I promised a few examples of spreadsheet driven apps. You may remember the Hipster List was the first example. These are simple web apps that are initialized using data from a Google Spreadsheet once the user loads them in a browser. Using spreadsheets to keep app information current is easy for anyone. There is even a way for users to point the app at their own Google Spreadsheet if the app developer wants to turn feature that on.

The next example of a spreadsheet driven app (below) is the Mobile Buyer’s Agent app. This may take a little time to load because it is an experiment, and thus not using a vulcanized Polymer library, so it is importing lots of individual library documents. Be patient and once cached in your browser it will be fast.

The idea is to create a mobile web app that can be used by buyers as they shop for a home. Once again the data is maintained in a Google spreadsheet, this time by the buyer’s agent. The agent can add houses, home information, and notes to the spreadsheet and the buyer can use the app to view the information as they shop. This is an easy way for an agent to personalize their client experience.

Take a look at the spreadsheet to see how information is organized. It allows the agent to add personalized title and notes to each house.

The README document provides more details on how the app was built. Or try the app here. I will likely provide a few updates to this app in the near future to make it a bit more interesting, but I though the first version showed a few nice features, and how to build them.

d3 charts - wrapping 'NVD3 Charts' in a web component

In my continued experiments with Polymer, I created a web component that wraps NVD3 - a reusable chart library for d3.js. As part of the activity I ported all of the NVD3 example charts to a web component I am calling __. The component is contained in a pogg on, as this is where I do my experimenting and it allows me to code and serve the project documents in the one place.

The above chart is an iframe to this document The actual element tag used is as follows:

   css="/pg1GXbi9MBx:dxkNM7ZicfBe::53" >
 </goddip-charts >

To view the uncompiled and unminified source see (html document source, data document source, and style document source).

The best way to learn about the __ component is to take a look at its README document. This describes how to use each of the charts, reference data, add styling, etc. You can always view the component source. If you have a _poggr.com_ account you can view, clone, and edit _goddip-charts_ using the poggr project UI.

Fun with Literate CoffeeScript

As an emacs/org-mode/babel user I have always been fascinated with the potential of literate programming and combining inline code in my notes. I have many org-mode documents that interactively execute code for various tasks and procedures. These tasks includes certain maintenance activities, or destructive operations I don’t want to get wrong. I have an entire org document devoted to db maintenance, filled with Ruby code to execute complicated db queries and operations. It is nice to see the example code inline in my notes, and be able to modify the code and execute it directly in my notes. This works especially well for checklist where calculations or actions are called for. You might even say org-mode was one inspiration for building; creating a browser based tool that is simple, flexible, and powerful for creating interactive and compelling documents that work in any web browser.

The potential of browser-based literate programming is why I find the idea of Literate CoffeeScript facinating. It is not just the idea of documenting code or even the idea of describing code in a blog post. It is the idea of creating flexible and effective browser based task and tool documents. The power in these types of documents is you see the code you are executing, which is extremely useful for programmer’s notes. It seems literate CoffeeScript might have something to say about how to create browser-based interactive notes that include inline code, like emacs/org-mode/babel has done for emacs users.

Since supports compiling CoffeeScript into JavaScript I decided to turn on literate CoffeeScript and give it a go to see if this is a legitimate way to combine code and blogging in a single pogg document.

Poggr CoffeeScript Compilation

The way poggr works is that when you save a CoffeeScript document poggr keeps both source code and compiled JavaScript code. Just like when you save a markdown document poggr saves both the source markdown and the compiled html. When a document is requested using a poggid in an http request, poggr will deliver the compiled code unless a query parameter is used to request source. This works out quite well in most cases, since the compiled version is what browsers are expecting (html, css, JavaScript). This model allows poggr to support other markup and languages like less, scss, yaml, etc to work similarly.

LitCoffeeScript is unique in that compilation produces two documents (markdown -> html) and (CoffeeScript -> JavaScript). Thus, one challenge is knowing whether a document request is for the html or JavaScript version. I felt compelled enough to experiment that I added a test case where adding a .js extention to a poggid will return the JavaScript, otherwise it will return the compiled html version of the document.

<script src="//">

I wanted to pick something fun to experiment with so I chose a game originally created by Marc-André Cournoyer. in his game.litcoffee gist.

You can see my version of the literate CoffeeScript post in action here. What you will notice it the game is running as part of the post, and all the code is also embedded in the post. This may look like a normal code example post, but if you look at the source code you will see at the end of the source document that the post actually loads the js version of itself. So by saving a literate CoffeeScript document you automatically get a blog post; in addition all of the fenced CoffeeScript code is compiled into a JavaScript document. Any changed inline code is re-compiled into an updated JavaScript document with each save. Mind Blown right!

I can’t see it replacing my emacs/org/babel workflow yet, but it certainly opens some possibilities for having a set of private online notes, experiments, and tools I can call up in any browser to edit and execute. One down-side is while emacs is mode-less in that editing and execution happen together, the browser model is built for view-only. Poggr is built on browser-based document editing, but viewing the rendered results is still a separate action. Although it is not exactly the same emacs/org-mode, there are cases where it is actually better. Emacs does not excel where rich visualization and rendering are beneficial, this is what the browser does best.

When I get a chance I will port a few of my org-mode notes over to literate CoffeeScript documents on poggr and make a note here when they are up.

Spreadsheet Driven Web Apps

Using Google spreadsheets is a great way for a team to collaborate on a data set but it leaves a bit to be desired on presentation of the data. To that end I will be creating a series of fun examples showing how to build small interactive apps that utilize Google Docs and Polymer web components to quickly bring data to life. In this series I will be using a Google spreadsheet as the data source, but other data sources are possible, and I will get to those as well in future posts.

The first example is Hipster List, an app that shows cool places to visit in various cities. Check out the README document for details on how this app is put together.

A little convention is used to make it work. Namely, I use a Hipster Hot Spots Google spreadsheet, where each city’s data is represented by a tab in the spreadsheet. There is also a key tab that provides a list of all the cities in the spreadsheet and the tab id (gid) for each city’s data. The app will load its data from the spreadsheet and populate the city drop-down list of hot spots, and display a map with markers for each hot spot. This was a fun first example, remember to checkout the readme document for code and explanation.

Note: I enabled url fragment parameters so you can easily point the app at your own copy of the spreadsheet for testing. See the readme document for the how-to instructions. Feel free to copy the spreadsheet and try out the app with your own list of cities and hot spots.

Separating code and data is always beneficial, but there is something cool about connecting an app to a Google spreadsheet. There are many spreadsheet users who would like to have an app to visualize their data, but may not be up to the coding challenge yet. I think many small useful apps could be built this way; I will pick a few to build in the next few weeks and discuss them here. I am using the service for the example, which is a service I built just for these types of small quick apps that can rely on an external data service. It is basically working to merge interactive content creation and blogging into a single service.

Leave me a comment if you have an small spreadsheet driven app you would like me to build. If it seems reasonable I may add it to the list.

CoreData.SQLDebug for RubyMotion

It is sometimes handy to turn on CoreData.SQLDebug in the simulator when debugging a Core Data issue. I have found the output to be very useful in finding the hard to find little bugs that pop-up between restkit and core data. It can also help find performance issues with the database. Unfortunately there isn’t any documentation for how to do this in RubyMotion. I found one solution that works to a degree. It requires installing the ios_sim app and forcing the simulator into CoreData.SQLDebug mode after the rubymotion build.

You will need to install ios_sim

$ brew install ios-sim

Then add the following two line as the last lines in your RubyMotion rakefile

# Be sure to substitute your app name and make sure you are using
# the correct path to the app based on simulator version.
ios_sim = `which ios-sim`.strip
sh "#{ios_sim} launch build/iPhoneSimulator-6.1-Development/ --args 1"

This will open the simulator in CoreData.SQLDebug mode, and log debug information to the terminal.

Getting RKLogConfigureByName working in RubyMotion

Just a quick note, I was getting an undefined constant error for RKLogConfigureByName, the standard way of setting up logging in RestKit. It seems that the #define statements in the /vendor/Pods/RestKit/Code/Support/RKLog.h file are not getting picked up. I am using the pod and loading with RubyMotion pod support, so Iåm not sure what the issue is. I will need to investigate further but this quick workaround works, just call the lower-level method mapped via the #define. For example instead of RKLogConfigureByName use RKlcl_configure_by_name. I also list all the RKlcl_v constants to use instead of the RKLogLevel constants. I also included an example of how they are used, in this case I have put the setup in a method, and it gets called from the the standard didFinishLaunchingWithOption application block.

def init_restkit_logging
#define RKLogLevelOff -> RKlcl_vOff
#define RKLogLevelCritical -> RKlcl_vCritical
#define RKLogLevelError -> RKlcl_vError
#define RKLogLevelWarning -> RKlcl_vWarning
#define RKLogLevelInfo -> RKlcl_vInfo
#define RKLogLevelDebug -> RKlcl_vDebug
#define RKLogLevelTrace -> RKlcl_vTrace
# "restkit" "RestKit"
# "" "RestKit/Network"
# "" "RestKit/Network/Cache"
# "" "RestKit/Network/Queue"
# "" "RestKit/Network/Reachability"
# "restkit.object_mapping" "RestKit/ObjectMapping"
# "restkit.core_data" "RestKit/CoreData"
# "restkit.core_data.cache" "RestKit/CoreData/Cache"
# "restkit.core_data.search_engine" "RestKit/CoreData/SearchEngine"
# "" "RestKit/Support"
# "" "RestKit/Support/Parsers"
# "restkit.three20" "RestKit/Three20"
# "restkit.ui" "RestKit/UI"
# "restkit.testing" "RestKit/Testing"
# "app" "App"
RKlcl_configure_by_name("Restkit", RKlcl_vDebug)
RKlcl_configure_by_name("App", RKlcl_vDebug)
RKlcl_configure_by_name("RestKit/Network*", RKlcl_vTrace)
RKlcl_configure_by_name("RestKit/ObjectMapping", RKlcl_vTrace)

nvALT and Emacs

In a previous post wiki-searchable-notes I mentioned that I was using nvALT for note taking. nvALT is a very simple way to create and search notes and store them in flat files that can be used by other tools. One use is publishing to a github wiki, today I will discuss another.

I am an Emacs user and often found myself dropping out of emacs to find a note I needed in nvALT. I went looking for the best way to index and access my nvALT notes inside Emacs, and found the very cool emacs script called Deft that works with EMacs Markdown Mode to create the equivalent of nvALT inside of emacs. It can be configured to work with the nvALT repository so they work well together.

A few pointers…

  • If you use markdown in nvALT as I do, follow the instructions to install markdown-mode via git clone.
  • Follow the instructions to install Deft via git clone. It is an active repository, so clone makes keeping up-to-date easy. Also update init.el to require the deft.el script.
  • For markdown and nvALT using the flat file config (see wiki-searchable-notes for flat file config) you need to add a few additional expressions in init.el. Add these four lines as discussed on the deft documentation. (setq deft-extension "md") (setq deft-directory "~/Development/wikis/") (setq deft-text-mode 'markdown-mode) (setq deft-use-filename-as-title t)
  • Follow the instructions to map a keyboard shortcut to open deft. I use H-d (see my emacs hyper-key post ) but a simple function key mapping would be. (global-set-key [f8] 'deft)
  • Create a symlink from ~/.deft to your nvALT notes directory, this is shown in the nvALT preferences under the notes tab. See example below. ln -s ~/Documents/notes/ .deft When you eval init.el or restart emacs you should be set. Fire up Deft and the UI will operate just like nvALT, only it works in an Emacs buffer!!

Emacs Experimental Hyper-Key Mappings

In a previous post Remapping My Caps Lock Key I mentioned that I remapped my caps-lock key to escape, but also created a “hyper-key” (ctrl-shift-cmd-opt) when the caps-lock key is held down. This opens up a keyboard worth of new shortcuts for emacs. Here are a few I have been playing with for the past few days. An alternative key mapping would be to map the hyper key to holding down the tab key, if you already have the caps lock key mapped to control, and thus muscle memory might preclude this mapping from working for you.

H is the remapped caps-lock HyperKey from my earlier post, which translates as C-M-S-s in the emacs init.el key-mappings. I include an init.el excerpt at the end of the post for all of these mappings.

  • (H-l) This will mark the entire current line, from any position on the line. Using the arrow keys will extent the selection one line at a time either up or down.
  • (H-f) This invokes text expansion for code completion, I do this a lot so I wanted it to be very comfortable.
  • (H-3) This invokes the comment/uncomment function on a region, ruby comment is the # so I thought I would try this binding.
  • (H-Right Arrow) This opens a new window to the right of the current window, I do this often enough I wanted it to be quick
  • (H-Left Arrow) This closes the current window, sort of the opposite of Right arrow.
  • (H-Down Arrow) This opens a new window below the current window
  • (H-p) In the current window switch to the previous buffer
  • (H-n) In the current window switch to the next buffer
  • (H-delete) Kill this buffer
  • (H-w) Quick copy line, pressing multiple times adds more lines to the copy
  • (H-k) Quick cut line, pressing multiple times adds more lines to the cut
  • (H-c) Copy region into register (prompts for register number)
  • (H-v) Paste from register (prompts for register number)
  • (H-spacebar) Open a popup shell in directory of current buffer.
  • (H-e) Eval buffer, mostly used to eval init.el after tweaks

I will likely be tweaking more in the upcoming weeks as I experiment with key mappings, I will post an update after I get a chance to work with the hyper-key for a while, and settle on a favorite set of key-mappings. See the excerpt from my init.el below.

(defun quick-copy-line ()
"Copy the whole line that point is on and move to the beginning of the next line.
Consecutive calls to this command append each line to the
(let ((beg (line-beginning-position 1))
(end (line-beginning-position 2)))
(if (eq last-command 'quick-copy-line)
(kill-append (buffer-substring beg end) (< end beg))
(kill-new (buffer-substring beg end))))
(beginning-of-line 2))
(defun quick-cut-line ()
"Cut the whole line that point is on. Consecutive calls to this command append each line to the kill-ring."
(let ((beg (line-beginning-position 1))
(end (line-beginning-position 2)))
(if (eq last-command 'quick-cut-line)
(kill-append (buffer-substring beg end) (< end beg))
(kill-new (buffer-substring beg end)))
(delete-region beg end))
(beginning-of-line 1)
(setq this-command 'quick-cut-line))
(transient-mark-mode 1)
(defun select-current-line ()
"Select the current line"
(end-of-line) ; move to end of line
(set-mark (line-beginning-position)))
(define-key help-map "d" 'docsetutil-search) ; C-h d
(defvar th-shell-popup-buffer nil)
(defun th-shell-popup ()
"Toggle a shell popup buffer with the current file's directory as cwd."
(unless (buffer-live-p th-shell-popup-buffer)
(save-window-excursion (shell "*Popup Shell*"))
(setq th-shell-popup-buffer (get-buffer "*Popup Shell*")))
(let ((win (get-buffer-window th-shell-popup-buffer))
(dir (file-name-directory (or (buffer-file-name)
;; dired
;; use HOME
(if win
(quit-window nil win)
(pop-to-buffer th-shell-popup-buffer nil t)
(comint-send-string nil (concat "cd " dir "\n")))))
(global-set-key (kbd "C-M-S-s-l") 'select-current-line)
(global-set-key (kbd "C-M-S-s-f") 'hippie-expand)
(global-set-key (kbd "C-M-s-#") 'comment-or-uncomment-region)
(global-set-key (kbd "C-M-S-s-<left>") 'delete-window)
(global-set-key (kbd "C-M-S-s-<SPC>") 'th-shell-popup)
(global-set-key (kbd "C-M-S-s-p") 'switch-to-prev-buffer)
(global-set-key (kbd "C-M-S-s-n") 'switch-to-next-buffer)
(global-set-key (kbd "C-M-S-s-v") 'insert-register)
(global-set-key (kbd "C-M-S-s-c") 'copy-to-register)
(global-set-key (kbd "C-M-S-s-e") 'eval-buffer)
(global-set-key (kbd "C-M-S-s-<right>") 'split-window-right)
(global-set-key (kbd "C-M-S-s-<down>") 'split-window-below)
(global-set-key (kbd "C-M-S-s-<backspace>") 'kill-this-buffer)
(global-set-key (kbd "C-M-S-s-w") 'quick-copy-line)
(global-set-key (kbd "C-M-S-s-k") 'quick-cut-line)

Trying out Pixate - CSS for iOS app Development

Recently I have been using RubyMotion for iOS development; I really appreciate developing in Ruby, and prefer Emacs to Xcode. Compared to using interface builder, styling apps can be a challenge. It is possible to use RubyMotion with XIB files created in Xcode’s Interface Builder, but I have been trying to avoid this. I am striving for a more web-app like design and development workflow.

I have been using teacup, which takes a declarative approach to styling and uses a CSS-like DSL. Although I liked teacup, I had been anxiously awaiting the arrival of Pixate because of its support for CSS-based styling. Pixate became generally available this month, and I purchased a license. The license is $199, and although expensive, a small price compared to time saved if it works. Since I already do a lot of CSS work on the web side it seems like a nice way to leverage my CSS skills and experience. The Pixate team along with the RubyMotion team created a RubyMotion-Pixate gem that makes it easy to get Pixate working with RubyMotion.

After 2 days of coding I have my basic controllers in place as well as several TableViewControllers. I have used Pixate to style many of the elements. With Pixate you can style with four types of selectors:

  • element type selector - Select a control by element name
  • universal selector - Select any control
  • class selector - Select a control by class name
  • id selector - Select a control by ID

It also supports attribute selectors and pseudo classes. See the complete list for more information on selectors and styling.

One really nice feature is the ability to set up Pixate to dynamically change your app in the simulator when you update the CSS. This is an awesome feature. To set it up add these two PXStylesheet lines to your app_delegate.rb file near the end of the application method:

 def application(application, didFinishLaunchingWithOptions:launchOptions)
    PXStylesheet.styleSheetFromFilePath('path-to/default.css', withOrigin:0)
    PXStylesheet.currentApplicationStylesheet.monitorChanges = true  

I was only able to get it to work by providing the absolute path to the css file, so add your absolute path in place of path-to in the above method call. I will post if I figure out how to do a relative path, I hate putting in absolute paths.

Warning: I found that Pixate 1.0.2 does not work properly on the device if these two statements are left in the app delegate when compiling for the device. If your styles are not being picked up on the device this may be the reason. To get around this during development I put in a test for simulator using the Device.simulator? method in Bubblewrap,

 def setup_pixate_monitor 
   PXStylesheet.styleSheetFromFilePath('path-to/default.css', withOrigin:0)
   PXStylesheet.currentApplicationStylesheet.monitorChanges = true

Then include this conditional call:

 setup_pixate_monitor if Device.simulator?

So far Pixate has mostly worked as expected, but there was one odd issue. I had expected that I could create zero-sized frames and allow CSS to style them to the correct size. For example creating a new label object might look like this.

 @name_label = UILabel.alloc.initWithFrame(CGRectZero)
 @name_label.styleId = 'name_label'

CGRectZero, a CGRect constant, will set the frame to size [0,0][0,0]. Then the CSS style definition below should set the frame size correctly.

 #name_label { 
   top              :20px;
   left             :5px;
 	   width            :300px;
   height           :30px;  
   font-size        :16px;
   font-align       :center;  

I would expect the frame to be set to [5,20][300, 30] when the application is run. Instead the frame remains set to [0,0][0,0], so the text in the label is not displayed in the interface. This [0,0][0,0] frame size is confirmed with REPL using the tree command that comes with the sugarcube gem.

When I set the frame to a non-zero size when creating the UI object, then the CSS style is picked up and the frame size is set correctly by Pixate. Very odd, I am assuming this to be a bug, but maybe there was a reason to leave zero-sized frames unaltered by CSS. Typically CGRectZero frames are used to hide UI elements until they are ready to be used, or until the dimensions are known based on content. If a CSS selector matched zero-sized frames I suppose this could lead to some unexpected behavior for iOS developers accustom to zero-sized frames not being displayed until the specifically resize them in code.

In the end I created a new global constant

 CSSRect = [0, 0], [1, 0] 

and this allows the CSS to do its job. So

 @name_label = UILabel.alloc.initWithFrame(CSSRect)
 @name_label.styleId = 'name_label'

allows me to create frames that are then altered to the correct size via CSS. I also found that using CGRectInfinite works as well. Basically it sets a huge rectangle but the CSS resizes it as expected.

The RubyMotion-Pixate gem also adds REPL support for changing the style via REPL. This is handy, but I find the dynamic updating via the CSS file to be easier to use.

The Pixate Engine consists of two core technologies: a 2D graphics engine and a CSS styling engine. So far my focus has been using the CSS styling engine. By using a styling rendering engine, design execution can be pushed to run-time. One of the benefits of this approach is the ability to dynamically modify the look of an app, which can be useful in user testing, including A/B testing. For this, Pixate allows CSS to be loaded via a URL, much like a web browser. I am sure there will be performance implications of this dynamic rendering approach, so this will also have to be explored as a cost versus the benefit of dynamic styling.

I really liked Colin Gray’s ideas around teacup, and the rubyesque way it integrated with rubymotion.

 @search = subview(UITextField, :search)

It would be interesting if this syntax could be used with Pixate versus the less elegant:

 @search = UITextField.alloc.initWithFrame(CSSRect)
 @search.styleId = 'search'

I have only just begun to use Pixate, there may be possibilities for making the calls a bit more elegant without writing too many helpers.

I will add more posts as I learn more.

The three c's

I really enjoyed this interview with Tony Fadell on the unique nature of Apple’s design process. The discussion about project abandonment percentages is incredibly important, and often overlooked in large companies. In many cases abandonment is a financial decision related to either real or opportunity costs associated with launching a product. People who have never worked for a large consumer products company likely have no idea how many products are cancelled just before launch because of the incredible cost in launching a product into the market.

Tony makes an amazing point about the toll such high cancellation rates have on employees at a company, and on the quality of the products the company ships. The inverse is that high commitment to ship products that pass key milestones leads to better employee commitment.

“When you’re in a culture that has a point of view, and drives to launch everything it does, you know you’re on the hook and you better bring your best game every time,” Fadell explained.

Tony contrasts his experience at Apple with his experience at Philips:

Fadell explained that a key and yet often overlooked difference between Apple and other tech companies is that Apple ships 99% of the products that pass certain internal milestones. By way of contrast, during Fadell’s tenure at Philips - where he was charged with overseeing the company’s audio strategy - the iPod guru noted that Philips would axe 9 projects out of 10, even if a particular product was about to ship.

I don’t think large companies have a metric for tracking the number and impact of cancelled projects. In my experience executive teams wanted to forget cancellations as quickly as possible and move on. They considered the cost to be in the past, and by having cancelled the project they had cut any ongoing cost. But as Tony points out, there are ongoing costs, just not costs that have their own column on a balance sheet or scorecard. In my experience it was clear … the impact of cancellations were cumulative and devastating.

The importance of commitment is actually one of the 3 c’s I use when evaluating a project: Clarity, Competency, and Commitment. Over the years I have found these to be the key pieces of early stage information that will best predict the success of a project. Tony’s pont about commitment is that it isn’t only about commitment to a project, it is about the culture of commitment in an organization. I like this point, and I imagine there is a corollary for organizational clarity and competency. Below are a few notes related to project level evaluation of the 3 c’s


Clarity is an evaluation of how clear the goals are for the product, and how well understood the product is.

For example:

  • A project to enhance a successful existing product with incremental features likely has very high clarity.
  • A project to move a successful product through a major transition will likely have medium clarity, but in some cases will have low clarity if the product manager and the team have different ideas about product direction.
  • A project to improve an unsuccessful product is usually medium to low clarity. If you are lucky you understand what went wrong, but lack of clarity is often the reason it failed in the first place.
  • A new product is usually low clarity, but if you have a great product manager it may be medium clarity to high clarity.
  • A new product in a new market is often low clarity and may even be disguised as medium to high clarity because the teams reviewing the product have little experience in the market. By this I mean the product brief will use language that sounds high clarity, but market experts would easily identify the brief as too vague. This is where competency and clarity overlap early in a project.

My first task was always to make sure there was a plan in place to address any clarity issues immediately. From my experience without such a plan and milestones for high clarity, teams often started to build the wrong product, or multiple wrong products. If the team cannot agree on what the product really is, it will certainly fail. New products could achieve medium to high clarity. The key step is to identify clarity as an issue and put a plan in place to provide good clarity early in the project. I have seen many product requirements documents that were very detailed, but no two team members would describe the same product when asked what the product was. Providing detail is not the same as providing clarity.


One of the other key issues in the success of a project is competency. In a large company design, and engineering resources tend to be plugged in to a project primarily based on their availability. There is an idea of a performance band with some people regularly performing better than others, but rarely a deep understanding of the individual competencies of team members. Having directed both engineering and design teams, and worked closely with product management for many years I have come to see that individual competencies play a key role in project success; a role that is rarely reflected in evaluations or performance rankings. Evaluations rarely measure competency. For an interesting take on the fallacy of skills in success see The Success Equation: Untangling Skill and Luck in Business, Sports, and Investing

Here I look for a match in competency for the product needs, but also for how well the team works in the particular product context. How much experience does this team have defining and launching a new product? Has the lead engineer designed anything at this scale before? Many projects fail because a key competency is lacking on the product team.


This is what Tony is referring to in his interview, how much commitment is there for this product? This refers to team commitment as well as executive commitment. In my experience, commitment issues fall into a few categories.

Market Issues

It is sometimes the case, especially in technology, where the market is moving so fast projects become obsolete before they are completed. This leads to high cancellation rates. These cases are about risk management, and understanding that the market evolution rate is a key issue. For example having a 24 month product cycle in a rapid innovation market may be taking on a lot of risk. If you can’t move faster, maybe find a market that better matches your organizational delivery capabilities.

Structural Commitment Issues

In some cases a company is trying to do too many things, and commitment is a structural issue. I suspect Tony’s characterization of Philips false into the structural definition. In these cases it is important to force prioritization and work with executives to understand that doing fewer things better will actually result in shipping not only better products, but more products. It can seem counter-intuitive, but I think Tony’s description above shows how this has been proven at Apple. Less SKU’s more volume.

Project Commitment Issues

I often found that when project comitment was low, it was low in very specific ways. Here are a few examples:

  • Low hanging fruit - Many projects came across my desk as the so-called low-hanging fruit project. These are projects that are so low cost and high value that they seem obviously high-commitment on the surface; they often originate in an executive review meeting. The main issue here is that no one questions them, so their clarity is usually quite low, and their commitment falsely high. Usually as clarity rises even a small amount, commitment collapses because the actual project could never deliver on the low hanging fruit mirage that came out of a thirty minute executive discussion.

  • The magic mirror - Another class of projects with commitment issues were the magic mirror projects. These are projects where whomever is looking at the projects sees what they want to see, and ignores everything else. These types of projects are the most dangerous because they are usually multi-headed beasts that are trying to simultaneously serve many masters. Their commitment is based in company politics and thus commitment can shift or disintegrate very quickly.

Given my team’s success was based solely on shipping successful products my most important task was usually at the early phase of projects, and mostly making sure that projects scored high on their combined CCC levels.

Parsing a simple markdown style list in Ragel

In an earlier post Simple state machine example, I provided an example of using the Ruby state_machine gem to create a state machine for handling a simple list of tasks. In this post I will provide a similar but not exactly compatible description of building a parser to read lists from a text file. In this example I use the markdown syntax for lists, where items can be placed hierarchically, thus removing the need for a separate “list” object.

I found the Ragel documentation to be excellent. The only issue is a lack of practical examples. Given the dearth of examples available, I though I would add my +1 example to help the cause. If you are serious about using Ragel I recommend reading the documentation start to finish quickly, then a second go through taking notes on key items like default machines, syntax, priorities, actions, etc before building a parser. Having a strong base will help tremendously when using examples.

There are three files involved in this solution to the list problem:

  • lists.txt: a data file that contains two lists for the parser to parse.
  • mdlist.rb: a ruby class that will call the parser and output the list returned from the parser.
  • mdlist_parser.rl: A file that will be used by Ragel to create a parser class definition (mdlist_parse.rb).

I added all three files to one gist, which is shown below. Below the lists.txt data file uses a markdown like syntax where hierarchy is expressed through indentation (4 spaces or a tab).

## Tasks
- Go to Whole Foods
- Go to produce section
- get oranges
maybe Mandarine and Valencia
- get avocados
- get squash
maybe buttercup if they have it
- Go to bakery section
- get bagels
- get 12 cupcakes
- Go to Dairy
- get milk
should be organic 2% if they have it
- Pay for items
## Tasks
- Write up a Ragel example for blog
- Create simple example for parsing lists
- Ragel code for a parser
Should provide support for parsing multiple task lists.
It should also support hierarchical task lists
- Create a simple ruby class that uses the parser
- post code as gists
- Write up a blog post describing the use of ragel in the example
- Post to blog
require 'rubygems'
require './mdlist_parser.rb'
class MDList
def initialize(filename)
contents =, 'r') { |f| }
lexer_lists ='\n',"\n"))
puts lexer_lists
lexer_lists.lists.each do |list|
puts "Tasks:"
list[:items].each do |item|
puts "-".rjust(4*item[:level]) + item[:title] + " : (" + item[:level].to_s + ")"
item[:description].split(/\r?\n/).each do |l|
puts " ".rjust(4*item[:level]) + l.strip
class MDListParser
attr_accessor :lists
machine test_lexer;
action MarkTaskStart {
task_start = fpc
lists_index += 1
@lists[lists_index] = {:items => []}
action MarkTaskTitleStart {
task_start = fpc
action MarkTaskDescriptionStart {
task_start = fpc
action IncrementTaskLevel {
task_level += 1
action TaskText {
if data[p]
item_index += 1
@lists[lists_index][:items] << { :type => task_item_type, :level => task_level, :title => data[task_start...p].pack('c*').strip, :description => ""}
task_level = 1
action TaskDescriptionText {
if data[p]
@lists[lists_index][:items][item_index][:description] = data[task_start...p].pack('c*').strip
task_level = 1
space_or_tab = " " | [\t];
indent_or_tab = " " | [\t];
task_header = "##" space_or_tab* "Tasks" space_or_tab* [\n];
task_char = (digit+ '.' >{task_item_type = :ordered}) | ('-' >{task_item_type = :unordered});
task_title = [^\n]+ [\n];
task_starter = indent_or_tab* @IncrementTaskLevel task_char;
task_description_line = ([^\n]+ - ^[##]) [\n];
task_description = (task_description_line - task_header)+;
#task_description = (task_description_line)+;
task_item = task_starter space_or_tab* (task_title >MarkTaskTitleStart %TaskText) (task_description* >MarkTaskDescriptionStart %TaskDescriptionText);
task = (task_header >MarkTaskStart) . task_item*;
main := |*
def initialize(data)
%% write data;
data = data.unpack("c*") if(data.is_a?(String))
eof = data.length
@lists = []
token_array = []
task_item_type = ""
task_level = 1
fpc = 0
fc = ""
%% write init;
%% write exec;

To create an app that supported operating on these lists you would need to parse the list and create objects that could be operated on. Perhaps adding checkboxes in a UI, or strike-through font when the item is marked complete.

In this example I am using Ragel, which uses a set of state machine definitions to generate a state machine. In this case I am using Ragel to generate a parser to parse lists similar to the ones shown in lists.txt. In Ragel you specify a Ruby class that uses a series of preprocessors (%%) that are processed by the Ragel library. Ragel will replace these blocks and preprocessor commands with ruby parser code and a parse table; resulting in a state machine for parsing the file. The documentation will describe all of the required preprocessor commands for Ruby. Ragel supports many languages and the preprocessor commands differ slightly for different languages. Check the documentation for meaning.

The bulk of the instructions for creating a parser are inside the %%{ }%% block. The block is made up of machine definitions and actions. Ragel state machines recognize byte sequences as regular expression machines do, but can also execute code at arbitrary points in the recognition of a regular language (actions). Here regular expressions are used to define a regular grammar, see type-3 in the Chomsky hierarchy.

Thus when you see the statement:

task_title =  [^\n]+ [\n]

this is defining a machine ([^\n]+ [\n]) and assigning it a name task_title. The Ragel documentation refers to the right side of the expression as a regular expression machine or machine, this is roughy equivalent to production rules in tradition grammar design. Using named expressions this way allows grammar rules to be built up recursively, much like non-terminals are used in traditional grammar definitions.

Thus an expression like:

task = (task_header >MarkTaskStart) . task_item*;

uses the rules task_header** and task_item** in the definition of the expression. Ragel expressions look unusual at first because they are both defining a grammar and embedding behavior (code). For example the above expression includes a reference to of a block of code MarkTaskStart that should be executed when the task_header machine is matched. These code blocks are called actions in Ragel. It can be useful to use a convention like all lowercase for rules, and CamelCase for actions to make the expressions easier to read.

Ragel defines a syntax for specifying when an action is to be called relative to state transitions between machines. For example before a transition, after a transition, or at the end of file, etc. The documentation is very good, though it is terse.

Name Syntax
entering action expr >action
finishing action expr @ action
all transitions action expr $ action
leaving actions expr % action

Ragel also allows you to embed error handling behavior using a similar mechanism.

Finally, one of the challenges of regular grammars is the requirement that they are DFA’s and thus need to be deterministic. Ragel provides a mechanism for including priorities in the case where multiple next states are possible; you can define which state will be taken. For more see the Ragel documentation on priorities and guarded expressions. The reason I suggested reading through the documentation prior to reading example grammars is that Ragel expressions can begin to look very confusing if you are not versed in the difference between the syntax associated with machines, actions, priorities and guards, since they all appear intermingled in a Ragel expression.

To create a parser for the mdlist_parser.rl file shown above use this command:

 ragel -R mdlist_parser.rl

This will create a parser written in ruby called mdlist_parser.rb that can be included into your Ruby program.

Now we need a simple Ruby program to use the parser, I am including this because I didn’t see a lot of examples for how to do this so wanted to add one here.

The simple ruby class defined in mdlist.rb will open the data file and read it in to a string, and pass the string to the parser. The parser will return a Ruby object that has a lists method that returns the list in a data structure. The above class will then output the list formatted to show the hierarchy. The list could easily be used to create a list object that includes the state machine from my earlier state machine post.

I will assume you have Ragel, installed, if not get it here. To see the parser in action you need all three files (mdlist_parser.rl, mdlist.rb, lists.txt) in the same directory and then take these steps:

  1. run the ragel parser: ragel -R mdlist_parser.rl
  2. run irb and enter the following into irb:

    • load “mdlist.rb”
    • list =“lists.txt”)

You should see the output of the puts statements displaying the lists data structure with information about the hierarchy of the list. It would be easy to replace the puts with a call to a method like add_item() from my state_machine example referenced earlier.

That’s it. Defining grammars and using parser generators can seem challenging at first, but once you get through a few examples and build a simple grammer it will become very simple, since the rules are really very simple. The language of grammar definition can be challenging at first, but just try to understand the concepts and don’t get too bogged down in the terminology. Ragel is a very powerful tool for any developer to have in their tool belt, especially if you are interested in building high performance APIs, it combines a powerful parser generator with an expressive syntax for generating powerful state machines. To fully understand this and other examples check out the Ragel documentation and tutorials listed below.

Also see this great Consuming Gherkin: One Byte at a Time video intro of Mike Sassak & Greg Hnatiuk discussing their experience using Ragel for the Cucumber parser.

Pattern problems vs logic problems

Suppose three men can paint three fences in three hours. How long would it take one man to paint one fence?

I ran across this interesting problem in “The Joy of x: A Guided Tour of Math, from One to Infinity,” a very accessible and interesting tour of mathematics.

It turns out most people quickly answer “one hour.” As Strogatz opines,

The words themselves nudge you that way. The drumbeat in the first sentence— three men, three fences, three hours— catches your attention by establishing a rhythm, so when the next sentence repeats the pattern with one man, one fence, __ hours, it’s hard to resist filling in the blank with “one.” The parallel construction suggests an answer that’s linguistically right but mathematically wrong.

The correct answer is three hours. It is obvious if you imagine each person painting their own fence for three hours. Remove two people and two fences and you are left with one person, still painting their one fence for three hours, as before.

What struck me about this problem is that it is an incredibly simple, concrete, and visual example of how our brains try to match patterns, but more importantly the side effect that occurs when a pattern is matched. Neuroscience studies suggest that dopamine (a neurotransmitter associated with pleasure) is released when we solve a problem, thus giving us a biological explanation for that wonderful feeling we get when we have solved a problem.

This made me wonder, does our brain perhaps release dopamine when we solve the faux pattern matching problem and tricks us into thinking we solved the actual logic problem? Thus we quickly blurt out the wrong answer. After all, we have spent a lifetime feeling the dopamine rush when we believe we have the answer to a problem. Strogatz’s observation about this particular word problem having two solutions (a pattern solution, and a logic solution) is very interesting, and is likely very related to a number of Cognitive Biases. It is perhaps valuable to think about this explicitly when considering information:

  • What is the pattern problem being suggested?
  • What is the logic problem being suggested?

And make sure you have the answer the right question when you feel that first burst of dopamine show up.

Creativity Booster: Get a dog.

It probably sounds specious, but I have found having a dog around has made me both more productive and more creative. The evidence for this claim is the number of daily messages I post to our team message board that start with the phrase “While I was out walking the dog I had this idea….”

Before getting a dog I would get sucked into a problem and become obsessed with solving it, the kind of linear obsession that leaves no room for creative leaps. What is needed is to allow the problem to marinate in my subconscious, to facilitate the unexpected synaptic connections that occur when you finally let your mind relax. The problem is, obsession with solving the problem makes this type of relaxed mind difficult and leaps of creativity less frequent. I am sure with practice one could recognize the symptoms and use some type of mediation exercise, but for me the answer is walking the dog. The pattern repeats regularly … I hit a nasty bug or design conundrum, get stuck, and then take the dog out for 15-20 minutes, and the answer suddenly presents itself.

For me, dog walking seems to engage the kind of subconscious pattern matching that provides the keys to unlock many problems. Wallas would have called this the incubation phase of creativity. I think of it as a cousin to Mihály Csíkszentmihályi’s concept of the flow mental state. This seems to be validated by Nardi’s work on the neuroscience of personality. Specifically, the brain imaging results where he describes the delta state in terms of Csíkszentmihályi’s flow, but adds that “also on occasion when we are copacetic, open to whatever comes next.” This is a perfect description of my mental state on a walk with the dog. I feel close to that feeling of flow, but not quite the same – an approximation. But it seems to do the trick. As a side note, Nardi’s brain imaging results of people watching TV shows up as black; similar to a deep non-dreaming sleep. So TV is not so good for creativity … just saying.

I don’t find that walking alone or with another person works as well. I wonder if it is the non-conversational interactions with the dog, just enough interaction to get me to stop focussing on the issue, but not so much that my mind is focussed on keeping up a conversation with someone else. Whatever the reason, it works; almost always presenting a promising new direction, if not an outright answer.

This is my muse, Archer, the retired racing greyhound.

RubyMotion iOS Apps

I wanted to make a quick note that I have been using RubyMotion the past few months. I don’t mind building natively in Objective-C but since I have been coding both the app and the server side I found switching between Objective-C and Ruby a bit frustrating. I really find Objective-C to be too verbose a syntax for my taste. I also prefer to code in emacs vs. the Xcode UI. Call me old fashioned, but I find I can work much faster when I can operate on the code directly, versus through an intermediary UI.

The second reason for switching to RubyMotion is the libraries that are being created, they make iOS development feel so comfortable to a Ruby developer. Three key examples are BubbleWrap, SugarcCube and Teacup.

The third reason is testing and debugging, I like that RubyMotion comes with an RSpec clone, this means I have the same testing framework on both app and server. I also love the interactive console, there is nothing like tweaking your app live from a console (REPL). I find I can debug a lot of the code from the console, but RubyMotion also supports GDB for the more serious debugging needs. I hadn’t used GDB in a few years but it came back to me pretty quickly once I started using it.

I also like the DSL approach of Teacup in styling RubyMotion iOS apps. I like that I can create style files much like I do with CSS and have my app UI built with the style information, makes changing style feel more natural to me as a web developer.

I have no doubt that there are many Objective-C developers who are extremely efficient in building apps, but it is always a challenge to become expert on multiple platforms. To become an expert iOS developer you need to become expert in the Cocoa libraries; the nice thing about RubyMotion is it allows you to learn the libraries within a familiar syntax if you are a ruby developer. It also allows you to create Ruby wrappers and generators that make developing for Cocoa feel more natural to a Ruby developer. Finally, since RubyMotion creates compiled native iOS apps, their is very little performance hit.

I have a backlog of notes that I will post when I get a chance; including my experiences with development, debugging, meta-programming, deploying via TestFlight, etc. I just wanted to give RubyMotion some praise from this Ruby developer, it has made developing iOS apps very similar to deploying ruby apps.

Lean API on Heroku

We have recently been working on an iOS app that requires a backend service. In this case I was looking for something leaner, simpler, and faster than Rails since it was only an API for a mobile app, no web front-end. I wanted it to be very lean and scalable so we could make it through early user testing without spending a lot on servers. Ok, ideally without spending anything on servers; basically how much could I squeeze out of one Heroku worker.

After some investigation of the typical light weight ruby frameworks (Sinatra, Merb, etc) I stumbled upon Grape, a ruby API micro-framework. Grape uses a very simple DSL for defining APIs for your Ruby objects. Grape runs on Goliath, which is a non-blocking Ruby web server framework that uses Ruby fibers to simplify the handling of asynchronous requests. Goliath runs on the popular EventMachine reactor. EventMachine is an event-driven Ruby library that works much like Node.js.

The Grape github page provides a great deal of information on getting started, and David Jones has a great example project on GitHub demonstrating how to deploy a grape API on Heroku.

The DSL is really simple and I was able to wrap some ruby objects in a day and deploy it on Heroku. Here is an snippet of what the DSL looks like.

require 'goliath'
require 'em-synchrony'
require 'em-synchrony/em-mongo'
require 'grape'
require './app/models/mission.rb'
require './app/models/player.rb'
module MyAppName
class API_v1 < Grape::API
prefix 'api'
version 'v1', :using => :header, :vendor => 'company_id' do
format :json
resource 'missions' do
# All mission API endpoints go here...
# ...
desc "Get a mission record using its id as key", {
:params => {
"id" => { :id => "Mission id.", :required => true }
get "/:id" do
error! 'Unauthorized', 401 unless env['HTTP_SECRETK'] == 'a secret key'
missions_json = env.missions_coll.find({'_id' => params[:id]})
error! 'Mission not found', 404 unless missions_json != []
mission = {|i| Mission.from_json(i)}.first
# map returns an array of 1 item, so get first as the mission object
# do something with the mission object here
# then return object to caller as json
resource 'players' do
# All player API endpoints go here...
# ...
desc "Get a player record using its id as key", {
:params => {
"id" => { :id => "Player id.", :required => true }
get "/:id" do
error! 'Unauthorized', 401 unless env['HTTP_SECRETK'] == 'a secret key'
players_json = env.players_coll.find({'_id' => params[:id]})
error! 'Player not found', 404 unless players_json != []
players = {|i| Player.from_json(i)}

As you can see the Grape framework supports API versioning, and the DSL provides a simple way to define API endpoints by defining resources and then specifying the HTTP requests (get, post, put, delete) for that resource. Any Rails developer should feel comfortable with the paths, params, and routes syntax in Grape.

In this code snippet I show part of the API definition for two resources (missions & players). This will mean the path for accessing these are /missions and /players. Because I specified prefix ‘api’ at the top of the file, the actual path becomes /api/missions and /api/players. So for example the get “/:id” would correspond to a get request of /api/players/7E781305-777F-4044-9770-C7995585F540 where the UUID is a player id and would be available in the params[:id] variable.

I should also note that even though these are simple get requests Grape will expect a header to be set for the secret key(secretk), and also require an Accept header with the version, vendor info, and content type (json). The easiest way to test your API will be to use an app like Postman that makes it easy to formulating requests, setting headers, from your Chrome browser. Postman also allows you to save requests, and re-run them.

I happen to be using Mongo for this, but Grape supports most major DBs. I am only showing two get methods, my full definition supports CRUD for these objects, as well as a few common queries of the db. The error checking of the request is fairly straightforward. I am checking for an API key, but this would be replaced with an API key lookup function to validate the requestor. It is easy to respond with specific errors as you can see.

The terse error!, unless syntax makes the error handling code very readable. The request handling for these two examples are simple: I query a mongo collection for an id, then map that response onto objects, and then convert the objects to json. This looks funny since it is basically json->object->json since mongo returns json, but there is more that happens in the object mapping; the json from the db and the json from the object are not the same.

By requiring mission.rb and player.rb at the top of the file, I pull in my Mission and Player classes so they can be used in the map operation. Try to ignore the lame .first operation, this was a bit of laziness in dealing with what is an array of one item resulting from the map operation. As with all Ruby, the output of the last operation is what is returned in the body of the response.

The DSL is very clean and makes API maintenance relatively easy.

A few other handy links:

Simple state machine example

I have been investigating using the ruby state_machine gem for a project. State machines can be very handy in simplifying code where objects move through various states. The state_machine gem embeds state machine behavior into any class that uses it. My first test was to create a simple todo list example. The todo list will include a main list that contains items and sublists. This allows a way to organize items easily into sublists.

A simple way to do this is to declare two classes List and Item and allow an object of class List to contain a list of Lists and a list of Items. This approach allows a flat list with many items, or a hierarchical list with top-level items, but also sub-lists that contain their own items.

In addition to lists and items, I want is to track whether I have completed all of the items in a list. In the case of a hierarchical list this means all items of sub-lists as well. Thus in addition to lists and items, we need to track whether items and lists are in progress or completed.

The next step is deciding on the states of the two object types. For my example, I decided: * a list will have an initial state of available, and will transition to state started when the first item on the list is completed. When all items and sublists are completed the list will move to the state completed. * an item will have an initial state of available and will transition to completed when the item is finished.

Finally I want to inform the user when: * an item is completed * a list is completed * the project is completed (all items and sublists are completed)

Here is a quick example of the code to meet these requirements:

require 'rubygems'
require 'state_machine'
class Item
attr_accessor :name, :description
state_machine :item_state, :initial => :available do
after_transition :available=> :completed, :do => :item_completed
event :finish do
transition [:available] => :completed
state :completed do
def initialize(item_name, item_description, parent = nil)
@name = item_name
@description = item_description
@parent_list = parent
super() # NOTE: This *must* be called, otherwise states won't get initialized
def item_completed
puts "finished item #{}"
if @parent_list
class List
attr_accessor :name, :description, :lists, :items
state_machine :list_state, :initial => :available do
after_transition :started=> :completed, :do => :list_completed
event :start do
transition [:available] => :started
event :finish do
transition [:started] => :completed
state :started do
# take any actions related to moving to started state.
state :completed do
# take any actions related to moving to completed state.
def initialize(list_name, list_description, parent = nil)
@name = list_name
@description = list_description
@lists = []
@items = []
@parent = parent
super() # NOTE: This *must* be called, otherwise states won't get initialized
def add_list(name, description)
@lists <<, description, self)
def add_item (name, description)
@items <<, description, self)
# Called by child item when item is completed. Allows check for
# all items completed.
def child_item_completed
# once the first item is completed consider this list started
if self.list_state == "available"
# if all items are completed move this list to completed state.
if{|i| i.item_state != "completed"}.empty?
def child_list_completed
# if this is a sublist let parent know this list is completed.
# else this is top level list and everything is completed.
if{|i| i.item_state != "completed"}.empty?
if{|l| l.list_state != "completed"}.empty?
def list_completed
if @parent
puts "congrats on completing list #{}"
puts "congrats on completing project #{}"

As you can see there is a rich environment for embedding behavior, including adding it in the state definitions, adding it using the before_transition method, and adding it using the after_transition method. You can also define methods inside the state definition so you can extend the functionality of a state.

Now if you load this example in IRB you can play with the lists and items like so:

 load "list_example.rb"
 list ="Groceries", "Get some groceries")
 wf = list.add_list("Whole Foods", "Get some groceries from Whole Foods")
 milk = list.add_item("Milk", "2% Milk")
 strawberries = wf.add_item("Strawberries", "Ripe organic Strawberries"))
 oranges = wf.add_item("Oranges", "Ripe mandarine oranges")

 =&gt; finished item Strawberries

 =&gt; finished item Oranges
 =&gt; congrats on completing list Whole Foods

 =&gt; finished item Milk
 =&gt; congrats on completing project Groceries

This was a really simple example, but shows how easy it is to create classes that embed state machines. For more check out the state_machine gem.

State Diagrams

The library also allows you to generate graphs of the states and transitions in each class. For example:

create a Rakefile.rb

 require 'tasks/state_machine'
 require './list_example.rb

Then in terminal execute:

 rake state_machine:draw CLASS=List 

For the List class shown above this will generate a png file named List_list_state.png that looks like the image below.

The List class is very simple so the diagram is also simple. In the case of my project there are many states and more complicated transitions between states so the diagram can be very handy to visualize what is happening when debugging a strange transition,


This todo list example is very simple but it allows exploring the basic features of the state_machine gem, and demonstrates how simple it is to add state machine functionality to classes. If a class you are designing has variables that keep state, and you are triggering behaviors when those variables change, then a state machine will likely be a more clean approach to organizing behavior in your class.

Refactoring: making master programmers

There is often a tension between product management and engineering when it comes to time spent adding new features vs. time spent in code refactoring. One could even explain this in terms of top line vs bottom line descriptions. Features mean sales, codebase is an asset, and poor code quality is a liability that affects cost and thus profit. Sloppy, risky, or fragile code is even called “technical debt” in many circles. This tension between features and code quality has always been a tightrope walk for any successful software or Internet company. Starve features and you kill sales, ignore expanding bloat and you will never win a sprint, let alone the marathon of staying relevant.

But there is a lot more to refactoring than code quality. In this post I wanted to mention one that is often overlooked: “refactoring makes good coders into master coders.” The best lessons come from revisiting your mistakes and improving them, but without refactoring the revisiting is limited to quick fixes to limit the impact of a bad architecture, design, or implementation. Yes we can learn from our mistakes by trying different approaches on future projects, but the problems are ever changing, and thus the learnings are not as clear. I have always found I learned so much more as a designer and a developer by revisiting a problem with a new level of experience to draw from.

Design has been more fortunate regarding the opportunity for refactoring; good design organizations understand how much can be learned by refactoring a design and thus fight hard to allow for it. Development has often not been as successful in making the case. I wonder if the cost analysis could be changed if executives understood that refactoring actually significantly improved two of the most important assets at a software company: the code base and the engineering talent. Then it becomes a more interesting decision versus a simple weighing of new features vs improved quality.


I got to thinking about this looking at Picasso’s Bull series. This is an excellent example of a master working through a problem to develop the most elegantly simplified expression of the subject. To become a master, one must work through a problem incrementally and always looking for elegant ways to improve, to simplify the end expression of the solution. Even for a competent coder, it is not always apparent what is elegant without seeing the real life consequences of chosen approaches. Whether the approach makes the code fragile, bloated, or unfriendly, it is only through the experience of trying to grow a code base that these issues can be truly understood. Under the right conditions refactoring provides a sort of express lane to becoming a master developer. This is very difficult if you are never allowed to truly revisit a subject after completing the first expression of the solution. I like the “Bull” example because it is how I think of elegant design and development, just enough to represent the solution and no more, anything else is bloat that will be nothing but cost later. Through refactoring, a developer can develop insights, skills, and techniques more quickly by addressing a well understood problem from a more experienced perspective. Practice make perfect. If not the code, maybe the coder.

Toggle Bluetooth

In my home office I have a Bluetooth keyboard and trackpad. When I use my MacBook Air elsewhere in the house I constantly see connect and disconnect messages for these devices. Frequently toggling BT on/off can be a pain; the menu bar method for toggling BT requires scanning the menu bar for the BT glyph, clicking on it, finding the correct menu item and clicking on it. All that scanning, tracking, and clicking can be disruptive to a good mental flow; I wanted a quick keyboard shortcut to toggle bluetoooth on/off. I use Alfred and after a quick search I found this extension that does just that. I use “bt” as the shortcut code. I have found this to be very handy, I now toggle out of habit, so no thinking required;

Syntax Highlighting in OS X quick look

Quick Look is a handy OS X feature where you can get a quick look at a file by selecting it and pressing the space bar. This is handy when looking through snippet files on disk. This plugin adds syntax highlighting in Quick Look supporting many common programming languages, and even supports R code.

Getting a quick definition

I am a logophile, and regularly looking up the meanings of words I encounter on the web or in pdf documents. More recent OS X versions include a great feature that allows you to get a quick definition in almost any app (browser, editor, etc). Highlight a word and press ctrl-command-d to get the definition of the word. It is easy to configure to include Wikipedia definitions so you can also look up people and concepts.

To customize which dictionaries are used (including wikipedia entries) open spotlight (command-space), type dictionary and press return to open the dictionary app. Open the preferences menu and tick the checkbox for the sources you wish to use. Once you make pressing ctrl-command-d a habit you will find using it is very natural, and requires little thought to remember it.

Make sure you have wikipedia configured and then try it on these:

  • crepuscule
  • quiescent
  • Malta
  • Thomas Bayes
  • Markov chain

The pop-up definition is interactive so click on a definition to see the full definition entry then use the back arrow to get back to the list of definitions. You can also click on the source title to open the dictionary app with that entry.

How to measure anything

Over the past year I have had the opportunity to advise a number of people I have worked with in the past who are starting companies. In the past few years my role had been that of a director of both design and R&D teams and so I enjoy continuing that type of role in providing direction to these exciting new startup ventures.

One thing  many of these early phase projects lack is clarity and proper measurement of the problem and opportunity; having only a vague sense of their relative probability of success given their chosen direction versus alternative approaches.

Lately a lot of new startups tend to point to some fuzzy “user experience” as their advantage, and why they will succeed. As a design director I know that this is B.S. and even design and user experience contributions can be measured to a reasonable degree of confidence.

More times than I care to say, I have pointed teams to read and practice the techniques in “How to Measure Anything: Finding the Value of Intangibles in Business” by Douglas Hubbard.

The first response is always, “Read a book, are you serious” — yes I am serious, this is a good book and for many people it provides some very important tools for success around estimation and prediction. If you learn and use this on your project it will become automatic for you, and require little thought. It just takes practice.

Here are just a few key excerpts to motivate you to read it:

There are three reasons why people think things can’t be measured, all are misconceptions about different aspects of measurement: Concept, Object, and Method.

  1. Concept of Measurement. The definition of measurement itself is widely misunderstood. If one understands what measurement means, a lot more things become possible.
  2. Object of measurement. The thing being measured is not well defined. Sloppy and ambiguous language gets in the way of measurement.
  3. Methods of measurement. Many procedures of empirical observation are not well known. If people were familiar with some of the basic methods, it would become apparent that many things thought to be immeasurable are not only measurable but may already have been measured.

Hubbard does a good job of making it clear that these three misconceptions are easily overcome, and you can learn to measure anything quickly. More importantly perhaps, you will end up with a better defined question or problem through the process of identifying measures.

He uses a definition of measurement based on uncertainty  that is very powerful, echoing Shannon’s information theory of entropy:

Measurement is a quantitatively expressed reduction of uncertainty based on one or more observations.

By framing measurement as “uncertainty reduction,” Hubbard has solved the problem for many people who get stuck thinking of measurement as an impossibly exact science. For as Hubbard points out, even inexact measurement is valuable if it reduces uncertainty by some non-trivial amount. This is especially true when investment in the project is high.

He spends several chapters on techniques for determining what to measure and how, and then get’s into what I found to be a great exercise for teams.  It involves calibration of estimation for team members. By evaluating how calibrated people are at estimation (usually not!) we can get the team to understand they they need to improve, and more importantly with the right tools they can learn to be quite proficient at estimation. Having this skill will help them in many ways in their day-to-day work.

Hubbard  discusses the terrible misunderstanding and misuse of risk management in business and R&D projects. You know, those useless Low/Med/High values people put on their slides! He instead prescribes the use of basic confidence intervals and shows the reader how to use them.

A simple example is his test of confidence.

For a given question you provide a range you believe has a 90% CI. For example you say with 90% confidence the module will take you 2-3 days to code, unit test, and submit to system test. Or the wireframe will take you 3-6 hours to update, get reviewed, and hand to engineering.

Then ask yourself this: Suppose I offered you a chance to win $1000 in one of two ways:

  1. You win $1,000 if you your estimation turns out to be correct. If not, you win nothing.
  2. You spin a dial divided into two unequal “pie slices,” one comprising 90% of the dial and the other just 10%. If the dial lands on the large slice, you win $1,000. If it lands on the small slice, you win nothing (i.e., there is a 90% chance you win $1,000).

About 80% of people choose option 2, but why would this be if their estimate is of 90% CI or higher. In reality they probably are more like 50%-80% confident. For those who choose option 1, it could also mean they are over 90% confidence but being conservative in estimating, this can be equally undesirable.

This is the Equivalent Bet Test. You should try to set up a mental test like this when assessing confidence and if you pick the wheel then keep lowering the win percentage on the wheel (80%, 70%, 60%, …) until you don’t pick the wheel, that will tell you your real confidence in the answer. Research shows turning it into a bet (real or pretend) increases the quality of the estimates.

People who are very good at assessing their uncertainty (i.e. they are right 80% of the time they say they are 80% confident, etc.) are called calibrated. It is good to be calibrated, projects and life become more predictable.

This was just a short teaser of a simple technique, but there are more techniques. I highly recommend Hubbard’s book for anyone involved in complex  endeavors whether on their own or in teams. You will find problems are more clearly articulated once you have  figured out how to measure it; having good calibration in estimation will also significantly reduce your project risk and improve your decision making significantly.

There was a recent question on Quora: Why are software development task estimations regularly off by a factor of 2-3? That I believe is true because of teams not doing proper analysis, but also it is a multiplier effect of bad estimation across a team. Because of interdependencies of teams these estimation errors can cause huge estimation errors when rolled together. Get the book: How to Measure Anything: Finding the Value of Intangibles in Business

User Stories and Activity Diagrams

I have been using Omnigraffle to create activity diagrams associated with user stories. Some people may find this overkill but I find doing these diagrams makes transitions clear that might otherwise be missed until later when they lead to costly re-architecting of the screens and flows.

I use Omnigraffle for UI wireframes, so it seemed natural to use it for activity diagrams, which is what I have been doing. The issue is keeping the diagrams up to date. Today, while playing with the Ragel state machine compiler I discovered Ragel’s awesome states/transitions diagramming feature. I learned the feature uses Graphviz to create the diagrams from the parser grammar. This led me to Ruby Graphviz, a Ruby library for interacting with Graphviz. It got me thinking that maybe there was a simple DSL that could be used to describe UI activities and screens and then automatically generate diagrams from the description. This would make keeping descriptions and diagrams in sync very easy.

My first step is always to get a piece of the most basic idea working, then add another piece, etc until a basic prototype is complete. Given this approach the first step was to use ruby-graphviz to create a basic diagram similar to one of our activity diagrams (a very basic one). So here was a quick pass experiment for using ruby-graphvis to create a diagram. The next step would be to define a basic DSL and then write a parser and state-machine and incorporate the graph creation into the state machine as it parses the DSL activity description.

require 'graphviz'
# Create a new graph
g = :G, :type => :digraph )
us_num = 47 #placeholder, will get from file name in final version.
# set global node options
g.node[:color] = "#333333"
g.node[:style] = "filled"
g.node[:shape] = "box"
g.node[:penwidth] = "1"
g.node[:fontname] = "Trebuchet MS"
g.node[:fontsize] = "8"
g.node[:fillcolor]= "#294b76"
g.node[:fontcolor]= "white"
g.node[:margin] = "0.0"
# set global edge options
g.edge[:color] = "#666666"
g.edge[:weight] = "1"
g.edge[:fontsize] = "6"
g.edge[:fontcolor]= "#444444"
g.edge[:fontname] = "Verdana"
g.edge[:dir] = "forward"
g.edge[:arrowsize]= "0.5"
my_nodes={"WF1"=>"New Account Screen", "WF2" =>"Account Recover Screen", "WF3" => "Welcome Screen"}
my_decisions={"D1"=>"", "D2" =>"", "D3" => "", "D4" => ""}
g.add_nodes("Start",{:label => "", :shape => "circle"})
my_nodes.each do |key, value|
# When adding a node the node name becomes the label so can access later.
g.add_nodes(key,{:label => value})
my_decisions.each do |key, value|
# When adding a node the node name becomes the label so can access later.
g.add_nodes(key,{:label => value, :shape => "diamond"})
g.add_nodes("End",{:label => "", :shape => "circle"})
#hello = g.add_nodes( "Hello" )
#world = g.add_nodes( "World" )
puts g.inspect
# Create an edge between the two nodes
g.add_edges( g.Start, g.D1)
g.add_edges( g.D1, g.WF1, {:label => "[create account]"})
g.add_edges( g.D1, g.WF2, {:label => "[attach account]"})
g.add_edges( g.WF1, g.D2)
g.add_edges( g.D2, g.D3, {:label => "[failure]"})
g.add_edges( g.D2, g.WF3, {:label => "[account created]"})
g.add_edges( g.D3, g.WF2, {:label => "[account exists]"})
g.add_edges( g.WF2, g.D4)
g.add_edges( g.D4, g.WF2, {:label => "[failure]"})
g.add_edges( g.D4, g.End, {:label => "[recovered]"})
g.add_edges( g.WF3, g.End)
# Generate output image
g.output( :png => "US#{us_num}.png" )

This above very simple example creates the diagram below.

This needs some cleanup of the aesthetics but the possibility is interesting. The next steps will be to come up with a very simple dsl, as simple as possible, maybe something that is markdown compliant so it fits inside our wiki pages cleanly. It would need to cover start and end states as well as intermediate state nodes. It would need to also handle decision points (diamonds) as well as transitions (edges) and notes. The simplest form would be to allow listing all nodes and all decisions, and then listing the connections between them. Labels would also be needed on all of these. IDs would probably help for wiring up the connections.

Then it is a matter of running a parser on the wiki pages, looking for the syntax associated with the activity descriptions and generating a diagram using some ruby code. This might be a nice experiment to familiarize myself with Ragel to better understand its strengths and capabilities.

I hope to get to spend some free time on this over the coming weeks, as it seems like a fun side project.

Remapping My Caps Lock Key

I’ve had my caps lock key mapped to the control key for the last few months as I have migrated back to Emacs from TextMate. It was a slight improvement over the placement of the control key but not a huge improvement. I came across this article: A Useful CAPS-Lock Key from Brett Terpstra and decided to give his mapping a try. This mapping requires free third party software, but I was particularly intrigued not by the escape key mapping, which is very handy, but by the “Hyper-key” (ctrl-shift-cmd-opt) being mapped to holding down the shift key. This opens a lot of potential system wide shortcut key-bindings that are a lot easier than using the uncomfortable ctrl-shift-cmd-opt.

So far it is very useful, I like the hyper-t for opening iTerm2 in visor mode, very handy. I will check back in in a month on this topic and share any other key bindings I come up with.

Treetop and Parsing Expression Grammars (PEGs)

Over the holiday I had some time to investigate parsing expression grammers. I had done work in Lex and Yacc many years back when I was responsible for some kernel functionality and related system management kernel commands for a proprietary commercial operating system. I don’t remember fondly my time working with Yacc. But then I read about PEGs and the Treetop Ruby library. It allows the use of simple grammer rules based in regular expressions and creates a parser ruby class from the grammer that can then be used in a ruby program. It also allows ruby blocks to be embedded directly into the grammer rules.

For our startup we have a core feature that includes some user generated instructions that are meant to create a mobile experience for others to participate in, sort of a simple FSM driven experience. We could present the authoring environment in a form-based interface, but this seemed a bit too restrictive. We may still go with forms, but I wanted to try an intermediate format using user readable text files, so we could write up test cases fast and easy, and compile them into the FSM class. I was also inspired by the simplicity of the markdown syntax and the way it is used in FoldingText. It may not pan out but I really had fun working on it.

I will post some code in the future, but thought I would post a link to the tutorial I found very helpful in getting my experiment up and running quickly. It is a well written tutorial that starts with the basics of getting a simple parser working, and then explores just enough complexity to get you to a place where a moderately complex grammer can be written. I think this is a great tool for any Ruby developer’s tool belt; and for certain classes of problems related to parsing information it is a very eloquent approach.

FoldingText and productivity

I have been using the FoldingText app for a couple of weeks. It is a very interesting app targeting writers, something I am not, but I was intrigued by the interactivity of this minimalist app. Specifically the ability to add interactive todo lists and timers and have them execute in a text document. Please take a look at the FoldingText Video to get a feel for it, I don’t want to describe ideas that a video shows so clearly.

I have been using it for my daily plan the past 2 weeks. I usually start each day with a mix of items I want to accomplish. These items usually include a mix of coding items for a sprint, some user stories for the backlog, and some wireframes for a future sprint, etc. The mix keeps the day feeling balanced. I add a mix of these to the day’s plan, and then organize them into pomodoro time slices.

The app’s simplicity allows some really interesting customization that isn’t present in an app like Vitamin-R, which is a good pomodoro app, but like most apps is not very flexible. For example, I have found that keeping the daily plan, now and later notes, and the time slices all in a single document is very powerful. Further I can add notes indented under time slices to describe what I did during each slice. Since everything is in a single text document (markdown) and lives in my nvALT notes app, I can easily search and find my daily notes that include what I accomplished each day, etc. This is good for reviewing how well certain activities mix together, looking at my velocity over time, etc.

All of that is useful but the reason for my making this post is that I find the interaction model to be very interesting, basically a text document with very simple embedded mini-apps that are triggered by simple human-readable phrases that add functionality while the document is open and in use. With all output living in the text document. It gives hints of a feeing of empowerment that early spreadsheet apps like Lotus123 delivered. I can imagine all sorts of useful embedded mini-apps, the key will be maintaining the simplicity. Many apps used for productivity today are incredibly prescriptive, FoldingText feels like you are really in control and able to customize the document as a very simple app. Of course FoldingText itself is still more of an app than a platform, but I can imagine it as a platform with many developers adding these mini-apps. Todo lists and timers seem like a powerful start, I can’t wait to see what comes next.

Wiki + searchable notes.

For our startup I have been using github wiki to keep the product specs, design docs, user stories, etc organized and up-to-date. The nice thing about github is you can clone the wiki and work on it locally and push changes up to the server. See this writeup for more info. This is handy because you can then work on the wiki using markdown syntax in a regular text editor versus a web page editor.

The ease of this made me wonder if there was a way to do my normal note taking, code journalling, etc in markdown vs Evernote. I did some looking around and found nvALT, which is a markdown based notebook that can save notes as flat .md files.

So as an experiment I cloned my personal notes wiki from github.  After configuring nvALT to use the cloned wiki directory as its directory I could immediately see and search all of my wiki files as nvALT note files. Also I could add new files and they would now become linkable as wiki files. So basically nvALT acts as a note taking system, but notes can be also linked together via a mmd link notation that is supported by the github wiki. You can install the gollum gem and interact with the wiki locally to test the wiki pages.

So I can now create, edit, search notes in markdown, but also link them, as well as view them as a wiki.

I will post again after a few weeks trying out the solution with more info on how it is working.

Fast PhotoSync from iPhone

Doing iOS design and development I find myself capturing images on the iPhone all the time to make notes on. These usually end up being added to my notes or to our project wiki (see Screen capture goodness and  Wiki + Searchable Notes for more on that).

To get the images from the phone to my Mac I was using Apple’s Photo Stream feature but it took too long and sometime images just didn’t show up on the Mac. So I went looking for a better solution and found the PhotoSynch app in the app store. You install it on the iphone via the ios app store ($1.99), and on the Mac via the Mac app store (Free).

It can then be configured to synch all the images in your camera roll with the Mac over wifi. It has a quick transfer feature that allows it to transfer all images since the last sync to the Mac.

You start the transfer on the phone, and when it completes a Finder window will appear on the Mac so you can see the images. At this point I use script to move certain images into the right folders. The process is quick, simple, and works every time.

Screen capture goodness...


Take the shell script from below and create a TextExpander snippet to save any image in your OS X clipboard to disk with a unique uuid.png name, and automatically create a markdown image link that is pasted in place in your editor.


When making notes on wireframes, screen designs, activity diagrams, etc, I have a particular workflow where I do a screen capture and want to link the result in my markdown notes or from our project wiki. The power of markdown text files is their portability, the challenge can be losing the rich cut and paste of apps like Evernote.

In a previous post Wiki + searchable notes. I mentioned that I was now using the github clone feature for the wiki, allowing me to work on the wiki locally and then push changes to the server with git push. Another benefit of this approach, it makes it very easy to add images to the wiki. 

The problem was it took too many steps to go from capturing the screen, saving it, and finally linking to it in the wiki/notes file. So I created a TextExpander snippet to do all of this in 2 steps (OSX only)

  1. screen capture (ctrl-cmd-shift-4)
  2. type “wpng” into the editor where I want the image to be placed.

First you need TextExpander and also you need to install pngpaste a small bit of code that handles saving a clipboard image to a png file.

Then you just need this snippet (I used “wpng” as the snippet abbreviation):

#!/usr/bin/env bash
var=$(/usr/local/bin/pngpaste $target 2>&1)
if [ "$var" == "No PNG data found on the clipboard!" ];
echo "No-PNG"
echo "[![$uuid_str.png](images/$uuid_str.png)](images/$uuid_str.png)"
I chose to just use a UUID for the file name to keep it simple and unique for each file. I added this as a snippet in TextExpander and now instead of 10+ steps across 3 apps my workflow for getting a screen capture into a wiki page is this: 1. screen capture (ctrl-cmd-shift-4) 1. type "wpng" into the editor where I want the image to be placed. The result: typing "wpng" causes the last clipboard item to be saved as a png in the wiki images directory and the "wpng" text I just typed is replaced with the markup for the image that was just saved. Quick and simple.