Quick Start Guide – BCG-MD1 MotherDuck Gateway

Introduction to the Blue Charm MotherDuck BLE Gateway:

-The MotherDuck keeps an eye of up to three Blue Charm beacons (baby ducks!).
-When one of these beacons comes into range, the MotherDuck fires a webhook URL specific to that beacon which will trigger some specified action depending on the webhook.
-When one of these beacons goes out of range, the MotherDuck fires a different webhook URL specific to that beacon which will trigger some specified action depending on the webhook.
-Possible webhooks include IFTTT webhooks, Hubitat Maker API webhooks, PushCut webhooks, etc.

Shortcut links to jump directly to various sections on this page

Connect the MotherDuck to your local wifi network
Entering your beacon ID numbers and scanning parameters into the MotherDuck
Turning off the scanner if the settings webpage is not reloading and/or frequently getting stuck half way during reloading
Understanding webhooks
Selecting the optimal IN range and OUT of range settings for your project
Using the Missed Scan Interval setting to cover instances where beacon is purposely turned off or goes out of range too quickly
Using the consecutive IN and OUT of range counts to avoid misreports due to signal instability
How to erase existing wifi credentials
Using Practice Mode
Tips for your first automation project

Meaning of various LED lights

Before you jump into Step 1, some brief tips to keep in mind

  • Start with only ONE beacon automation. Using more than one beacon at the same time can sometimes lead to frustrating confusion.
  • Start with the beacon on its default settings. Just turn on the beacon (see the beacon’s Quick Start Guide page for instructions how to turn it on) and enter its MAC in the Data Entry Settings page of the MotherDuck. Adjusting the beacon settings and the MotherDuck settings at the same time gets confusing.
  • Adjust ONE data setting type at a time. Adjust it, then test with Practice Mode. Step by step adjustment of a single data setting type is slower at first, but will save you lots of time in the long run.
  • Don’t forget to turn off the BLE scanner on the Data Entry Page before you start to enter and submit the various data settings (otherwise the webpage will have trouble loading and the MotherDuck will frequently restart). This will make the data entry process go much more smoothly as it allows the MotherDuck to focus on data entry while the resource-intensive beacon scanning is turned off. Don’t forget to turn the BLE scanner back on when you are finished adjusting the settings.

Step 1: Connecting the MotherDuck to your local wifi network

In order for the MotherDuck to work, it needs a connection to your local wifi network and the internet. The following short video shows how to input your wifi network credentials (your network name and your wifi password) into the MotherDuck. During this process, before you enter your wifi credentials, the MotherDuck will require you to enter the MotherDuck’s password which is bluecharm; see the video around the 20 second mark:

If you are not a fan of video instructions, here are the same step-by-step instructions covered in the above video:

  • Step 1A
    -Connect the MotherDuck to USB power (either your computer or with the included power adaptor).
    -If the MotherDuck has no stored local wifi credentials, both the red and the green LED will blink simultaneously once per second (medium speed), indicating that the MotherDuck is ready to receive your local wifi credentials. The MotherDuck will now create a little wifi “access point” for you to connect to with your smartphone or computer.

Troubleshooting: This “access point” will remain open for two minutes. After two minutes, if no wifi credentials have been entered and saved, the red LED will blink very fast for 30 seconds, then the red LED will light continuously for 5 seconds, finally the MotherDuck will automatically restart.

  • Step 1B
    -Open your smartphone and go to your wifi settings the same way you normally do to connect to a new wifi network in your local coffee shop.
    -Look for a wifi network called Blue Charm Gateway Config. (See image below)
    -If Blue Charm Gateway Config does not appear, check that the MotherDuck red and the green LEDs are blinking simultaneously once per second; if not, restart the MotherDuck by disconnecting and reconnecting to your power source. You may also need to turn the smartphone’s wifi off and on again to refresh the list of networks. Sometimes this needs to be done a couple of times, depending on the type of smartphone and operating system.
    -Select that network and enter the MotherDuck’s password bluecharm when prompted by your phone.
