Qblinks Qmote Maker s Module Developer Guide

Size: px

Start display at page:

Download "Qblinks Qmote Maker s Module Developer Guide"

Wendy Walton
5 years ago
Views:

1 Qblinks Qmote Maker s Module Developer Guide This document is for Qmote Developers and Community Revision Information V0.1/2015-APR-16 Init Draft V1.1/2015-JUNE-18 Reduced output message length V1.2/2015-JULY-2 Added status of HID CCC V1.3/2015-JULY-15 Added status of Bonding Keys Full V1.4/2015-AUGUST-6 Added AT+BF command V1.5/2015-AUGUST-27 Added button combination code list V1.6/2015-AUGUST-31 Added antenna wire on drawing to indicate the module orientation V1.7/2015-NOVEMBER-3 Added ANCS support and QPS to UART command V1.8/2015-NOVEMBER-19 Removed Firmware OAD section was moved to another document. V1.9/2016-FEBRUARY-24 Added ANCS Auto Action support V1.10/2016-DECEMBER-28 Added ATZ8 command, for the firmware version 2.21 and later

2 Introduction Qmote Maker s Module is the world s first Bluetooth Low Energy Module that allows you connect your DIY development board and kit to all of the major Smart Home products in the market, as well as most social network platforms without doing any coding. Qmote Maker s Module is functionally the same as the standard Qmote with additional extensions designed for makers. It can send commands to control your Smartphone. It is also compatible with IFTTT, so you can make your development board work with the hundreds of other channels. It is easy to use Qmote Maker s Module. You don t need to have any App or Cloud programming skills. Simply send commands from your development boards through UART to Qmote Maker s Module. Please Note: Apple Notification Center Service (ANCS) is not supported until firmware To get your Qmote Maker s Module upgraded, please refer to Specifications Main Chipset TI CC2541F256 Protocol Standard Bluetooth V4.0 Low Energy Transmit Output Power -6 Output Power +4; Class 2 Device Receiver Sensitivity < 0.1% BER at -70 dbm Operating Voltage 3.3V ± 0.3V Power Consumption TX: 14mA; RX: 14mA

3 Module Introduction Qmote Maker s Module is only 17 mm by 18 mm (0.67 inch by 0.7 inch) in size. The pitch of the hold is the standard 2.54 mm (0.1 inch), which fits most standard pins. Figure 1 Qmote Maker s Module dimensions (unit: mm) Figure 2 Pin assignment

4 Pin Assignment GND Vdd(3.3v)!RESET!LED!Button!keep_alive_disable RX/TX (3.3v) 5v (Level Shifting) RX/TX (5v) Ground Supply Voltage Reset, active low LED indicator, active low Push Button, active low Disable advertising Keep-Alive, active low (Low for no keep-alive) UART RX/TX with 3.3v TTL Input for 5v TTL level shifting, this is not for BLE voltage supply UART RX/TX with 5v TTL Reset/LED/Button All the three functional pins are active low. Here is the sample schematic: Figure 3 LED/Button/Reset Pin

5 Level Shifting The operating voltage of Qmote Maker s Module is 3.3v. However, IO of most DIY boards use 5v logic. That is why Qmote Maker s Module provides the 5v level shifting for the UART. The input of 5v is for the level shifting only. You still need to provide 3.3v to drive the Bluetooth core. Figure 4 Work with Arduino Uno Keep-Alive By the default, Qmote Maker s Module remains advertising all the time. If keep-alive is disabled by grounding the!keep_alive_disable pin, the Module will work as the standard Qmote. The standard Qmote disconnects the connection if there is no button activity. If!Button keeps grounded (push-and-hold) in the keep-alive mode, it will generate the push code again every time when the Module is re-connected. For example, if you want to make a simple incoming mail envelope sensor (for a physical mailbox), use the keep-alive mode (by leaving the!keep_alive_disable pin open) and use a coin sensor for the!button pin. Once there is an envelope, the coin sensor will be pushed and remain pushed. When you walk by your mailbox with your

smartphone, the Module reconnects to your phone and the Qmote App will be triggered with the find-phone alarm. Figure 5 Coin sensor Please note,!keep_alive_disable pin is NOT an on-the-fly toggle.

