Supported Bluetooth Protocol
Bluetooth is provided on Ultra Stream, which makes the device discoverable to nearby device. With Bluetooth, exchanging data between streamer and other device is available.
Supported GATT Service
1.Service: Device info(0000180a-0000-1000-8000-00805f9b34fb)
Use the Service to obtain the device profiles. Characteristic is shown in the following table.
| UUID | Description |
|---|---|
| 00002a29-0000-1000-8000-00805f9b34fb | Manufacturer Name: MAGEWELL |
| 00002a24-0000-1000-8000-00805f9b34fb | Product model, such as ULTRA STREAM HDMI |
| 00002a25-0000-1000-8000-00805f9b34fb | Serial number, such as C301170101001 |
| 00002a26-0000-1000-8000-00805f9b34fb | Hardware revision, such as 1.3.11 |
2.Service: GATT(e20a39f4-73f5-4bc4-a12f-17d1ad07a961)
GATT is used for data exchange, including obtaining device information, password authentication, Wi-Fi configuration, enabling device ap mode, and obtaining ap information.
| UUID | Name |
|---|---|
| 08590f7e-db05-467e-8757-72f6faeb13d4 | Buffer-0 |
| f4be124e-4cdc-43e2-a6bb-8628e4009e6b | Buffer-1 |
| 1de1bf3d-1bbe-43aa-9a30-b2bb5ce9671d | Buffer-2 |
| 8d7bd67d-d0b3-4a5e-8d2b-2912af174a7d | Buffer-3 |
| 3a10340a-85e3-4190-86b4-b94dc505e4f8 | Buffer-4 |
Bluetooth Low Energy Advertising
BLE Name: It is fixed as 13-character device serial number, with a capital alphabetic prefix and 12 numbers, such as C301170101001. The serial number rules are as follows.
- A capital alphabetic prefix of with a range of 26, A to Z.
- The forth and fifth number indicates the manufacture year between 17-27.
- The sixth and seventh number indicates the manufacture month between 01-12.
- The eighth and ninth number indicates the manufacture day between 01-31.
Advertising Packet Agreement
- Including Advertising and Scan Response data.
- Advertising Data contains a sequence of AD structures
- AD structures contains the Length value, AD type and AD data.
- The Length value is the first octet of the AD structure.
| Advertising Packet | AD Structure | ||||
| Length | AD type | AD Data | Total Length | Description | |
| Advertising Data | 0x05 | 0x04 | 4 bytes | 6 Bytes | UUID |
| 0x16 | 0xFF | 21 Bytes | 23Bytes | Manufacturer Specific Data | |
| Scan Response | 0x0E | 0x09 | 13 Bytes | 15Bytes | Complete Local Name |
1.UUID (6 Bytes)
UUID: "ad07a961-0000-1000-8000-00805f9b34fb"
You can scan devices using specified UUID.
| Length | Value | Description |
|---|---|---|
| 1 byte | 0x05 | UUID length |
| 1 byte | 0x04 | UUID flag: Incomplete List of 32-bit Service Class UUIDs |
| 4 bytes | {0x61, 0xa9, 0x07, 0xad} | UUID value |
2.Manufacturer Specific Data (23 Bytes)
Definitions of AD Data (21Bytes) are as follows.
| Length | Value | Description |
|---|---|---|
| 1 byte | 0x14 | Custom data length |
| 1 byte | 0xFF | custom data flag |
| 2 bytes | 0x2935 | vender id. It is a constant value. |
| 2 bytes | 0x0808 | product id. It is a constant value. |
| 1 bytes | 0x01 | ble data layout. It is a constant value. |
| 2 bytes | 0x0001 | net protocol version, 1.0. It is a constant value. |
| 4 bytes | 0x01010101 | box status mask |
| 4 bytes | 0x00000000 | box eth ip: Ethernet IP address |
| 4 bytes | 0x00000000 | box wifi ip: Wi-Fi IP address |
3.Complete Local Name
Complete device name is the same as the 13-character device serial number. That is the BLE Name mentioned in the above context.
Device Communication
The client searches the device via the Bluetooth discovery service (GATT service: e20a39f4-73f5-4bc4-a12f-17d1ad07a961), and then interacts with the device via the BLE read/write feature value.
Service: GATT(e20a39f4-73f5-4bc4-a12f-17d1ad07a961):
This service is mainly used to interact with devices, such as obtaining device status, password authentication, Wi-Fi configurations, enabling device AP mode, and obtaining AP information, etc.
Service Characteristics are shown as the following table.
| UUID | Name |
|---|---|
| 08590f7e-db05-467e-8757-72f6faeb13d4 | Buffer-0 |
| f4be124e-4cdc-43e2-a6bb-8628e4009e6b | Buffer-1 |
| 1de1bf3d-1bbe-43aa-9a30-b2bb5ce9671d | Buffer-2 |
| 8d7bd67d-d0b3-4a5e-8d2b-2912af174a7d | Buffer-3 |
| 3a10340a-85e3-4190-86b4-b94dc505e4f8 | Buffer-4 |
1.Obtaining Device Status
| Procedure | Operation |
|---|---|
| Step 1 | APP -> Box Buffer-0: 2 Bytes = 0x5335 , 2 Bytes = Index |
| Step 2 | Box -> APP Buffer-4: 2 Bytes = 0x5336 , 4 Bytes = Box Status , 2 Byte = Same index |
Step 1: Request the device status when write using the buffer-0 characteristic. The characteristic contains 2 bytes constant value (0x5335) and 2 bytes random number.
Step 2: Obtain the device status when read using the buffer-4 characteristic. The characteristic contains 2 bytes constant value (0x5336), 4 bytes device status and 2 bytes random number.
Note: The random number in Step 2 and Step 1 must be the same.
2.Password Authentication
| Procedure | Operation |
|---|---|
| Step 1 | APP -> Box Buffer-4: 2 Bytes = 0x5333 , 2 Bytes = Index Buffer-0: 2 Bytes = 0x5333 , 16 Bytes = MD5(password) |
| Step 2 | Box -> APP Buffer-4: 2 Bytes = 0x5334 , 4 Bytes = retSucceed (0), errPasswd(-1) , 2 Byte = Same index |
The Buffer-4 characteristic should be written before the Step 1 Buffer-0 characteristic.
3.Wi-Fi Configuration
| Step 1 | APP -> Box |
| Buffer-0: 2 Bytes = 0x5337 2 Bytes = secuID, 0 - none, 1 - WEP, 2 - WPAPSK, 3 - WPA2PSK | 2 Bytes = Index | 2 Bytes = 0 - only ipv4, 1 - ipv4 or ipv6, 2 - only ipv6 | |
| Buffer-1: 18 Bytes = Wifi Name - 1 | |
| Buffer-2: 18 Bytes = Wifi Name - 2 | |
| Buffer-3: 18 Bytes = Wifi Passwd | |
| Buffer-4: 2 Bytes = 0x5337 | 16 Bytes = Wifi Passwd - 2 | |
| Step 2 | Box -> APP |
| Buffer-0: 2 Bytes = 0x5332 | 2 Bytes = Same Index | |
| Buffer-4: 2 Bytes = 0x5332 | 4 Bytes = retRunning(2), retSucceed (0), errPasswd(-1), errDevice(-4), errTimeout(-12), errNotFound(-14), errEmpty(-20)| 4 Bytes = WifiIP if retSucceed | 4 Bytes = Box Status | 2 Bytes = Version Major| 2 Bytes = Version Minor | |
Step 1: If the Wi Fi name and password are more than 18 bytes, they are written in two parts: buffer-0 buffer-1 buffer-2 buffer-3 buffer-4
Step 2: Read the buffer-0 characteristic first, and then the buffer-4 characteristic.
4.Enabling AP mode
| Step 1 | APP -> Box |
| Buffer-0: 2 Bytes = 0x5341 | 2 Bytes = Index | |
| Step 2 | Box -> APP |
| Buffer-4: 2 Bytes = 0x5342 | 4 Bytes = retSucceed (0), retRunning(2), errDevice(-4) | 2 Byte = Same index |
5.AP Information
| Step 1 | APP -> Box |
| Buffer-0: 2 Bytes = 0x5343 | 2 Bytes = Index | |
| Step 2 | Box -> APP |
| Buffer-4: 2 Bytes = 0x5344 | 2 Bytes = secuID, 0 - none, 1 - WEP, 2 - WPAPSK, 3 - WPA2PSK | 2 Byte = Same index | |
| Buffer-2: 2 Bytes = 0x5344 | 16 Bytes = Wi-Fi Name | |
| Buffer-3: 2 Bytes = 0x5344 | 16 Bytes = Wi-Fi Passwd |
The order of reading characteristics in step 2 is Buffer-4 Buffer-2 Buffer-3.
6.Ping
| Step 1 | Box -> APP |
| Buffer-1: |
After a Gatt connection is established, the buffer-1 feature is read periodically to prevent the GATT connection from being disconnected.