I was setting up PICO-8 on a raspberry pi on my TV, and I thought to myself, "Wouldn't it be nice if I could use my phone as a controller?". Obviously not ideal for games where tight controls are necessary, but a perfectly valid use case for slower or turned-based games.

Enter in Unified Remote!

At it's core, Unified Remote allows you to turn your phone into a remote, and it comes bundled with a bunch of remotes for various applications. However, I couldn't find anything that worked with PICO-8 out of the box. So I took it upon myself to create a custom remote.

This tutorial will assume you are running PICO-8 on a raspberry pi, and does not go into the setup of that piece.

First, you'll need to install the Unified Remote Server on your raspberry pi:

wget -O urserver.deb http://www.unifiedremote.com/d/rpi-deb
sudo dpkg -i urserver.deb 
rm urserver.deb 

Next, you'll need to setup Unified Remote Server to run as root whenever your pi starts up:

sudo modprobe uinput # just in case this hasn't been loaded yet

Modify /etc/rc.local (as root) and add the following somewhere before the "exit 0":

/opt/urserver/urserver-start &

Now, when you reboot your pi, Unified Remote Server should start up automatically.

Next, you'll want to add the custom PICO-8 controller that I've put together (feel free to tweak it to your needs using the Docs). To do this, you'll need to create a directory for custom remotes. For me, this was /opt/urserver/custom (even though the documentation says otherwise). You may want to go to the Unified Remote Server Manager interface at http://yourpihostnameorip:9510/web/#/log and see where the logs say it's looking for custom remotes to be sure. So in my case:

sudo mkdir /opt/urserver/custom
sudo mkdir /opt/urserver/custom/pico8

# Set permissions to a user other than root, so it's easier to work with
# Substitute your user here (or don't do it at all and just use root)
sudo chown pi /opt/urserver/custom/pico8
sudo chgrp pi /opt/urserver/custom/pico8

Then, you'll want to put the following files in the new pico8 directory:

meta.prop

meta.name: PICO-8
meta.author: John Langewisch
meta.description: Gamepad for PICO-8
meta.tags.category: gaming

layout.xml

<?xml version="1.0" encoding="utf-8"?>
<layout orientation="landscape" scroll="none">
  <row weight="1">
  </row>

  <row weight="6">
    <space weight="1"/>

    <grid color="#84769C" weight="4">
      <row>
        <space/>
        <button icon="up" ondown="core.keyboard.down,up" onup="core.keyboard.up,up"/>
        <space/>
      </row>

      <row>
        <button icon="left" ondown="core.keyboard.down,left" onup="core.keyboard.up,left"/>
        <space/>
        <button icon="right" ondown="core.keyboard.down,right" onup="core.keyboard.up,right"/>
      </row>

      <row>
        <space/>
        <button icon="down" ondown="core.keyboard.down,down" onup="core.keyboard.up,down"/>
        <space/>
      </row>
    </grid>

    <space weight="1"/>

    <grid weight="4">
      <row weight="2">
        <button image="logo.png" scale="fit" color="transparent"/>
      </row>

      <row weight="1">
      </row>

      <row>
        <space weight="1"/>
        <button text="SELECT" weight="6" ondown="core.keyboard.down,escape" onup="core.keyboard.up,escape"/>
        <space weight="1"/>
        <button text="START" weight="6" ondown="core.keyboard.down,enter" onup="core.keyboard.up,enter"/>
        <space weight="1"/>
      </row>
    </grid>

    <space weight="1"/>

    <grid weight="4">
      <row weight="3">
      </row>

      <row weight="4">
        <button icon="select" color="#FF6699" weight="2" ondown="core.keyboard.down,z" onup="core.keyboard.up,z"/>
        <space weight="1"/>
        <button icon="docclose" color="#FFCCAA" weight="2" ondown="core.keyboard.down,x" onup="core.keyboard.up,x"/>
      </row>

      <row weight="3">
      </row>
    </grid>

    <space weight="1"/>
  </row>

  <row weight="4">
  </row>
</layout>

icon.png (I just took the PICO-8 icon)
logo.png (I just took the PICO-8 logo)

Once you've added those files under /opt/urserver/custom/pico8 you should be able to restart the server to load the new remote either through the web UI, or by running:

/opt/urserver/urserver-stop
/opt/urserver/urserver-start

If things don't seem to be working, you can go to the web UI and check the logs for issues.

Now, you'll need to download the Unified Remote app to your phone (I paid for the full version, but it shouldn't be required). When you start the app, it should automatically find your server. Hopefully, when you add a new remote, and open the Gaming category, you should see your new PICO-8 remote. Add it, select it, and you should be able to control PICO-8 while it's running on your pi!

A few caveats:

• The files assume american style keyboard, feel free to tweak the buttons in the layout if that's an issue.
• I have the layout set to landscape orientation, but apparently Unified Remote doesn't respect that. I have to turn on screen rotation and make sure I'm in the correct orientation for it to look decent.
• I had some issues with the Unified Remote app picking up changes made to the meta.prop file. Clearing the app data, and starting from scratch solved it.
• I am using the wifi data connection for Unified Remote. This obviously relies on semi-decent network speeds to be responsive. Apparently there's also bluetooth connection, but I have not attempted that.
• "Select" is Escape, "Start" is Enter. Again, tweak to your heart's content.

Hopefully this is useful to folks!