Wifi settings on your computer or smartphone after you have started up the MotherDuck
  • Step 1C
    -After your phone is connected to the Blue Charm Gateway Config network, a page will appear on your phone entitled “Blue Charm Gateway Config” (see image below) with instructions to “Click the button below to configure the gateway to connect to your local wifi network”. Click the button “Configure Wifi” on the screen.

Troubleshooting: Some phones might not automatically take you to the configuration webpage after you connect with the Blue Charm Gateway Config network. If so, while connected to the Config network, open up a browser on your smartphone and enter 192.168.4.1 in the web address box to access the configuration webpage.

  • Step 1D
    -On the next screen (see image below), you will see a list of nearby wifi networks. Tap on the name of your local wifi network (only compatible with 2.4GHz networks), which will automatically fill that name in the box below, then fill in your network password below that. Tap on the Save button at the bottom of the screen.

-The next screen will show “Credentials Saved”, and the Mother Duck will try to connect to that network. (See image below)

-If it successfully connects, the MotherDuck’s green LED will flash quickly for 5 seconds. (See image below)

-Once the green LED has flashed quickly for 5 seconds, indicating that the MotherDuck has connected to your local wifi, tap cancel on the upper right corner of the screen to allow your phone to disconnect from the Mother Duck and to reconnect your phone to your wifi network. Some phones will do this step automatically so you won’t need to tap cancel.

-Congrats! You have now stored your local wifi credentials into the MotherDuck. These will be saved and reused every time you power up the MotherDuck. If your local wifi credentials stay the same, you will never have to do this step again.

Next time you power up the MotherDuck, after a few seconds, the green LED will flash quickly for 5 seconds, indicating that the MotherDuck has successfully connected to your local wifi and has begun normal scanning.

If the MotherDuck ever loses connection to your wifi network, the red LED will continuously flash very fast.

Changing Wifi Settings: Oops, you stored some wifi credentials into the MotherDuck, but now you changed your mind and want to input different credentials. How do you erase the existing credentials? Open up the MotherDuck housing and locate the black button near the spot where the antenna enters the housing. See the button circled in red below:

Hold down the red circled black button for 5 seconds to erase existing wifi settings

Hold that button down continuously for 5 seconds then release when both LED’s begin to simultaneously flash very fast. The existing wifi settings have now been erased. You can now enter new settings by following the Step 1 instructions above.

Step 2: Entering your beacon ID numbers and scanning parameters into the MotherDuck

Suggestion: Read through the data entry steps below, but please don’t start to enter any data yet if this is your first time. Just get a basic understanding of the possible settings. Then when you get to Step 3 below, you can enter the data suggested in that step and try using Practice Mode first.

In order for the MotherDuck to know which baby ducks (a.k.a. beacons) to watch and what to do when she sees them, you need to enter this information into the MotherDuck Data Entry webpage. The following short video shows how to input your beacon data and scanning parameters into the MotherDuck:

If you are not a fan of video instructions, here are the same step-by-step instructions covered in the above video:

  • Step 2A
    -Using any device (computer or smartphone) that is connected to the same wifi network as the MotherDuck, open up a browser and enter 192.168.0.99. This will take you to a webpage that is being hosted/served by the MotherDuck.
  • Step 2B
    -On this webpage, you will enter the ID number and other scanning parameters for each beacon that the MotherDuck will monitor.
    –Note that it is strongly recommended that before doing any data entry on this page, you should first use the menu at the top of the page to temporarily deactivate the scanning process (where it shows “Turn OFF or ON BLE scanner”). This will release resources to the processing of this web page data entry and make it function much more smoothly.

