Very Brief Description:
The BCG04 gateway scans for beacons, collects their basic broadcast data, and sends that data to your preferred MQTT or HTTP server.
To configure the gateway, you will first connect to it using a special app called KGateway. The app will first ask you for your local wifi password.
The app will then show you any Blue Charm gateways nearby your phone, and you can choose which gateway to add to the app.
Once you select the gateway to add, the app will ask you to input the configuration for that gateway.
After entering that info, you click on Complete, and you’re all done. The gateway is now scanning and sending the collected data to the cloud according to your configuration.
1. Download the KGateway app
Download the App named ‘KGateway’ from the iOS App Store or the Android Google Play store or scan the applicable QR code below to download the App. The phone will ask you to allow Location Services the first time you open the app or when you install it; be sure to click OK. The app is not actually using your location for anything, but smartphones require location permission in order to activate BLE services (which the app needs to connect to the gateway).
Minimum system requirements:
Android version > 10.0; iOS version > 13.0
2. Open the KGateway app
Click on the “+” sign.
3. Read the preparation page
Double click the button on the gateway, then tap NEXT on the bottom of the app screen.
4. Input your wifi password
The app automatically fills in the wifi network that your phone is currently using. Be sure this is a 2.4GHz network, since the gateway is only compatible with 2.4GHz wifi networks. In some cases, you may need to connect your phone to 2.4GHz network temporarily in order to send/teach this 2.4GHz network name and password to the gateway, then afterwards you can set you phone back to your regular 5GHz wifi network.
Understanding the LED indicator on the gateway:
Red light flashing rapidly: The gateway has entered network configuration state whereby you can now use our app to configure the wifi network that the gateway will use.
Red light flashing slowly: The gateway has successfully connected to Wi-Fi and is trying to connect to the server.
Red light remains on: The gateway is connecting to Wi-Fi.
Green light remains on: The gateway has successfully connected to the cloud server.
5. Wait for app to scan and find your gateway, then tap on it on the screen
It may take up to 30 seconds to scan and find your gateway.
6. Begin the provisioning process a.k.a. enter the configuration settings for the gateway
Before we continue, for your reference, there is a section further down this webpage (entitled “Some important tips and notes about the various configuration settings”) which goes into more detail about the configuration settings you will enter in this next step. Don’t worry about it for now. Let’s first get a basic configuration of the gateway done first.
In the screenshots below, I have chosen the MQTT tab at the top of the page since I will configure the gateway to send its collected beacon data to the cloud via MQTT. Alternatively, you could choose the HTTP tab. You only need to choose one or the other (in fact, you can only use one method). Then when you are finished entering all the data on that specific tab, scroll to the bottom of the page and tap the CONFIGURATION button.
Note that the data I have entered in the screenshots below is applicable to my MQTT server and my specific beacon and gateway. Your data will be different from this example. Further down this page, you will find more details about MQTT. Update: For you HA users, the screenshot below shows the URL as homeassistant.local. This worked up fine until a recent HA update. Now it needs to be only homeassistant, i.e. remove the .local.
7. Enter a name for the gateway
Enter your preferred name for the gateway then tap COMPLETE at the bottom of the screen.
8. Tap OK on the pop-up message to give the gateway permission to reboot in order to save all your settings to the gateway
9. The Device List app page will now show your gateway.
Sometimes it might have a “not configurable” message next to the gateway name on the Device List page. Just wait a few seconds and it will change to “configurable”. Or double click the button on the gateway.
10. To reconfigure the gateway settings at some time in future:
Tap on the gateway name on the Device List if you want to change the configuration of the gateway at any time. The screen shown below will appear. Then tap on Device Settings.
Note: Some finicky wifi networks will require your phone to be connected to the same wifi network as the gateway in order to reconfigure the settings. While others are more forgiving as long as you are connected to some other node of the same internal wifi network. For example, your phone might be connected to your 5GHz network, while the gateway is connected to your 2.4GHz network. If you are having trouble, try connecting your phone to the same 2.4GHz network as the gateway is connected to. And of course, there’s always the “unplug the gateway, wait 5 seconds, then plug it back in again” method for solving many problems.
Some important tips and notes about the various configuration settings
Understanding the LED indicator on the gateway:
Red light flashing rapidly: The gateway has entered network configuration mode.
Red light flashing slowly: The gateway has successfully connected to Wi-Fi and is trying to connect to the server.
Red light remains on: The gateway is connecting to Wi-Fi.
Blue light remains on: The gateway has successfully connected to the cloud server.
MQTT Server Parameters:
| Parameters | Defaults | Description |
| Host address | (based on your server) | The MQTT cloud address. |
| MQTT port | (based on your server) | |
| Client ID | mac address of the BCG04 | MQTT client ID |
| Name | (based on your server) | MQTT client user name |
| Password | (based on your server) | MQTT client password |
| Qos | Qos 0 | Qos 0: Best effort for MQTT report Qos 1: The message will be sent to ensure that it can be received by the subscriber, but the subscriber may receive it repeatedly due to message retransmission. Qos 2: The message will be sent to ensure that it can be received by the subscriber, but also to ensure that the subscriber does not receive the same information repeatedly. |
| Keep alive interval | 120 seconds | The time-to-live interval as defined by the MQTT protocol. |
| Publish topic | bluecharm/publish/{mac} | The topic used by the gateway to publishing data to the MQTT server. {Mac} is the MAC address of the gateway |
| Subscribe topic | bluecharm/subaction/{mac} | If the server needs to send a configuration request to the gateway, it will send that request through this topic. You will most likely not use this at all. {Mac} is the MAC address of the gateway |
| Response Topic | bluecharm/pubaction/{mac} | If a configuration request is sent to the gateway, the gateway will send an execution result message through this topic. You will most likely not use this at all. {Mac} is the MAC address of the gateway |
| Upload interval | 1 second | The gateway uses this parameter to control the upload period of modified advertisement data of your beacons to the cloud. |
MQTT with SSL:
The BCG04 supports the following SSL methods:
SSL with CA certificate
The gateway needs to verify the server’s CA certificate. You need to deliver the server’s CA certificate to the gateway.
SSL with self-signed certificate
The gateway needs to verify the server’s CA certificate. Your server also needs to verify the CA certificate on the gateway side.
SSL without certificate
The gateway and the server use SSL encrypted communication, but the gateway does not verify the CA certificate of the server, and there is a possibility of middle attach in this way.
How to upload the certificate to the gateway
When you choose to use certificate-based SSL, the APP will add a menu item for you to choose to upload a certificate. Click the menu to enter the upload certificate page.
When entering the upload certificate page, you can choose to copy the certificate into the text box, or you can choose to download the certificate from the specified URL. Then click upload to upload the certificate to the gateway.
HTTP Configuration:
The HTTP protocol adopts a request/response model. The client sends a request message to the server, and the request message contains the requested method, URL, protocol version, request header, and request data. The server responds with a status line containing the protocol version, success or error code, server information, response headers, and response data.
| Parameters | Defaults | Description |
| URL address | (based on your server) | URL of the HTTP server |
| HTTP Basic authentication | no | yes or no |
| Name | (based on your server) | Http Basic Authentication Username |
| Password | (based on your server) | Http Basic Authentication Password |
| Upload interval | 1 second | The gateway uses this parameter to control upload period of modified advertisement data of your beacons to the cloud. |
HTTP with SSL:
When using HTTP access, the HTTPS protocol is supported. Please make sure the URL address begins with “https://” if you would like to use SSL with HTTP.
The SSL configuration in HTTP mode is the same as the SSL configuration in MQTT mode, so please refer to the “MQTT with SSL” section above.
Scan Settings:
| Parameters | Defaults | Description |
| Scan interval | 100ms | Bluetooth scan interval in milliseconds. This is how long between the start of each scan period. 1000ms or longer is recommended for typical beacon scanning. |
| Scan duration | 100ms | Bluetooth scan windows in milliseconds. This is how long the start of scan period lasts. The scan duration/window parameter should not be larger than the scan interval. When the two parameters are equal, the scan duty cycle will reach 100% but typically it is advised to set the scan duration at 90-95% of the scan interval. For example, if scan interval set to 1000, then scan window should be set to 900 or 950. This allows the scanner some time/resources to use the wifi channel for data reporting to the server. |
| Filter RSSI | -100 | When the received broadcast message signal is smaller than the filter value, the message will be discarded. For example, when this parameters set to -67, weak signals below -67 will not be uploaded to the server. The filter is not often used. |
| Mac List | NA | You can scan the QR code sticker on Blue Charm beacons (or type it in manually) in order to specify the target Mac address here for filtering. The maximum number of MAC addresses that can be filtered is 15. Filtering for targeted MAC addresses is highly recommended, otherwise the scanner will scan everything around you and load all of that unneeded data to the cloud server. |
| Mac RegEx | NA | Another type of filter. Regular expression for BLE MAC address. For example, if you only want to receive BLE MACs starting with BC5729, the regular expression is: ^BC5729* (Note: the gateway can only recognize uppercase raw data strings). The filter is not often used. |
| Raw data | NA | Another type of filter. Regular expression for BLE raw data. For example, if you only want to receive BLE raw data starting with 020106, the expression is: ^020106* (Note: the gateway can only recognize uppercase raw data strings). The filter is not often used. |
Caching BLE Data:
Since wifi network connections may sometimes be unstable, The BCG04 gateway has the ability to cache messages. For example, when sending data to the cloud fails, the BCG04 will cache the message to the local buffer. It can cache up to 1000 BLE broadcast messages. When the network recovers, the BCG04 will report the cached messages.
If the number of cached broadcast messages exceeds 1000, the oldest message will be deleted.
Time Parameter:
| Parameters | Defaults | Description |
| NTP zone | UTC-0 | When the BCG04 uploads BLE message data to the server, it will carry a timestamp. The time zone of the timestamp can be configured through this parameter. We set ours to UTC-8 for our Oregon time zone. |
| NTP server | pool.ntp.org | NTP time server |