6 smartphone, the Module reconnects to your phone and the Qmote App will be triggered with the find-phone alarm. Figure 5 Coin sensor Please note,!keep_alive_disable pin is NOT an on-the-fly toggle. If the state is changed in the middle of the process, the Module needs to be reset in order to load the new configuration. In addition, the button code regeneration works for the physical!button port only. The AT command generated button code does not apply. Through AT commands, the control program shall check the GATT status and wait for the In-Process message if the Module is disconnected. TX/RX UART The baud rate configuration of UART is 38400,N,8,1. If you are working with Arduino soft serial, please use the software package with a higher performance. For example: AltSoftSerial : The original Arduino softserial has some performance issues for the applications using baud rate higher than AT commands are used to control Qmote Maker s Module. Please refer to the AT commands section for more details. ANCS Enable To enable Apple Notification Center Service, simply ground the ANCS_enable pin. This is not an on-the-fly toggle. Once it is changed, the module requires a restart to take the new configuration. When ANCS is enabled, this module always works in Keep-Alive mode. ANCS_auto_action is to select if ANCS-auto-action is enabled or not. To enable, ground the ANCS_auto_action pin, otherwise, it is disabled by the default.

7 AT Commands AT commands comprises of three parts. AT, followed by a command, and a termination character <cr>, which means Carriage-Return. The command will be processed after the <cr> is sent. The response from each command varies. In general, a successful command will respond with OK. For example, if you send AT<cr>, you will get <cr><lf>ok<cr><lf>. AT<cr> <cr><lf> OK<cr><lf> Note: <cr> is ASCII 0x0D, <lf> is ASCII 0x0A. <lf> from input will be ignored. AT commands summary Command Descriptions Possible Response ATI0 Get the device information INFO: <device info> ATI1 Get the firmware version number INFO: FW <ver> ATI2 Get system clock INFO: CLOCK <clock> ATE0 Local UART echo off OK ATE1 Local UART echo on (default) OK ATZ0 Force Commit (NVRAM) OK ATZ1 Reset configuration (of current OK connected device) ATZ3 Software Reset OK and device will be reset ATZ5 Reset and Enter OAD mode OK and device will be reset ATZ7 Total Factory Reset. This erase everything from Qmote configurations OK and device will be reset to all Bluetooth exchanged bonding keys. ATZ8 Switch to Keyboard Presenter mode. This is a one-way function. Once the mode is switched to the Keyboard Presenter mode, only Total Factory OK and device will be reset

8 Reset can restore it back to the default mode, Mouse Presenter mode. If the device has been paired before the mode switch, un-pair and pair it again is needed to use the Keyboard Presenter. ATX0 Force non-presenter mode OK ATX1 Force presenter-mode. One-click and OK two-click will not trigger the actions on Qmote app. ATL1=n Start LED blinking for 60 seconds, where OK n 0: Just once 1: Slow 2: Medium 3: Fast 5: Non-Stop ATL0 Stop LED blinking OK ATL2=n Set button response time, where n is one byte hex number OK or Err if value is incorrect 0x80~0xFF slow 0x00 normal 0x01~0x7F faster This uses 2 s compliment 0x x x7F ATBN=n Send button combination code n, where n is in the hex format. E.g. ATBN=0x01 OK or Err if combination code is invalid Remember to send release code by ATB0 afterward. Otherwise, it will be considered as button on-hold. Note: Button on-hold through AT command will NOT trigger on-hold phone finder. Use ATBN=0xFF for the find phone alert, instead. ATBN=0x0C Recall virtual keyboard. This works for OK ios only. Remember to send release code by ATB0 afterward. ATBN=0xFF This triggers the Find Phone alert. OK

9 Remember to send release code by ATB0 afterward to stop the alert. ATBN=n,<msg> Send button combination code with IFTTT message. The length of the message cannot exceed 19 bytes. Once <msg> is used, ATB0 will be sent OK or Err if the combination code is invalid or the message is too long automatically. In another word, this command cannot be used as the finder trigger. <msg> can be either ASCII message or 0xhex value. E.g. ATBN=0x01, TEXT or ATBN=0x01,0x1122 ATB0 Send button release code. This is OK identical to ATBN=0x00 ATH0 Terminate connection without OK re-advertising. Regardless of how!keep-alive is configured, the advertising will be stopped. ATH1 Enable advertising OK Note: If you issue this command when the device is connected, it will enter CONNECTED ADVERTISING mode ATH2 Disable advertising OK AT+BN=n,f Set F-code, where n is the button combination code and f is the F-code. OK or Err if n or f is invalid E.g. AT+BN=0x01,0x02 (assigned F-code 0x02 to the button combination 0x01) For more information about F-code and button combination, please refer to the Qblinks Qmote GATT Specifications document AT+BF=n Set Platform, where n is the platform ID. E.g. AT+BF=0x01 to set the platform to OK or Err if n is invalid or the device is not ready ios, AT+BF=0x00 to unset the platform. Please refer to the Qblinks Qmote GATT Specifications document AT+BI1 Show remote BD address BLE: <BD addr> or Err if

