2 * This file is part of the libsigrok project.
4 * Copyright (C) 2018-2019 Gerhard Sittig <gerhard.sittig@gmx.net>
6 * This program is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation, either version 3 of the License, or
9 * (at your option) any later version.
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License
17 * along with this program. If not, see <http://www.gnu.org/licenses/>.
22 #include <libsigrok/libsigrok.h>
23 #include "libsigrok-internal.h"
28 #define LOG_PREFIX "serial-bt"
31 #ifdef HAVE_SERIAL_COMM
34 #define SER_BT_CONN_PREFIX "bt"
35 #define SER_BT_CHUNK_SIZE 1200
40 * Serial port handling, wraps the external BT/BLE dependencies.
44 * @defgroup grp_serial_bt Serial port handling, BT/BLE group
46 * Make serial-over-BT communication appear like a regular serial port.
51 /* {{{ support for serial-over-BT channels */
53 static const struct scan_supported_item {
55 enum ser_bt_conn_t type;
56 } scan_supported_items[] = {
57 /* Guess connection types from device names (useful for scans). */
58 { "121GW", SER_BT_CONN_BLE122, },
59 { "Adafruit Bluefruit LE 8134", SER_BT_CONN_NRF51, },
60 { "HC-05", SER_BT_CONN_RFCOMM, },
61 { NULL, SER_BT_CONN_UNKNOWN, },
64 static const char *ser_bt_conn_names[SER_BT_CONN_MAX] = {
65 [SER_BT_CONN_UNKNOWN] = "<type>",
66 [SER_BT_CONN_RFCOMM] = "rfcomm",
67 [SER_BT_CONN_BLE122] = "ble122",
68 [SER_BT_CONN_NRF51] = "nrf51",
69 [SER_BT_CONN_CC254x] = "cc254x",
72 static enum ser_bt_conn_t lookup_conn_name(const char *name)
78 return SER_BT_CONN_UNKNOWN;
79 idx = ARRAY_SIZE(ser_bt_conn_names);
81 item = ser_bt_conn_names[idx];
82 if (strcmp(item, name) == 0)
86 return SER_BT_CONN_UNKNOWN;
89 static const char *conn_name_text(enum ser_bt_conn_t type)
91 if (type >= ARRAY_SIZE(ser_bt_conn_names))
92 type = SER_BT_CONN_UNKNOWN;
94 return ser_bt_conn_names[type];
98 * Parse conn= specs for serial over Bluetooth communication.
100 * @param[in] serial The serial port that is about to get opened.
101 * @param[in] spec The caller provided conn= specification.
102 * @param[out] conn_type The type of BT comm (BT RFCOMM, BLE notify).
103 * @param[out] remote_addr The remote device address.
104 * @param[out] rfcomm_channel The RFCOMM channel (if applicable).
105 * @param[out] read_hdl The BLE notify read handle (if applicable).
106 * @param[out] write_hdl The BLE notify write handle (if applicable).
107 * @param[out] cccd_hdl The BLE notify CCCD handle (if applicable).
108 * @param[out] cccd_val The BLE notify CCCD value (if applicable).
110 * @return 0 upon success, non-zero upon failure.
114 * Summary of parsing rules as they are implemented:
115 * - Implementor's note: Automatic scan for available devices is not
116 * yet implemented. So strictly speaking some parts of the input
117 * spec are optional, but fallbacks may not take effect ATM.
118 * - Insist on the "bt" prefix. Accept "bt" alone without any other
120 * - The first field that follows is the connection type. Supported
121 * types are 'rfcomm', 'ble122', 'cc254x', and potentially others
122 * in a future implementation.
123 * - The next field is the remote device's address, either separated
124 * by colons or dashes or spaces, or not separated at all.
125 * - Other parameters (RFCOMM channel, notify handles and write values)
126 * get derived from the connection type. A future implementation may
127 * accept more fields, but the syntax is yet to get developed.
129 * Supported formats resulting from these rules:
133 * bt/rfcomm/11-22-33-44-55-66
134 * bt/ble122/88:6b:12:34:56:78
135 * bt/cc254x/0123456789ab
137 * It's assumed that users easily can create those conn= specs from
138 * available information, or that scan routines will create such specs
139 * that copy'n'paste results (or GUI choices from previous scan results)
140 * can get processed here.
142 static int ser_bt_parse_conn_spec(
143 struct sr_serial_dev_inst *serial, const char *spec,
144 enum ser_bt_conn_t *conn_type, const char **remote_addr,
145 size_t *rfcomm_channel,
146 uint16_t *read_hdl, uint16_t *write_hdl,
147 uint16_t *cccd_hdl, uint16_t *cccd_val)
149 enum ser_bt_conn_t type;
151 char **fields, *field;
154 *conn_type = SER_BT_CONN_UNKNOWN;
168 type = SER_BT_CONN_UNKNOWN;
171 if (!serial || !spec || !spec[0])
174 /* Evaluate the mandatory first three fields. */
175 fields = g_strsplit_set(spec, "/", 0);
178 if (g_strv_length(fields) < 3) {
183 if (strcmp(field, SER_BT_CONN_PREFIX) != 0) {
188 type = lookup_conn_name(field);
196 if (!field || !*field) {
200 addr = g_strdup(field);
204 /* Derive default parameters that match the connection type. */
205 /* TODO Lookup defaults from a table? */
207 case SER_BT_CONN_RFCOMM:
211 case SER_BT_CONN_BLE122:
221 case SER_BT_CONN_NRF51:
223 * Are these values appropriate? Check the learn article at
224 * https://learn.adafruit.com/introducing-the-adafruit-bluefruit-le-uart-friend?view=all
234 /* TODO 'random' type, sec-level=high */
236 case SER_BT_CONN_CC254x:
237 /* TODO Are these values appropriate? Just guessing here. */
251 /* TODO Evaluate optionally trailing fields, override defaults? */
257 static void ser_bt_mask_databits(struct sr_serial_dev_inst *serial,
258 uint8_t *data, size_t len)
264 if ((serial->comm_params.data_bits % 8) == 0)
267 mask32 = (1UL << serial->comm_params.data_bits) - 1;
268 mask = mask32 & 0xff;
269 for (idx = 0; idx < len; idx++)
273 static int ser_bt_data_cb(void *cb_data, uint8_t *data, size_t dlen)
275 struct sr_serial_dev_inst *serial;
281 ser_bt_mask_databits(serial, data, dlen);
282 sr_ser_queue_rx_data(serial, data, dlen);
288 /* {{{ wrap serial-over-BT operations in a common serial.c API */
290 /* See if a serial port's name refers to a BT type. */
291 SR_PRIV int ser_name_is_bt(struct sr_serial_dev_inst *serial)
298 if (!serial->port || !*serial->port)
301 /* Accept either "bt" alone, or "bt/" as a prefix. */
302 if (!g_str_has_prefix(serial->port, SER_BT_CONN_PREFIX))
304 off = strlen(SER_BT_CONN_PREFIX);
305 sep = serial->port[off];
306 if (sep != '\0' && sep != '/')
312 /* The open() wrapper for BT ports. */
313 static int ser_bt_open(struct sr_serial_dev_inst *serial, int flags)
315 enum ser_bt_conn_t conn_type;
316 const char *remote_addr;
317 size_t rfcomm_channel;
318 uint16_t read_hdl, write_hdl, cccd_hdl, cccd_val;
320 struct sr_bt_desc *desc;
324 /* Derive BT specific parameters from the port spec. */
325 rc = ser_bt_parse_conn_spec(serial, serial->port,
326 &conn_type, &remote_addr,
328 &read_hdl, &write_hdl,
329 &cccd_hdl, &cccd_val);
333 if (!conn_type || !remote_addr || !remote_addr[0]) {
334 /* TODO Auto-search for available connections? */
338 /* Create the connection. Only store params after successful use. */
339 desc = sr_bt_desc_new();
342 serial->bt_desc = desc;
343 rc = sr_bt_config_addr_remote(desc, remote_addr);
346 serial->bt_addr_remote = g_strdup(remote_addr);
348 case SER_BT_CONN_RFCOMM:
349 rc = sr_bt_config_rfcomm(desc, rfcomm_channel);
352 serial->bt_rfcomm_channel = rfcomm_channel;
354 case SER_BT_CONN_BLE122:
355 case SER_BT_CONN_NRF51:
356 case SER_BT_CONN_CC254x:
357 rc = sr_bt_config_notify(desc,
358 read_hdl, write_hdl, cccd_hdl, cccd_val);
361 serial->bt_notify_handle_read = read_hdl;
362 serial->bt_notify_handle_write = write_hdl;
363 serial->bt_notify_handle_cccd = cccd_hdl;
364 serial->bt_notify_value_cccd = cccd_val;
367 /* Unsupported type, or incomplete implementation. */
370 serial->bt_conn_type = conn_type;
372 /* Make sure the receive buffer can accept input data. */
373 if (!serial->rcv_buffer)
374 serial->rcv_buffer = g_string_sized_new(SER_BT_CHUNK_SIZE);
375 rc = sr_bt_config_cb_data(desc, ser_bt_data_cb, serial);
379 /* Open the connection. */
381 case SER_BT_CONN_RFCOMM:
382 rc = sr_bt_connect_rfcomm(desc);
386 case SER_BT_CONN_BLE122:
387 case SER_BT_CONN_NRF51:
388 case SER_BT_CONN_CC254x:
389 rc = sr_bt_connect_ble(desc);
392 rc = sr_bt_start_notify(desc);
403 static int ser_bt_close(struct sr_serial_dev_inst *serial)
408 if (!serial->bt_desc)
411 sr_bt_disconnect(serial->bt_desc);
412 sr_bt_desc_free(serial->bt_desc);
413 serial->bt_desc = NULL;
415 g_free(serial->bt_addr_local);
416 serial->bt_addr_local = NULL;
417 g_free(serial->bt_addr_remote);
418 serial->bt_addr_remote = NULL;
419 g_slist_free_full(serial->bt_source_args, g_free);
420 serial->bt_source_args = NULL;
425 /* Flush, discards pending RX data, empties buffers. */
426 static int ser_bt_flush(struct sr_serial_dev_inst *serial)
434 /* Drain, waits for completion of pending TX data. */
435 static int ser_bt_drain(struct sr_serial_dev_inst *serial)
438 /* EMPTY */ /* TODO? */
443 static int ser_bt_write(struct sr_serial_dev_inst *serial,
444 const void *buf, size_t count,
445 int nonblocking, unsigned int timeout_ms)
450 * TODO Support chunked transmission when callers' requests
451 * exceed the BT channel's capacity? See ser_hid_write().
454 switch (serial->bt_conn_type) {
455 case SER_BT_CONN_RFCOMM:
458 wrlen = sr_bt_write(serial->bt_desc, buf, count);
462 case SER_BT_CONN_BLE122:
463 case SER_BT_CONN_NRF51:
464 case SER_BT_CONN_CC254x:
466 * Assume that when applications call the serial layer's
467 * write routine, then the BLE chip/module does support
468 * a TX handle. Just call the serial-BT library's write
473 wrlen = sr_bt_write(serial->bt_desc, buf, count);
483 static int ser_bt_read(struct sr_serial_dev_inst *serial,
484 void *buf, size_t count,
485 int nonblocking, unsigned int timeout_ms)
487 gint64 deadline_us, now_us;
488 uint8_t buffer[SER_BT_CHUNK_SIZE];
494 * Immediately satisfy the caller's request from the RX buffer
495 * if the requested amount of data is available already.
497 if (sr_ser_has_queued_data(serial) >= count) {
498 rc = sr_ser_unqueue_rx_data(serial, buf, count);
503 * When a timeout was specified, then determine the deadline
504 * where to stop reception.
507 now_us = 0; /* Silence a (false) compiler warning. */
509 now_us = g_get_monotonic_time();
510 deadline_us = now_us + timeout_ms * 1000;
514 * Keep receiving from the port until the caller's requested
515 * amount of data has become available, or the timeout has
516 * expired. In the absence of a timeout, stop reading when an
517 * attempt no longer yields receive data.
520 /* Run another attempt to receive data. */
521 switch (serial->bt_conn_type) {
522 case SER_BT_CONN_RFCOMM:
523 rdlen = sr_bt_read(serial->bt_desc, buffer, sizeof(buffer));
526 rc = ser_bt_data_cb(serial, buffer, rdlen);
530 case SER_BT_CONN_BLE122:
531 case SER_BT_CONN_NRF51:
532 case SER_BT_CONN_CC254x:
533 dlen = sr_ser_has_queued_data(serial);
534 rc = sr_bt_check_notify(serial->bt_desc);
537 else if (sr_ser_has_queued_data(serial) != dlen)
548 * Stop upon receive errors, or timeout expiration. Only
549 * stop upon empty reception in the absence of a timeout.
553 if (nonblocking && !rdlen)
556 now_us = g_get_monotonic_time();
557 if (now_us > deadline_us)
561 /* Also stop when sufficient data has become available. */
562 if (sr_ser_has_queued_data(serial) >= count)
567 * Satisfy the caller's demand for receive data from previously
568 * queued incoming data.
570 dlen = sr_ser_has_queued_data(serial);
576 return sr_ser_unqueue_rx_data(serial, buf, dlen);
579 static int ser_bt_set_params(struct sr_serial_dev_inst *serial,
580 int baudrate, int bits, int parity, int stopbits,
581 int flowcontrol, int rts, int dtr)
584 * Bluetooth communication has no concept of bitrate, so ignore
585 * these arguments silently. Neither need we pass the frame format
586 * down to internal BT comm routines, nor need we keep the values
587 * here, since the caller will cache/register them already.
601 struct bt_source_args_t {
602 /* The application callback. */
603 sr_receive_data_callback cb;
605 /* The serial device, to store RX data. */
606 struct sr_serial_dev_inst *serial;
610 * Gets periodically invoked by the glib main loop. "Drives" (checks)
611 * progress of BT communication, and invokes the application's callback
612 * which processes RX data (when some has become available), as well as
613 * handles application level timeouts.
615 static int bt_source_cb(int fd, int revents, void *cb_data)
617 struct bt_source_args_t *args;
618 struct sr_serial_dev_inst *serial;
619 uint8_t rx_buf[SER_BT_CHUNK_SIZE];
627 serial = args->serial;
630 if (!serial->bt_conn_type)
634 * Drain receive data which the channel might have pending.
635 * This is "a copy" of the "background part" of ser_bt_read(),
636 * without the timeout support code, and not knowing how much
637 * data the application is expecting.
640 switch (serial->bt_conn_type) {
641 case SER_BT_CONN_RFCOMM:
642 rdlen = sr_bt_read(serial->bt_desc, rx_buf, sizeof(rx_buf));
645 rc = ser_bt_data_cb(serial, rx_buf, rdlen);
649 case SER_BT_CONN_BLE122:
650 case SER_BT_CONN_NRF51:
651 case SER_BT_CONN_CC254x:
652 dlen = sr_ser_has_queued_data(serial);
653 rc = sr_bt_check_notify(serial->bt_desc);
656 else if (sr_ser_has_queued_data(serial) != dlen)
668 * When RX data became available (now or earlier), pass this
669 * condition to the application callback. Always periodically
670 * run the application callback, since it handles timeouts and
671 * might carry out other tasks as well like signalling progress.
673 if (sr_ser_has_queued_data(args->serial))
675 rc = args->cb(fd, revents, args->cb_data);
680 /* TODO Can we use the Bluetooth socket's file descriptor? Probably not portably. */
681 #define WITH_MAXIMUM_TIMEOUT_VALUE 0
682 static int ser_bt_setup_source_add(struct sr_session *session,
683 struct sr_serial_dev_inst *serial,
684 int events, int timeout,
685 sr_receive_data_callback cb, void *cb_data)
687 struct bt_source_args_t *args;
692 /* Optionally enforce a minimum poll period. */
693 if (WITH_MAXIMUM_TIMEOUT_VALUE && timeout > WITH_MAXIMUM_TIMEOUT_VALUE)
694 timeout = WITH_MAXIMUM_TIMEOUT_VALUE;
696 /* Allocate status container for background data reception. */
697 args = g_malloc0(sizeof(*args));
699 args->cb_data = cb_data;
700 args->serial = serial;
703 * Have a periodic timer installed. Register the allocated block
704 * with the serial device, since the GSource's finalizer won't
705 * free the memory, and we haven't bothered to create a custom
706 * BT specific GSource.
708 rc = sr_session_source_add(session, -1, events, timeout, bt_source_cb, args);
713 serial->bt_source_args = g_slist_append(serial->bt_source_args, args);
718 static int ser_bt_setup_source_remove(struct sr_session *session,
719 struct sr_serial_dev_inst *serial)
723 (void)sr_session_source_remove(session, -1);
724 /* Release callback args here already? */
729 static enum ser_bt_conn_t scan_is_supported(const char *name)
732 const struct scan_supported_item *item;
734 for (idx = 0; idx < ARRAY_SIZE(scan_supported_items); idx++) {
735 item = &scan_supported_items[idx];
738 if (strcmp(name, item->name) != 0)
743 return SER_BT_CONN_UNKNOWN;
746 struct bt_scan_args_t {
748 sr_ser_list_append_t append;
753 static void scan_cb(void *cb_args, const char *addr, const char *name)
755 struct bt_scan_args_t *scan_args;
758 enum ser_bt_conn_t type;
759 char *port_name, *port_desc;
765 sr_info("BT scan, found: %s - %s\n", addr, name);
767 /* Check whether the device was seen before. */
768 for (l = scan_args->addr_list; l; l = l->next) {
769 if (strcmp(addr, l->data) == 0) {
774 /* Substitute colons in the address by dashes. */
777 snprintf(addr_text, sizeof(addr_text), "%s", addr);
778 g_strcanon(addr_text, "0123456789abcdefABCDEF", '-');
780 /* Create a port name, and a description. */
781 type = scan_is_supported(name);
782 port_name = g_strdup_printf("%s/%s/%s",
783 SER_BT_CONN_PREFIX, conn_name_text(type), addr_text);
784 port_desc = g_strdup_printf("%s (%s)", name, scan_args->bt_type);
786 scan_args->port_list = scan_args->append(scan_args->port_list, port_name, port_desc);
790 /* Keep track of the handled address. */
791 addr_copy = g_strdup(addr);
792 scan_args->addr_list = g_slist_append(scan_args->addr_list, addr_copy);
795 static GSList *ser_bt_list(GSList *list, sr_ser_list_append_t append)
797 static const int scan_duration = 2;
799 struct bt_scan_args_t scan_args;
800 struct sr_bt_desc *desc;
803 * Implementor's note: This "list" routine is best-effort. We
804 * assume that registering callbacks always succeeds. Silently
805 * ignore failure to scan for devices. Just return those which
809 desc = sr_bt_desc_new();
813 memset(&scan_args, 0, sizeof(scan_args));
814 scan_args.port_list = list;
815 scan_args.append = append;
817 scan_args.addr_list = NULL;
818 scan_args.bt_type = "BT";
819 (void)sr_bt_config_cb_scan(desc, scan_cb, &scan_args);
820 (void)sr_bt_scan_bt(desc, scan_duration);
821 g_slist_free_full(scan_args.addr_list, g_free);
823 scan_args.addr_list = NULL;
824 scan_args.bt_type = "BLE";
825 (void)sr_bt_config_cb_scan(desc, scan_cb, &scan_args);
826 (void)sr_bt_scan_le(desc, scan_duration);
827 g_slist_free_full(scan_args.addr_list, g_free);
829 sr_bt_desc_free(desc);
831 return scan_args.port_list;
834 static struct ser_lib_functions serlib_bt = {
836 .close = ser_bt_close,
837 .flush = ser_bt_flush,
838 .drain = ser_bt_drain,
839 .write = ser_bt_write,
841 .set_params = ser_bt_set_params,
842 .setup_source_add = ser_bt_setup_source_add,
843 .setup_source_remove = ser_bt_setup_source_remove,
845 .get_frame_format = NULL,
847 SR_PRIV struct ser_lib_functions *ser_lib_funcs_bt = &serlib_bt;
852 SR_PRIV int ser_name_is_bt(struct sr_serial_dev_inst *serial)
859 SR_PRIV struct ser_lib_functions *ser_lib_funcs_bt = NULL;