How I Built a Multi-User Door Buzzer for Our Apartment

Full disclosure: a lot of people have talked about this idea, this is just my implementation of it for our apartment.  You can check out Buzzeromatic.com if you want someone else to administer yours or post to Elance/oDesk/HackerNews/Twitter to get someone to build it for you.  Look for something cool from @gregkoberger with all those features I left out (user management, UI, adding new roomies, adding more numbers etc.)

Making a Present for My Roommates

About a month ago, I moved to a 3-story loft in SOMA with my husband Kevin and our good friends Park and Kat.  My sister also graduated college and joined a local startup, so she'll be moving in with us next week.  With 5 people living here and only 2 master keys to the front door, we had a bit of an access problem right away.  My roommates, knowing I haven't had a chance to code since the move started, were nice enough to suggest a build an app with my Twilio skills (full disclosure: I work there) and we tested it out last night - it works, so I'd love to share.

How A Call Box Works

If you've lived in an apartment with a call box for buzzing people into your apartment before, this will sound pretty familiar.  There is a list of names and corresponding codes listed on the callbox display, you dial the number and it rings the person who lives there, they press a key and the door is unlocked. What happens inside the callbox is a little more interesting - because the sound the keypress makes, which is called a DTMF tone, is actually a pretty amazing little thing.  Tone dialing was arguably one of the earliest massive implementations of human-to-computer communication.

Phreaking Out the Phone with DTMF Tones

There is a long history of phreaking (the image to the right is of a bluebox built by Steve Jobs and Steve Wozniak, on display at the Computer History Museum) by playing DTMF tones and other tones (pulses, pins, etc), and the things telecommunications hackers achieved without any kind of API like Twilio is pretty amazing.  In my case, the call box just requires the person who receives the call to press 6 to open the door, and responds when the 6 DTMF tone is played.  This tone doesn't have to come from pressing a key though,  I can just play the audio file into the phone to mimic the action of a keypress - and the doors opens! The simplest implementation of this is just to have the door automatically open when anyone dials your extension.  I don't recommend setting your callbox up this way, because you might accidentally let in people who are messing with the box looking for a way in so they can do bad things.  My street has a lot of bums and other riff-raff on it, so I wanted something with a couple different types of security.  So here's what I did.

Setting Up My Call Box with Twilio

If you haven't heard of my company, Twilio, before the really quick elevator pitch is that we are the AWS of telecommunications, making it easy to send/receive calls and text messages programmatically and only paying for what you use.  It's pretty sweet, its a startup, and I'd love your feedback on it.  So here we go:

• Get a local Twilio number (or you can use the sandbox number for free)

• Tell your building administrator to add your name/number to the box

• Build a simple app that forwards the call to your cell phone so you can make sure the box can recognize DTMF tones passed from a forwarded call

Doing this test before you build your full blown app is really important, it will save you from debugging an issue outside of your control.  You just need to create this little callbox.xml file, save it somewhere on the web (publicly accessible on Dropbox is a handy option, our try Twimlets) callbox.xml (replace 415-555-1212 with an actual phone number)

1. <Response>

2. <Dial>415-555-1212</Dial>

3. </Response>

If you are using your Twilio trial account, make sure you use the Twilio sandbox number and remember your pin code for testing (or email me at danielle@twilio.com and I can manually remove this restriction from your account). If you run into problems just email help@twilio.com for 24/7 support, or tweet @twilio

Building the Full App

Now that your testing is done, it's time to build the full app with just a little PHP.  This took me about 25 minutes to write from scratch in Emacs, probably will take you a whole lot less with all the sample code.  Here's the spec for how the app should work: Need to have:

• visitor or roommate dials our extension in the call box and our Twilio number is called

• menu is read to visitors, giving them the option of which roommate to contact

• roommates have a secret code they can punch in to bypass the menu and open the door

• if the visitor selects one of the roommates from the menu options, that roommate gets a call and presses a number on their cellphone dialpad to buzz in

Nice to have:

• menu selections can be made at anytime, without waiting for the menu to finish, because that is just annoying

• roommates can be simultaneously dialed on multiple numbers (cellphone, work, house phone) if they want

• fun audio files can be played when someone is let in

callbox.php - this file controls what happens when the callbox is dialed -->

