Teleportme - an automated always-on FaceTime powered Portal

Teleportme is an open source project which aims to connect people through an automated and always-on portal - transport your inter-offices, meeting room, or common area communication across large distances with a FaceTime powered portal.

Why use Teleportme?

The Teleportme portal is a fantastic way of keeping remote offices linked. Like a modern-day global water-cooler, but without the water... and just cooler!

PaperCut Dev team in Melbourne talking to the team in Portland

Skype, hangouts, or facetime calls are great in regular usage too, but people tend to think 'oh the person is too busy, I won't bother them'. With Teleportme set up, it's a lot more relaxed and allows people to wander past the portal (if you set it up in a well-trafficked area) and catch up with people at the other site who are also near.

With the offices here at PaperCut we've noticed a definite positive change with the regions chatting between each other, and more people from different teams chatting to people in other teams. "Cross-collaboration" - in presentation-speak.

This project provides the software and setup documentation required to get everything up and running in your organization.

How does it work?

The system is based around a mac mini (or other mac) connected to a TV with a webcam, in each location. The software automates an always-on video conference session between two sites. It's a set-and forget system - all you do is set it up and each day it boots up and the portal opens at your predefined times (i.e. overlapping business hours).

At a high level is works by automating Apple FaceTime on a set schedule. On the software side it's a Bash Shell Script (.command file) that runs on system startup and does the work behind the scenes to open the connection and keep it alive.

Hardware Recommendation

There's no hard-and-fast rules for this - but here's the hardware that we're using at PaperCut. Consider this reference hardware and a good starting point:

Mac computer - A base model Apple Mac Mini
Webcam - Logitech Webcam C930e
HDMI Cable - Can be purchased from the Apple Store
External Speakers - Any amplified PC speaker will do
TV with HDMI supporting auto on/off schedules (e.g. Samsung Smart TV)

Let's set it up!

Step 1: Setting up the Mac

The Mac setup is pretty standard with the following configuration:

System Preferences -> Users and Groups - Set up a default user account on the mac at each of the sites - e.g. site1-portal-user and site2-portal-user.
System Preferences -> Users & Groups -> Login Options - Ensure Automatic Login is set to the user created in the step above.
System Preferences -> Bluetooth - Turn off Bluetooth - The box will run without a keyboard and mouse, so turn off Bluetooth so it does not raise 'unable to find' message.
System Preferences -> Sharing - Change the hostname of each machine to e.g. site1-portal-mac and site2-portal-mac.
System Preferences -> Sharing - Enable Screen Sharing to support remote management.
System Preferences -> Energy Saver - Set the Screen to Never turn off
System Preferences -> Energy Saver -> Schedule - Set startup time to [1 minute before portal open time] and set sleep time to [portal close time].

Step 2: Configure FaceTime

Create an Apple ID for each of the sites, in order to use with FaceTime at the Apple ID page
Login to FaceTime with the Apple ID assigned for that site

Step 3: Setup the script

Copy the script teleportme.command onto the Desktop (download here)
Ensure the script has execute permissions (e.g. chmod +x ~/Desktop/teleportme.command )
Add the teleportme.command to the login startup items for the account: System Preferences -> Users & Groups -> Login Items, then add ~/Desktop/teleportme.command
Open teleportme.command in a text editor, and modify the Config Section of the script. Change:

CALLER_FACETIME_ID
CALLER_HOSTNAME 
RECEIVER_FACETIME_ID 
RECEIVER_HOSTNAME 
OPEN_UTC_HOURS 
OPEN_UTC_DAYS_OF_WEEK

Step 4: Setup Additional items to make your life happier!

Install Cliclick

By default, the mouse pointer lands up being placed over the menu bar in Mac OS. This means that the menu bar is annoyingly visible during FaceTime calls. The teleportme.command script will run the 'Cliclick' utility (if installed) to move the mouse out of the way, allowing the menu bar to auto-hide, letting you enjoy the full-screen Portal experience!
Download the utility from the Developer's page, then copy the cliclick executable over to the same directory location as your teleportme.command file.