Troubleshooting: After entering each piece of data on this webpage, you will need to click on the submit button for that data. This will store this data in the MotherDuck and reload the webpage. If your webpage is not reloading and/or frequently getting stuck half way during reloading, you probably have not deactivated the scanner. Please do so using the menu selector at the top of the data entry webpage where it shows “Turn OFF or ON BLE scanner”.

Using Beacon #1 as an example, here’s a brief description of the types of data you need to enter and how this data will effect the performance of the MotherDuck:

Beacon #1 MAC
Current Value: (once you have entered and submitted a value for this parameter, the stored value will show here)
Required Format: Must start with dd, and have 17 total characters including 5 colon marks. MACS are comprised of digits 0~9 and lower case letters a~f. So anything that looks like a 0 is the number 0 not the letter O.
ALERT: MAC address letters should all be entered in lower case, not upper case.
Enter your first beacon’s MAC ID number here. You can find the MAC ID number of your beacon printed on the back of the beacon. Click SUBMIT to save it.

Be sure to only enter one data item at a time, then click SUBMIT next to that item. It is not possible to fill in all the parameter boxes and then click SUBMIT to save them all at the same time.

Reminder: The MotherDuck is only compatible with Blue Charm Beacons’ products BC011, BC021, BC08, and/or BC-U1. It is not compatible with our other beacon products and is also not compatible with beacons by other manufacturers.

WebHook for Beacon #1 when IN range
Current Value: (once you have entered and submitted a value for this parameter, the stored value will show here)
Required Format: Must start with https:// not http://. Maximum length of 130 characters
Enter the webhook URL here that you want the MotherDuck to fire when Beacon #1 comes into range. Click SUBMIT to save it.

WebHook for Beacon #1 when OUT of range
Current Value: (once you have entered and submitted a value for this parameter, the stored value will show here)
Required Format: Must start with https:// not http://. Maximum length of 130 characters
Enter the webhook URL here that you want the MotherDuck to fire when Beacon #1 goes out of range. Click SUBMIT to save it.

Deeper Dive: Webhooks are simple URL’s the same as regular URL’s such as https://cnn.com. The difference is that webhooks don’t take you to a web page, but instead trigger another app or system connected to the internet. For example:

-IFTTT: this popular app allows you to create webhooks that will trigger some action from the IFTTT app. Once IFTTT receives the webhook over the internet, it could perhaps send you a notification, or turn on your music, or turn on a light, or turn off a light, or whatever else you can imagine. IFTTT also works with a large number of smart home devices. Plus, you don’t even have to have your phone turned on or be at home; IFTTT’s platform works even if your phone is turned off or you’re not at home.

-Depending on your smart home system, you can skip the IFTTT step (and have slightly faster reactions) if you set up a webhook directly within your smart home system, then have the MotherDuck send that webhook when a certain beacon comes into range. And a different webhook when it goes out of range. Your smart home system can then trigger automations according to your system settings.

For example, the Hubitat smart home system allows you to activate their built-in Maker API, then to setup webhooks that will trigger the available automations within the Hubitat. All you need to do is enter those webhooks into your MotherDuck to make these automations happen when a beacon comes into and/or out of range of the MotherDuck.

Beacon #1 IN Range RSSI threshold
Current Value: (once you have entered and submitted a value for this parameter, the stored value will show here)
Required Format: negative number from -99 to -1; typically set this around -65 for a 2 meter range but adjust as needed for your usage case. Each usage case is unique, so you will need to test which setting here best fits your case!
Enter the RSSI signal strength threshold value that the MotherDuck will require to consider Beacon #1 to be out of range. Click SUBMIT to save it.

Beacon #1 OUT of Range RSSI threshold
Current Value: (once you have entered and submitted a value for this parameter, the stored value will show here)
Required Format: negative number from -99 to -1; typically set this around -80 for a 4 meter range but adjust as needed for your usage case. Each usage case is unique, so you will need to test which setting here best fits your case!
Enter the RSSI signal strength threshold value that the MotherDuck will require to consider Beacon #1 to be out of range. Click SUBMIT to save it.