10 the device is not connected AT+BI2 Show current configuration BLE: <config> Note1: <config> is the same as the return of the Configuration Retrieve Characteristics of Qmote GATT Specifications Note2: Only the paired devices have the configurations AT+BI3 Show current GAP Role State BLE: <n> <desc>, where 0 INIT 1 STARTED 2 ADVERTISING 3 WAITING 4 WAITING AFTER TIMEOUT 5 CONNECTED 6 CONNECTED ADVERTISING 7 ERROR AT+BI4 Show bonding status BLE: <n> <desc>, where 0 DISCONNECTED 1 CONNECTED NOT PAIRED 2 BONDED AT+BI5 Show all NVRAM configurations BLE: <n>,<config>, where <n> is the number of the configuration set Note: Only the paired devices have the configurations AT+BP=p Set the Tx (Transmit) Power, where p is 0 = -23 dbm 1 = -6 dbm (default) 2 = 0 dbm OK or Err. Configuration can be set only when there is no RF activity Note: This configuration is not stored in the

11 AT+Q0 Output QPS-to-UART message in ASCII (Default) NVRAM. Every reset will restore the value to the default OK (Note1) AT+Q1 Output QPS-to-UART message in HEX OK (Note1) AT+ANCP=m Write to ANCS Control Point Write message m to Control Point (Note1)(Note2) AT+ANCS0 Disable ANCS output OK (Note1)(Note2) AT+ANCS1 Enable ANCS output OK (Note1)(Note2) AT+RSSI0 Disable RSSI output OK (Note1) AT+RSSI1 Enable RSSI output OK (Note1) AT+CK Request Time Service notification if time service is available OK (Note1) A/ Repeat the last command Repeat the last AT Note1: Supported by the firmware 2.07 or later. Note2: ANCS is supported on ios 7 or later. command regardless its result was an OK or an Error The Long-Click The long-click is turned off by the default until the long-click combination code is configured with a F-code. If you simply want to enable the long-click without any purpose, you can assign an unused F-code to any long-click button combination. For example, ATBN=0x05,0x99, to assigns F-code, 0x99, which is not functional, to the button combination code, 0x05, which is long-short.

12 In-Process Status Change The status of Qmote Maker s Module may be changed during the process. For example, when the connected central device (usually the phone) is away from the Module, then the status is changed to disconnected. Or when the central device is near the Module, the status is restored to connected. You will receive the In-Process Status Change message, so your program knows what is going on and can take action if needed. The message is composed as the following format: <cr>st: <code> <message><cr> For example, <cr>st: 1 CONNECTED<cr> Note: There is A SPACE between ST: and <code>, and another SPACE between <code> and <message> Message What happened 1 CONNECTED <remote BD address> Central device is connected, but not paired yet Note: At this stage, <remote BD address> shows only the paired phone. If a connected phone is new to this Qmote, it will not show. 2 PAIRED <remote BD address> Central device successfully paired 3 BONDING OK <remote BD address> Paired central device is reconnected 4 PAIRING FAILED Pairing failed, either by timeout or because user does not grant pairing permission 0 DISCONNECTED Central device is disconnected or connection is lost 5 BTN <combination code> Button Pressed. <combination code> is in the hex format. E.g. 0x01 6 BTN 0x00 Button Released 7 FINDER Finder triggered 8 HIDCCC This message indicates the OS HID is ready to receive command. This message happens only after central device is PAIRED or BONDING OK. Some Android devices do not have this message since