Webcam Zoom

Try using a utility from the manufacturer of your Webcam - e.g. the Logitech Utility from the Mac App Store, and use it to adjust the zoom/pan to make sure the picture looks good!
1.3x times zoom would be a good starting point
Ideally position the camera so that when people on the other side are looking at the screen, it looks like they are looking directly into the portal

Mac Mini Placement

Once you've got the system up and going, consider mounting the mac mini on the back of the TV.
Double-sided Velcro is a good choice.

TV Setup

Mount your TV in a visible public location. A movable mount is ideal.
It's recommended to make the following changes on the TV (assuming the TV supports it)

Turn on/off on a schedule (matching the portal open/close schedule)
Turn off on no HDMI input

Due to the delay in signal through the HDMI cable, the echo/feedback cancellation built into FaceTime seems to have problems so you will need to use external speakers plugged directly into the mac, rather than using the speakers built into the TV.

Manual Management/Startup

If you need to temporarily turn off the portal, simply close the Terminal window. When finished, open it again by double clicking on teleportme.command on the Desktop.

Looks good so far - are there any cool features?

Custom sounds - we prefer Wallace and Gromit sound effects, but Dr Who and other sounds are also more than appropriate!
Automatic reconnect on failure - if the call drops due to a bad connection, the call with be re-attempted regularly.
Automatic wake/sleep of the TV and the Mac, and automatic start/stop of the script means that the portal automatically opens/closes with no intervention required on either end!

Why external speakers?

It's probably worth re-iterating this part - due to the delay in signal through the HDMI cable, the echo/feedback cancellation built into Facetime seems to have problems - so you will need to use external speakers plugged directly into the mac, rather than using the speakers built into the TV.

Technical - How it works:

On startup teleportme.command is automatically started and permanently runs in a Terminal Window. One system is the 'called' and the other the 'receiver'.

On the Receiver:

FaceTime is configured to automatically accept calls from “caller”.
If the portal time window is open (based on config), FaceTime is started and waits for a call.
When a call is received/started, full screen mode is activated.
FaceTime is quit when the portal time is closed.

On the Caller:

If the portal time window is open (based on config), FaceTime is started and instructed to call “receiver”.
When a call is received/started, full screen mode is activated.
If the call drops, or is unable to start, it retries
FaceTime is quit when the portal time is closed.

Talking of Mac - why did you choose that platform?

There were a few reasons that a mac setup worked for us in our situation, but there are always other ways of doing things…

Easy to replicate the exact same setup between different sites
Mac hardware is available world-wide
Facetime has excellent quality - in testing from the West Coast of the US to Australia on a daily basis, the quality remains exceptional

How much bandwidth does FaceTime need, and how much data will I use up when the Portal is open?

HD Video bandwidth suggestions for FaceTime from Apple are listed here: http://support.apple.com/kb/ht4534
In terms of data usage, we've found that ~400 MB data uploaded / ~400 MB downloaded for a 1 hour call is average, however it depends on how much activity there is, so these numbers could vary greatly!

How do I configure the Portal Open/Close sounds?

Portal open sound - create or copy a .wav file to the same directory as the script, and name it: portal_open.wav
Portal close sound - create or copy a .wav file to the same directory as the script, and name it: portal_close.wav

Where does the 'Teleportme' name come from?

Teleportme was kindly suggested by Paul Saint George, the artist behind the Telectroscope project. The Telectroscope is a modern day art project, where people in New York and London see each other through a steam-punk-esque 'tube'...

In Paul's words: "I am sure you know the theory that all tech was invented in Eagle comic and Star Trek (The Original Series), so why not go straight for the teleportation reference? It's an active verb (teleport) and a personal pronoun (me), rather than a noun describing the object."

The fine print...

This open source project is sponsored by PaperCut Software, the coffee-fuelled producers of print management software. The Authors are Chris (codedance) and Tim (squashedbeetle). Please feel free to send us a pull request or file an issue!