ADB / Android Debug Bridge
Included with Macro DeckControl an Android phone or tablet over USB or Wi-Fi: wake it, start apps, tap, type and take screenshots.
The Overview tab of the ADB / Android Debug Bridge integration, with a notice to turn on ADB in Settings
- Wake, lock and reboot a connected Android device
- Start or force-stop apps and open links on the device
- Send keys, taps, swipes and text
- Save screenshots of the device screen to a folder
- Device events and variables for battery, screen and foreground app
The ADB integration controls Android phones and tablets through the Android Debug Bridge (ADB), the same tool Android developers use. Macro Deck finds the adb program, runs the ADB server and keeps track of the devices that are attached over USB or connected over Wi-Fi. It can also download the official Android platform-tools for you.
Every action works on the device you pick in the action, or on the default device when you leave Device empty. The default device is the one you chose with Set as default in Settings > ADB, or the only attached device when you chose none.
What you can do
- Screen and power: wake the device, turn the screen off (Android locks the device this way) or reboot it into Android, recovery or the bootloader.
- Apps and links: start an app or force-stop it by its package name, such as
com.spotify.music, and open a link with the app the device picks for it. - Input: send a key such as Home, Back, Volume Up or Media Play Pause, tap a point on the screen, swipe from one point to another, or type text into the focused field.
- Screenshots: capture the screen as a PNG file in a folder on your computer, and optionally write the file's path into a variable.
Some example setups:
- A button that wakes a tablet on your desk and starts your music app.
- A button that sends Media Play Pause to your phone.
- An automation on Device Connected that opens a dashboard page on a tablet as soon as you plug it in.
Live status
The integration reports when a device is connected, disconnected, authorized, becomes unauthorized, goes offline or comes back online, so flows and buttons can react to it. Variables hold the number of connected and authorized devices and, for the default device, its model, manufacturer, battery level, whether the screen is on, whether the lock screen shows and which app is in front. Each authorized device also gets variables of its own, named after its model. While the integration is on, the battery of each Android device also appears in the Battery widget.
The basic actions (keys, taps, swipes, text, apps, links, reboots and screenshots) keep working while Macro Deck is locked, so a button bound to one still works on a locked computer.
What you need
- Macro Deck 3 on Windows, macOS or Linux
- An Android device with USB debugging turned on in its Developer options
- A USB cable that carries data, or wireless debugging for a connection over Wi-Fi
- Android platform-tools (adb); Macro Deck can download them in Settings > ADB
- On Linux, permission for your user to access the USB device, usually through a udev rule
Set it up
Step 1: Turn on the ADB integration
In the sidebar, click Integrations and then ADB / Android Debug Bridge. The integration is off until you turn on the switch at the top right. Once it is on, the page shows ADB is turned off until you turn on ADB in the next step.
Step 2: Enable ADB in Macro Deck
Open Settings > ADB and turn on Enable ADB. If ADB program shows Not found, click Download platform-tools. An existing Android SDK or an
adbon yourPATHis found automatically, and Executable path lets you point to another one.Step 3: Turn on USB debugging on the device
On the phone or tablet, open Settings > About phone and tap Build number seven times to turn on Developer options. Then turn on USB debugging in Settings > Developer options. The exact place differs a little between manufacturers.
Step 4: Connect and authorize the device
Connect the device with a USB cable and confirm Allow USB debugging? on its screen. Tick Always allow from this computer so it does not ask again. The device then appears under Devices in Settings > ADB as Ready. To connect over Wi-Fi instead, enter the device's IP address and port under Connect over Wi-Fi, for example
192.168.1.20:5555.Step 5: Choose a default device
With more than one device attached, click Set as default next to the one your actions should use when you leave Device empty. With a single device, it is used automatically.
Step 6: Add an ADB action to a button
On the Deck page, make sure the deck is unlocked (the button at the top right reads Lock) and click a button. The editor opens with Short Press selected. Click + Add action, choose ADB / Android Debug Bridge on the left of the Add action dialog and pick an action, for example Wake Device or Start App. Fill in its fields, such as Package for Start App, and leave Device empty to use the default device. The category only appears while the integration is turned on.
Step 7: Press the button
Click Save and press the button on your deck. If nothing happens, check Integrations for a notice, such as No devices connected or a device that needs authorization.
Actions11
Put these on a button or run them from a flow.
- Wake Device
- Wakes the device screen.
- Sleep / Lock Screen
- Turns the device screen off, which is how Android locks a device.
- Start App
- Launches an app by its package name, or brings it to the front.
- Force Stop App
- Force-stops an app by its package name.
- Open Link
- Opens a URI on the device, the same as tapping a link.
- Type Text
- Types text into the currently focused field on the device.
- Send Key
- Sends a single Android key event, such as Home, Back, Volume Up or Media Next.
- Tap
- Taps the screen at the given X and Y coordinates.
- Swipe
- Swipes the screen from one point to another over a set duration.
- Reboot Device
- Reboots the device into Normal, Recovery or Bootloader mode.
- Take Screenshot
- Captures the device screen and saves it as a PNG file in a folder, optionally writing its path into a variable.
Triggers6
A button or flow can react to these events.
- Device Connected
- An Android device was plugged in, or Macro Deck first saw it.
- Device Disconnected
- An Android device was unplugged, or Macro Deck lost track of it.
- Device Authorized
- The authorization prompt was accepted on the device.
- Device Became Unauthorized
- A previously authorized device needs the authorization prompt accepted again.
- Device Went Online
- An authorized device became reachable again.
- Device Went Offline
- A device that was reachable can no longer be reached.
Variables11
Show these values on buttons and widgets, or use them in conditions.
adb_connected_device_count- The number of attached Android devices.
adb_authorized_device_count- The number of devices that are online and authorized.
adb_device_connected- Whether the default device is connected.
adb_device_authorized- Whether the default device has authorized this computer.
adb_device_model- The model of the default device.
adb_device_manufacturer- The manufacturer of the default device.
adb_device_battery_level- The battery level of the default device in percent.
adb_device_screen_on- Whether the screen of the default device is on.
adb_device_locked- Whether the default device shows its lock screen.
adb_device_foreground_app- The package name of the app in front on the default device.
adb_device_<device>_connected,adb_device_<device>_authorized,adb_device_<device>_model,adb_device_<device>_battery_level- Connected, authorized, model and battery level of each authorized device.
<device>is the device's model in lowercase letters, digits and underscores, with_2,_3and so on added for more devices of the same model.
Frequently asked questions
Do I need Android Studio or the Android SDK?
No. Macro Deck only needs the adb program from the Android platform-tools. Click Download platform-tools in Settings > ADB and Macro Deck downloads the official package from Google, about 15 MB, for its own use. An existing installation is found automatically.
Can I control a device over Wi-Fi?
Yes. Turn on wireless debugging on the device and enter its IP address and port under Connect over Wi-Fi in Settings > ADB. Macro Deck does not pair devices itself: on Android 11 and later, pair the device with this computer first, or switch it to network debugging over USB with adb tcpip. Otherwise the device refuses the connection.
Why does an action fail with no device found?
When you leave Device empty, the action uses the default device. If you chose none and more than one device is attached, there is no default, so pick a device in the action or click Set as default in Settings > ADB. Also check that the device shows Ready and not Not authorized.
Is there a separate lock action?
No. Android has no separate lock command. Sleep / Lock Screen turns the screen off, which locks the device the same way the power button does.
Does the ADB integration affect other programs that use ADB?
Macro Deck uses the normal ADB server, so programs such as Android Studio share it. Restart ADB server in Settings > ADB briefly disconnects their devices too. Macro Deck leaves the server running when it exits unless you turn on Stop ADB server when Macro Deck exits.
Why does the device show "No permission to access this device"?
The computer lacks permission to talk to the device over USB. On Linux, install the platform-tools udev rules; on Windows, install the manufacturer's USB driver for the device.
More in Your computer
System
Included with Macro DeckControl your computer from your deck: apps, volume, commands, notifications, sleep and shutdown.
Keyboard
Included with Macro DeckPress shortcuts, type text and run key sequences on your computer from a button.
Mouse
Included with Macro DeckClick, move the pointer, drag and scroll on your computer from a button.
Steam
Included with Macro DeckStart and close Steam games, and show what you play, your friends and your library on your deck.