13 its HIDCCC is sent before CONNECTED. 9 BONDING KEYS FULL There have been more than 10 central devices paired. A Total Factory Reset is required. Note: Message 5/6/7 are from the physical!button port only. AT command button generation does not trigger those messages. Other In-Process Message (*1) QPS: <QPS-to-UART Message> Message sent from the QPS Command, 0x31 ANCS: 0 FOUND SERVICE Apple Notification Center Service is found. TIME: 0 TIME SERVICE FOUND Found Time Service TIME: 1 YYYYMMDDhhmmss Current time notification received. When the Time Service is found, the first notification will be sent. It can be retriggered by AT+CK command. RSSI: [signal strength] The signal strength of the connected central. RSSI information is a periodically output per 2 seconds. It can be enabled by AT+RSSI1 and be disabled by AT+RSSI0 *1: This is supported by the firmware 2.07 or later *2: There is a SPACE between : and the message number Button Combination Code List [Release] 0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07

14 0x08 0x09 0x0A Short-Click Long-Click Apple Notification Control Service (ANCS) Support Qmote Maker s Module now supports Apple Notification Center Service (ANCS). With ANCS, your Qmote Maker s module can obtain the notification information from your ios devices. To use ANCS feature, you will have to understand the format of ANCS. For more information regarding ANCS, please refer to: pplenotificationcenterservicespecification/introduction/introduction.html Qmote helps to relay the ANCS messages from/to your development board, so you can easily get the information of the notifications or perform a notification action on it. There are 5 types of ANCS messages that Qmote will generate: Message/Format What for ANCS: 0 SERVICE FOUND Indicates there is ANCS on this connected central ANCS: 1 [+->PN],[Category ANCS Notification Source information ID],[Notification Data] ANCS: 2 [Notification ID],[App ID] Decoded App ID of the notification ANCS: 3,[Notification ID],[Caller ID] This is for the incoming call only ANCS: 4,[Notification ID],[Attribute Result of the message sent to ANCS ID],[Msg Len],[The Msg] Control Point + : Added Notification - : Removed Notification > : Modified Notification P : This notification can be performed with positive action N : This notification can be performed with negative action [Notification ID]: is encoded as network order. ID to be sent to the Control Point shall

15 use the same order. [Category ID]: Please refer to the ANCS document. [Attribute ID]: Please refer to the ANCS document. [Notification Data]: Please refer to the ANCS document. Here are some examples: ANCS: 1 +PN,2,0x Notification Added, Can perform Positive and Negative action ANCS: 2 0x ,com.apple.mobilephone Notification ID, 0x , App ID com.apple.mobilephone ANCS: 3 0x , An incoming call from ANCS: 4 0x ,1,5,Gmail Notification ID 0x is Gmail This was actually generated by at+ancp=0x Perform notification action at+ancp=0x This will pickup the call associated with Notification ID 0x at+ancp=0x This will hang up the call associated with Notification ID 0x

16 ANCS Auto-Action When ANCS is enabled, you can choose if you want the module to perform a build-in functions, ANCS-Auto-Action. When ANCS-Auto-Action is enabled, by grounding the ANCS_auto_action pin, the module automatically sends click patterns to Qmote App when there is notification received. The click pattern sent to the Qmote App is based on the ANCS notification category ID, as the following table Category ID Notification Source Click Pattern to Send 1 Incoming Call(*) (0x01) (0x0A) 2 Missed Call (0x02) 4 Social/SMS/iMessage (0x03) All Others Other than above (0x04) [CLEAR] Notification Clear(**) (0x05) Note: * Incoming Call generates two click patterns. The (0x0A) one also includes the caller ID as the UART message sent to the Qmote App ** Notification Remover of any category generates the same click pattern. The beauty of ANCS Auto-Action is that you don t need to write a single line of code to use the notification to trigger some events. For example, your incoming call can trigger the LIFX lighting. For the real application, please refer to the DevKit of Qblinks.com, the Maker s Project 5.

17 How to upgrade Qmote firmware Qmote supports Firmware-Over-The-Air. You may need to perform the firmware upgrade to have the latest features. To upgrade the firmware, you need to download Qblinks Qmote Upgrade Tool on ios. Please refer to Qblinks Support at for more information.

+ (5~27 VDC) GND. Bluetooth V4.2 BLE RS-422/485 Serial Adapter. Model: BLE-485C. 1. Package content: BLE RS-422/485 adapter

+ (5~27 VDC) GND. Bluetooth V4.2 BLE RS-422/485 Serial Adapter. Model: BLE-485C. 1. Package content: BLE RS-422/485 adapter Bluetooth V4.2 BLE RS-422/485 Serial Adapter 1. Package content: BLE RS-422/485 adapter Model: BLE-485C Package Contents: BLE 422/485 adapter x 1 Screw x2, Screw nut x 2 A4 User manual x 1 Mini USB Cable