Deeper Dive: Having two different input values for IN range and OUT of range allows you to reduce possible over sensitivity of the MotherDuck’s reactions. Imagine if you set both the IN and OUT range numbers to -50. As the beacon signal wavered (as normal for BLE signals), you might get an “In Range” reaction one second, then “OUT of range” the next second, and so on and so on. Too sensitive!

But if you set the IN number at -45 and the OUT number at -60 (for example), you create a nice buffer between the two reaction zones. The beacon signal would need to be -45 (or higher) before the MotherDuck would send the “IN” webhook, and it would need to be -65 (or lower) before the MotherDuck would send the OUT webhook. In other words, the beacon would need to have moved some significant distance away from the MotherDuck.

Beacon #1 Missed Scan Interval (in milliseconds)
Current Value: (once you have entered and submitted a value for this parameter, the stored value will show here)
Required Format: regular number from 1000 to 100000; typically set this around 5000.
Enter the number of missed scans that will be required before the MotherDuck considers Beacon #1 to be “missing in action” and therefore marked as out of range. Click SUBMIT to save it.

Deeper Dive: Imagine the MotherDuck is keeping an eye on a beacon and waiting for it to go out of range. It sees the beacon’s signal over and over again, but the signal strength has still not quite reached the OUT of range zone. Suddenly, the beacon moves away so quickly (perhaps in a car) that the MotherDuck never receives another signal from the beacon. Since the beacon signal never reached the required OUT level, the MotherDuck would do nothing. Hmmm…that’s not what we want.

With the Missed Scan Interval setting, you can address this potential issue by adding a Missing timer. For example, if you set the Missed Scan Interval to 3000ms (3 seconds), and the MotherDuck receives no signal from the target beacon for 3 seconds, she will automatically consider the beacon to be out of range and send the OUT webhook.

By the way, this also makes it possible to manually turn the beacon OFF (only beacons with an OFF button, of course), and 3 seconds later, the MotherDuck would send the OUT webhook. I can think of a couple interesting projects that could use this setup. You could even use our USB-powered beacon plugged into a USB outlet in your car. When you shut off the car engine, the USB would also be shut off, and 3 seconds later, the MotherDuck in your garage would send the OUT webhook.

Beacon #1 Consecutive In Range Counts Required
Current Value: (once you have entered and submitted a value for this parameter, the stored value will show here)
Required Format: regular number from 1 to 100; typically set this around 3.
Enter the number of consecutive “in range” RSSI values required before the MotherDuck considers Beacon #1 to be in range. Click SUBMIT to save it.

Beacon #1 Consecutive Out of Range Counts Required
Current Value: (once you have entered and submitted a value for this parameter, the stored value will show here)
Required Format: regular number from 1 to 100; typically set this around 3.
Enter the number of consecutive “out of range” RSSI values required before the MotherDuck considers Beacon #1 to be out of range. Click SUBMIT to save it.

Deeper Dive: All BLE signals experience some interference from other things in your environment. In the same way, watch the signal strength bars on your smartphone, and you will notice that they often move around quite a bit also (even though they are really much much broader bands and shouldn’t move at all). Both beacons and smartphone signals are influenced by the environment, obstacles, other signals, appliances, ghosts, etc.

As a result, the signal strength of any beacon will vary over time even when the beacon is stationary. So, for example, you might get a stream of signal strength numbers such as -50, -52, -49, -52, -51, -70, -54, -53, -49, -50, etc. Did you notice the quirky -70 that popped up in there? If you had set your OUT RSSI threshold for this beacon at -69, the MotherDuck would have sent at OUT webhook when it saw this -70 oddball reading even though the beacon was still in range. Of course, you could simply adjust the OUT RSSI threshold to -75 and avoid this issue, but that might make the OUT range distance too far for your project.

