A modern (post-2019) Homebridge-verified Amazon Dash plugin for Homebridge. Requires elevated privileges to configure and a WiFi device in monitor mode.
npm install homebridge-amazondash-mac  
A modern (post-2019) Homebridge-verified Amazon Dash plugin for Homebridge that doesn't require Dash button modification, Dash button setup (through Amazon or other means) nor the Dash button connecting to a local network.
Through Homebridge, this plugin (and with an additional supported USB WiFi device typically) Amazon Dash buttons can be used as Homekit buttons.
This plugin also provides an optional web API to virtually push the Amazon Dash buttons via URL.
This project is a fork of jourdant's homebridge-amazondash-ng, which is a fork of KhaosT's homebridge-amazondash.
An Amazon Dash button:
* has a rounded, elongated shape with an concave button on one end
* is white, with a removable product brand sticker
* is being resold online often as "button pushed once"
* includes its own removable clip for hanging and adhesive pads for mounting
* includes an (almost, see below) non-replaceable battery powering an estimated 1,000 clicks
* can create a WiFi access point reporting device information via HTML
* has Bluetooth and a microphone
* is further described here
By December 31, 2019, Amazon removed the capability to set up a Dash button for connection to a network. Also at that time, all Dash buttons that were connected to a network received an over-the-air update that disabled the button—a process Amazon refers to as "deregistration."
requires a second WiFi device (e.g. USB WiFi) if the Homebridge computer uses its native WiFi as its connection to the local network or that native WiFi device does not support monitor mode or is not stable in monitor mode*
* monitoring is done via tcpdump in a separate, non-blocking process
uses tcpdump's ability to report on MAC addresses visible to the WiFi device in monitor mode*
converts the Dash button's failed attempt* to connect to a local network on Dash button press as a HomeKit button single-press
* may not work with a Dash button that was "deregistered" via the over-the-air firmware update
This plugin is a fork of jourdant's homebridge-amazondash-ng with:
* Removal of the requirement to run Homebridge with root privileges
* Switch to tcpdump from airodump-ng
* Support for the Homebridge Plugin Settings GUI
* Support of and expectation that a Dash button cannot be configured nor connect to the local network
Support for distinct Single Press and Double Press* events if enabled for a button.
* Multiple buttons can appear and act as one button through aliasing
* An optionally-enabled web API allowing virtual button pushes via URL
* Support for firmware revision, serial number, model number
* Multiple logging debug levels
* User ability to remove a stale button during setup experimentation
* Installation and usage documentation
* Code maintenance, bug fixes
Options tab. On that screen you can set the start time and end time to play. You can also increase the song's default volume. In Apple's Home* app, you can set to play the song on "repeat."Settings. It is likely you'll need to remove those device's caches via the "Remove Single Cached Accessory" function of the "Manage Cached Accessories" section of the Homebridge Settings accessible from the Homebridge UI's upper right menu icon.tcpdump is present on your system and install if neededsudo tcpdump --monitor-mode standalone with the WiFi device (i.e. -i and the WiFi interface name) to test usage and visibility of Dash activityhomebridge user permission to also sudo tcpdump without a passwordnpm install -g homebridge-amazondash-macdebug levels during installation experimentationjson
{
"platform": "AmazonDash-MAC",
"name": "AmazonDash-MAC",
"interface": "wlx9cefd5fa2fdf",
"debug": 2,
"wport": 3000,
"buttons": [
{
"name": "Doorbell",
"MAC": "AA:BB:CC:DD:EE:FF",
"serial": "G030QC0400868230",
"firmware": "50018520_US",
"model": "JK29LP",
"doublePress": false
},
{
"name": "Button One",
"MAC": "AABBCCDDEEFF",
"serial": "G030MQ0370960400",
"firmware": "40018220_US",
"model": "JK29LP",
"alias": [
"a0b0c0d0e0f0"
],
"doublePress": false
},
{
"name": "Button Two",
"MAC": "aa:bb:cc:dd:ee:ff",
"serial": "G030DN0400063350",
"firmware": "50018520_US",
"model": "JK29LP",
"doublePress": true
}
]
}
`$3
refers to the monitoring WiFi interface for tcpdump to listen on. Once the WiFi monitoring interface is properly set up, this identifier is reported by the iwconfig or tcpdump -D command.$3
* Silent (0) No reporting.
* Default Runtime Messages (1) Reports when a button is triggered. This debug level is recommended for day-to-day working installations.
* Testing Messages (2) Reports removal, creation or configuration of accessories at initialization. This debug level is useful when testing a configuration and a debug level after using the special Clear Accessories debug level.
* MAC Address Discovery (3) Reports visible MAC addresses only at initial discovery. This debug level is helpful for configuration and testing.
MAC Address Streaming (4) Reports all visible MAC addresses as they are parsed live. This debug level is very* verbose.
* Clear Accessories (10) A special debug level that removes all previously added accessories. This is useful when experimenting during initial configuration when "phantom" accessories may be displayed or accessory characteristics are not being updated due to caching of previous versions of those accessories during configuration experimentation. To use, set debug to 10 and restart Homebridge. Reset debug to the (non-10) desired debug level (2 is recommended) and restart Homebridge. This second restart will recreate the accessories fresh from the config.json file. Note any Homekit actions previously configured for the button accessories may not be retained and may need to be reconfigured for each.Getting a Dash Button MAC Address, Serial Number, Firmware Version, Model Number
$3
The model number is printed on the back of the Dash button.$3
An Amazon Dash button can create a WiFi access point and can provide its information via an internally-generated web page.* Long press on the Dash button until the light flashes blue
* Join the network
Amazon ConfigureMe newly created by that Dash button
* Open the URL http://192.168.0.1 on the device connected to Amazon ConfigureMe
* MAC address, serial number, firmware version (and battery level) are displayed
* The reported information can be copy-pasted as-is individually into the plugin settings fields. To do so, keep the page display (e.g. in a browser tab) and switch over to the local network to access the plugin settings form (e.g. in a second browser tab). $3
It has been seen (e.g., after the battery is replaced) that the web page at from the Amazon ConfigureMe WiFi access point may return an apparently blank page. On view of the page source, the serial number, firmware and MAC address may be present within the structure:`
$3
You may see a different Dash-generated web page such as below.!Alternate Amazon Dash Information Page
A Dash button showing a page of this type may or may not work with this plugin. Please try to enter your WiFi credentials and use this plugin in
debug mode to test if the button's MAC is visible, and that button's MAC address (if it is). If you are (or are not) able to use this technique for buttons showing a page of this type, please share your experiences in this plugin's GitHub discussion.$3
On pessing an Amazon Dash button, is the button's light initially red instead of white? If you don't see an inital white light on pressing a Dash button, it is not attempting to connect to a network, therefore the button in its curent state will not work with this plugin. Dash buttons that had fully-depleted batteries before battery replacement or the button was pushed while the battery was low have exhibited this condition. Under these conditions, the Dash button may still be capable of reporting its MAC address and battery level via its Amazon ConfigureMe WiFi access point at 192.168.0.1 (activated by a long press until the light pulses blue) but it no longer attempts to connect to a network on button press (the "white light" phase is missing). As it can report its MAC address, etc., it may still be recoverable, depending on its firmware version, by flashing it via the "play a specific audio WAV file via an earbud up to its microphone while the light is pulsing blue; a green light means success" method. Firmware 40018220_US may allow a recovery; firmware 50018520_US and 60019520_US may not.$3
alias is an optional configuration for situations where a button is meant to act just as another. For example, you may have a need for more than one doorbell button for multiple doors. Another example is a button to trigger a "Goodnight" scene—however you want one on each nightstand on each side of the bed.To use this capability, configure one of the buttons as typical—this is the button that will be visible in Homekit. In the
alias portion of its configuration, add the MAC addresses of other buttons to "alias for" or "masquerade as" that button. When buttons with those MAC addresses are pushed, it will appear to Homekit as if the visible button was pushed.The buttons corresponding to the MAC addresses in the
alias list are not intended to be visible as separate accessories in Homekit—do not add the buttons corresponding to the MAC addresses in the alias list as separate button accessories.WiFi Device and Monitor Mode
A WiFi device capable of monitor mode is needed for tcpdump to see Amazon Dash button activity. If your Homebridge computer's connection to the local network is via WiFi, you'll need a second WiFi device (such as a USB WiFi adapter) capable of monitor mode.A USB WiFi adapter is about $10-$20 with free shipping online. If you would like some insight about compatible WiFi adapters or you have tried a USB WiFi adapter with this plugin, learn more from or share your experience with the community (good or bad) in this repository's discussion. For example, a USB WiFi device known to work in some contexts for these purposes is the Panda 300Mbps Wireless 802.11n USB Adapter (PAU05).
$3
This is example-only. There are several and different ways to do this.* Confirming the WiFi device is working, visible and to get the
interface name:
`
sudo iw dev
* Test the WiFi device can be put in monitor mode ( is for example only) (method one):
`
sudo ip link set wlan0 down
sudo iw wlan0 set monitor none
sudo ip link set wlan0 up
* Test the WiFi device can be put in monitor mode ( is for example only) (method two):
`
sudo ifconfig wlan0 down
sudo iwconfig wlan0 mode monitor
sudo ifconfig wlan0 up
* Confirm monitor mode and WiFi monitoring interface name (confirm "Mode:Monitor"):
iwconfig
This plugin uses 's ability to report on MAC addresses visible to the WiFi device (in monitor mode) and converts the Dash button's exposure of its MAC address on button press as a Homekit button single-press. tcpdump can only see Amazon Dash buttons when connected to a WiFi device in monitor mode.$3
* Test tcpdump stand-alone with the WiFi monitoring interface name (wlan0 is for example only):
`
sudo tcpdump -i wlan0 --monitor-mode
Note: It has been seen that may fail with --monitor-mode with the error "That device doesn't support monitor mode" although the device is reporting it is in and seemingly working in monitor mode via iwconfig, and demonstrated to work in an alternate OS version. This issue has been seen with the PAU05 device in Jammy Jellyfish Ubuntu. Under these conditions, using airodump-ng as an alternate to tcpdump is likely a workable option. To use this option, follow the instructions for tcpdump but install aircrack-ng and permit airodump-ng to be run via sudo without a password. Enable the setting Use airodump-ng instead of tcpdump* in this plugin's settings.$3
* If the above test failed because tcpdump is not installed, install tcpdump:
`
sudo apt install tcpdump
$3
If is not (yet) permitted to run by the homebridge user via sudo without a password prompt, you will see this log entry on restarting Homebridge:
`
[AmazonDash-MAC] ERROR: additional steps are required to allow user (user name) to run tcpdump via sudo on (host name)
[AmazonDash-MAC] ERROR: see installation documentation for next steps
[AmazonDash-MAC] ERROR: tcpdump exited, code 1
[AmazonDash-MAC] ERROR: tcpdump closed, code 1
You'll need to configure
to be run via sudo by the homebridge user without without a password.
* For this configuration, you'll need the location of tcpdump on your system via e.g. whereis tcpdump.#### Method One: If you already have an entry for the
homebridge user in your sudoers file* Add the full path of
tcpdump at the end of the homebridge entry in the /etc/sudoers file via the visudo command to edit that file:
`
sudo visudo
is required and is a text-only editor (e.g. vi or GNU nano) with editor-specific command keystrokes.
* Add your location of tcpdump (e.g. , /usr/sbin/tcpdump) to the end of the homebridge entry:
`
homebridge ALL=(ALL) NOPASSWD:SETENV: /usr/sbin/shutdown, /usr/bin/npm, /usr/local/bin/npm, /usr/sbin/tcpdump
If there is no entry for the user such as the above in the sudoers file, proceed to Method Two*.
* Save the file and exit with that text editor's method. Accept any default file names during the save-and-exit step.
* vi or vim sequence
* esc key
* :wq
* enter key
* GNU nano sequence
* control-x#### Method Two: If you don't have an entry for the
homebridge user in your sudoers fileThis method is creating a new file in the
/etc/sudoers.d directory. All files in the /etc/sudoers.d directory are included via the /etc/sudoers file by the #includedir /etc/sudoers.d. Note the # does not indicate a comment, as one would think.1. Create a new file (e.g. named
amazondash—it could be anything) with root permissions (e.g. via sudo gedit amazondash) in the /etc/sudoers.d directory.
1. Add the line homebridge ALL=(ALL) NOPASSWD: /usr/sbin/tcpdump (with your path to tcpdump). Save and exit.Migrating to 3.0.0 from Versions Prior to 3.0.0
As of version 3.0.0, Double Press functionality is enabled on a per-button basis. If you have been using Double Press functionality prior to version 3.0.0, re-enable this functionality as needed per-button via this plugin's settings.
It is likely you'll need to remove those device's caches via the "Remove Single Cached Accessory" function of the "Manage Cached Accessories" section of the Homebridge Settings accessible from the Homebridge UI's upper right "three dots" menu icon.
Pushing Buttons Virtually via the Web API
To enable the ability to push buttons virtually via a web API and URL, specify a port number in "Web API Port" via
Settings. An example is 3000. If "Web API Port" is blank, the Web API will not be active.Buttons can be virtually pushed either by MAC address or by button name.
$3
The URL are of the forms:
*
http://HOST:PORT/mac/MACADDRESS00
*
* where "HOST" is the host name or IP address of the computer running Homebridge.
Examples
*
*
* If a virtual button push is received and valid, the JSON of the virtually pushed button will be returned. Any other condition will return with no data.
If a virtual button push is received and valid but sooner than 5 seconds after a request to push that same button, no data and status 425 "too early" will be returned.
When using the "name" form of the URL and a button name contains a space, replace the space with
to encode the space for use in the URL.The "mac" form of the URL accepts typical formats of a MAC address (with or without colons, upper or lower case).
The "buttons" form of the URL will return the JSON of all buttons.
$3
To require a token to get the list of buttons or push buttons virtually via the web API, specify the token string in "Web API Token" via
Settings. If "Web API Token" is blank, a token will not be required. The allowable characters for a token is restricted for URL path safety.When using a token, insert it as the first element of the URL path, following host and port. Examples:
*
http://192.168.0.50:3000/yourtokenstring/name/Front%20Doorbell
* Replacing the Battery May Be Possible
$3
$3
If the unit boots (i.e. from a button press) while "low power" it will stop attempting to connect to a network—i.e., a red light only and no white light—even after a new battery is installed. It can still report its MAC address and battery level via its
WiFi access point at 192.168.0.1` (activated by a long press until the light pulses blue) but it no longer attempts to connect to a network on button press (during the "white light" phase). As it can report its MAC address, etc. it may still be recoverable by flashing it via the microphone method, depending on the firmware version.Change the battery before the battery level becomes too low.
Do not press the button if the battery is low.
* Version 1 (the one with the screws under the slicker) has a spot-welded lithium AAA that is not easily replaced.
* Version 2 (without the screws) from the factory has a Duracell AAA battery in a conventional battery holder.
However, an access door is not provided.
An access slot is easily cut-in from the back with a rotary tool. A back cut-in slot directly exposes the battery area.
Cut a rectangular slot 4mm inset from all sides of the oval groove on the flat back side.
!Amazon Dash Version 1: Spot-Welded Battery
!Amazon Dash Version 2: Spacing and Tool Bit
!Amazon Dash Version 2: Cutouts
!3M Mounting Strip Covering New Battery Access