Plugin Developer Guide

So you want to write a plugin?! You came to the right place!

Modify the default plugin

The easiest way to create a plugin is to modify the existing one. Open this file:

plugins/siriproxy-example/lib/siriproxy-example.rb

You can see a simple structure of how Siri intercepts voice commands. The syntax is:

listen_for /regular expression/i do
    say something
    request_completed
end

When you speak to Siri, it matches the captured text against the regular expressions you specify with each "listen_for". See later in this document for some Ruby regular expression tricks if you aren't familiar with Ruby syntax.

Try changing this line:

  listen_for /test siri proxy/i do

to:

  listen_for /hello siri proxy/i do

Installing your plugin

After modifying the default plugin, stop your Siri server (Ctrl-C). In your Siri root directory (not .siriproxy, but the root of your Siri proxy checkout) run:

siriproxy update .

The '.' is required because otherwise the update will go out to Github to find things. This isn't documented anywhere, so hopefully you found this page!

Start up your Siri proxy server again with:

rvmsudo siriproxy server

Now test it out! Use your phone to say "hello siri proxy". If you get the correct response, it works! Congratulations!

Publishing your plugin for others to install

Currently it is not documented anywhere how to do this. If you know how, please add it to this section. Otherwise, consider it impossible.

Regex tips

Ruby regexes are similar to other languages. If you are not familiar with a regular expression, go read up on it, because you won't be able to develop a plugin without that knowledge.

To specify a capture group:

listen_for /siri proxy word ([a-z]*)/i do |word|

To specify multiple capture groups (test this by saying "siri proxy word hello number three"):

listen_for /siri proxy word ([a-z]*) number ([a-z]*)/i do |word, number|

SUPER IMPORTANT NOTE: Why did we make "number" a letter group instead of digits? It's because nothing magic happens when you say a number. Siri will interpret you saying "three" as the word "three". The exception to this is if you say a string of numbers like "four five six" Siri will interpret that as "456".

To specify optional words:

listen_for /how do I get to(?: the)? store/i do

There are two important things in the above statement. First, the ?: in the group means it will not capture, so you don't need to add a |capture| after the do. If you want to capture the optional word, remove the ?:. The second important thing is the space is IN the capture group. If you just did this:

listen_for /how do I get to (?:the)? store/i do

And you said "how do I get to store" to Siri, it wouldn't match, because the regex would be looking for two spaces, one before the group and one after. Tricky and stupid stuff!

Passing configuration options to your plugin

TODO

Making Siri remember things

One way to get Siri to remember things is to cache them to a file which is restored upon reinitialization of SiriProxy. For example, if you have multiple key/value pairs you want Siri to remember you can store them in a Hash and write/read from a CSV file.

``require 'csv'

Read from a CSV file:

@reFile = "#{Dir.home}/.siriproxy/resel.csv" @reSel = Hash.new if File.exists?(@reFile) @reSel = Hash[CSV.read(@reFile)] else @reSel["redeye"] = "living" @reSel["room"] = "living" @reSel["device"] = "tv" @reSel["feed"] = "ota" end

Write to a CSV file:

CSV.open(@reFile, "wb") {|csv| @reSel.to_a.each {|elem| csv << elem} }``

Using special characters

If you want to use special characters, such as accents, some modifications are needed (see Issue #50). Basically, you have to add the line below at the first line of any .rb file (don't panic, there's a patch for that ;) )

 # -*- encoding: utf-8 -*-

Also, your text editor may be configured to save files using UTF-8. Here's the command if you want to patch SiriProxy's .rb files

curl -o- https://github.com/eMxyzptlk/SiriProxy/commit/739b0cefb3e60b94514123c010820a1d51c99dfb.patch | patch -Np1

Troubleshooting

If you get this when starting up Siri proxy:

rescue in block in initialize': Cannot start the server on port 443

Run this command to find out which programs are listening on port 443:

sudo lsof -i:443

Then get their PIDs (you probably only need to kill ruby) from the PID column and kill them with:

sudo kill -9 xxxx

This page is a work in progress. Feel free to edit it.