To address this potential issue, the MotherDuck allows you to set a required number of consecutive counts OUT or IN before the MotherDuck will send the appropriate webhook. In the example above, if you had set the Consecutive Out of Range count to 2, the MotherDuck would have ignored the single oddball -70 reading that randomly popped up due to signal interference.

Step 3: Using Practice Mode

Here’s a short video showing how Practice Mode works.

Before starting this demo, on the MotherDuck data entry page, I have set the MotherDuck BLE scanner to ON, and the Practice Mode to ON as well. So the MotherDuck is not sending webhooks, but instead is simply lighting the green LED for IN range and red LED for OUT of range.

At the beginning of the demo, the MotherDuck green LED is slowly flashing, indicating normal scanning. But the beacon is not turned on yet, so the MotherDuck can’t “see” it. Once I press the button on the beacon to turn it on, the MotherDuck quickly spots it, concludes that it is IN range according to the data settings for Beacon #1, and then lights the green LED continuously.

When I pick up the beacon and move it away (I put it behind my back in this demo), the MotherDuck still sees that the beacon is there, but it is past the threshold for OUT of range. The MotherDuck then lights the red LED to indicate that the beacon is OUT of range.

Notice at the end that I turn the beacon off, and after the Missed Scans Interval time has elapsed, the MotherDuck lights the red LED to indicate the beacon is out of range (in this case, it is actually “missing in action”, but the MotherDuck treats that the same as out of range). Finally, I turn the beacon back on and the MotherDuck quickly lights the green LED to indicate that the beacon is back in range again.

MotherDuck data settings for Beacon #1 used during this demo

Beacon #1 IN Range RSSI threshhold: -50
Beacon #1 OUT of Range RSSI threshhold: -65 (hold the beacon behind your back if you don’t want to walk away)
Beacon #1 Missed Scan Interval (in milliseconds): 4000
Beacon #1 Consecutive In Range Counts Required: 1
Beacon #1 Consecutive Out of Range Counts Required: 3 Beacon used for demo: BC-021 on default settings

How to use Practice Mode

At the top of the Data Entry Webpage, you may have noticed a setting called “Practice Mode”. Practice Mode allows you to get a simple-to-understand visual signal from the MotherDuck when Beacon #1 comes into range or out of range. So instead of the MotherDuck firing a webhook when the beacon range state changes, it will simply light the green LED (in range) or red LED (out of range).

The IN/OUT indication is based on the settings of Beacon #1, so this is a great way for you to develop a feel for how adjusting certain settings will effect the reaction of the MotherDuck. For example, how will changing the IN range setting from -50 to -70 effect the distance from the MotherDuck? Or how will changing the “consecutive out of range readings reduce” false OUT reports from the MotherDuck? Practice Mode is a great way to build a “feel” for each of the settings.

Keep in mind that there are no universally “correct” settings. It always depends on your project goals. For example, you might carry Beacon #1 around in your pocket to trigger the lights on/off around your house. In that scenario, you would probably want the lights in the office to turn on before you reach that room so you can see where you are going. So you would set the IN range quite far. You would probably also not want the lights to ever turn off while you are sitting in the office, so you might set the “Consecutive Out of Range Counts Required” to 10 to be 100% sure the lights don’t go out until you have truly left the office. That’s just one simple example, but you can easily see that the goals of each automation will determine the “correct” settings for that particular beacon/automation.

Practice Mode also allows you to test out the MotherDuck independent of your home automation webhooks. For example, if you are not getting the automation result you expected, you can use Practice Mode to first confirm the MotherDuck is performing as expected. Then you can focus on the webhook or your home automation hub system to solve the problem from that end.

Note that Practice Mode only works for Beacon #1 and for the settings of Beacon #1.

The activate Practice Mode, go to the MotherDuck Data Entry webpage and turn ON Practice Mode then turn ON the BLE Scanner.

Last but not least, contact us any time if you have any questions or suggestions!