1. <?php

2. header("content-type: text/xml");

3. echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";

4. ?>

5. <Response>

6. <Gather action="/doorbell_gather.php" method="POST">

7. <Say voice="woman">If you are here for Katrina, press 2.</Say>

8. <Say voice="woman">For Danielle, press 3.</Say>

9. <Say voice="woman">For Park, press 4.</Say>

10. <Say voice="woman">For Kevin, press 5.</Say>

11. </Gather>

12. </Response>

Two important things to point out here. First, notice that the menu options in the tag are nested within . This is awesome, because it means Twilio is listening for a keypress the entire time and you can interrupt the menu with your selection at anytime. Also, you'll see if you check out the Twilio example code that usually includes the numDigits parameter, but we're excluding it on purpose here because we want to accept secret pin codes in addition to single digit selections. You'll see why in a moment. doorbell_gather.php - this file determines what to do with the keypad data we just received Note on this code: There are definitely more elegant ways to write this, but in my mission to convert all my roommates to geeks I've opted for something they can easily understand in case they want to change their secret codes without my help.  All pincodes have been changed for this example. -->

1. <?php

2. if($_REQUEST['Digits'] == '2') {

3. header("Location: katrina.xml");

4. die;

5. }

6. if($_REQUEST['Digits'] == '3') {

7. header("Location: danielle.xml");

8. die;

9. }

10. if($_REQUEST['Digits'] == '4') {

11. header("Location: park.xml");

12. die;

13. }

14. if($_REQUEST['Digits'] == '5') {

15. header("Location: kevin.xml");

16. die;

17. }

18. if($_REQUEST['Digits'] == '1234') {

19. header("Location: secret-danielle.xml");

20. die;

21. }

22. if($_REQUEST['Digits'] == '6677') {

23. header("Location: secret-park.xml");

24. die;

25. }

26. if($_REQUEST['Digits'] == '9988') {

27. header("Location: secret-kevin.xml");

28. die;

29. }

30. if($_REQUEST['Digits'] == '6786') {

31. header("Location: secret-katrina.xml");

32. die;

33. }

34. header("content-type: text/xml");

35. echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";

36. ?>

37. <Response>

38. <Say>I'm sorry, but the person you attempted to reach is unavailable.  Please try again later.</Say>

39. </Response>

So Twilio is passing the keypress data as 'Digits' and we're telling Twilio where to go depending on what was pressed. Pretty simple. The little bit of TwiML at the bottom only plays if the roommate called doesn't answer their phone. So now we need to create:

• roommate.xml - which calls the selected roommate so they can buzz in their guest

• secret-roommate.xml - which automatically opens the door when the code is entered

You might be wondering why everyone has their own secret-roommate.xml file, when they all do the same thing.  I decided it would be fun to prank my roommates with a funny theme song or movie quote before the door would unlock... To complete this code, you'll need to get an audio file (.wav or .mp3) of the DTMF tone you want to play back to the machine.  I used this awesome DTMF generator, and they host the audio file for you. roommate.xml - the file that calls the selected roommate

1. <Response>

2. <Say>Connecting you to [Roommate's Name] now</Say>

3. <Dial>415-555-1212</Dial>

4. </Response>

secret-roommate.xml - the file that opens the door is the roommate enters the correct pin code. The first <Play> contains a fun audio clip from Back to the Future, the second one plays the DTMF tone that will open the door (make sure to change this depending on which tone will open your specific door).

1. <Response>

2. <Play>http://moviewavs.com/0059305935/WAVS/Movies/Back_To_The_Future/seriousBLEEP.wav</Play>

3. <Play>http://www.dialabc.com/i/cache/dtmfgen/wavpcm8.300/6.wav</Play>

4. </Response>

So there you go, now you can manage a callbox for a bunch of roommates, add secret pin codes, and even give selective access to delivery people, cleaning staff, or whoever else is coming by to visit. Let me know if you find any bugs or have ideas for how to make this cooler in the comments. Photo credits:

• Call box: http://www.flickr.com/photos/carol329/300231462/

• Touch Tone Telephones, 1966: http://www.flickr.com/photos/roadsidepictures/3601261522/

• Bluebox: http://www.flickr.com/photos/awarnack/110798864/