Changes between Initial Version and Version 1 of expansion/gw16126

Timestamp:

11/07/2018 09:30:54 PM (5 years ago)

Author:

Tim Harvey

Comment:

initial page

expansion/gw16126

@@ +1 @@
+[[PageOutline]]
+
+= GW16126 miniPCIe BLE / LTE Cat-M1 modem
+The GW16126 is a miniPCIe form-factor card that features both a BLE 5.0 radio and a Cat-M1 modem designed for the IoT market.
+
+The GW16126 interfaces with a host over USB 2.0 and uses the following pins on the miniPCIe card edge:
+ - GND: pin 4,9,15,18,21,26,27,29,34,35,40,43,50
+ - VDD_3P3: pin 2,24,39,41,52
+ - USB_DM: pin 36
+ - USB_DP: pin 38
+
+Power draw varies greatly with the activity of the LTE Cat-M1 modem but typically varies between the milliwatt range to a max of around 2W
+
+On the USB bus the following are present:
+ * USB2514 USB 2.0 2-port HUB
+  * FT231X USB UART connected to a u-blox NINA-B30x BLE module
+  * u-blox NINA-B301 BLE module USB 2.0 controller
+  * u-blox SARA-R4 Cat M-1 / NB1 modem with nano-SIM socket
+
+These look like the following with {{{lsusb}}}:
+{{{#!bash
+ID 05c6:90b2 Qualcomm, Inc. 
+ID 0403:6015 Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)
+ID 0424:2514 Standard Microsystems Corp. USB 2.0 Hub
+}}}
+
+The following devices will be created by the kernel modules:
+ * /dev/ttyUSB0 (hci_uart) (CONFIG_BT_HCIUART, CONFIG_BT_HCIUART_H4 hci_uart)
+ * /dev/ttyUSB1 (qcdm) (CONFIG_USB_SERIAL_OPTION option)
+ * /dev/ttyUSB2 (at) (CONFIG_USB_SERIAL_OPTION option)
+ * /dev/cdc-wdm0 (qmi) (CONFIG_USB_NET_QMI_WWAN qmi_wwan)
+ * /sys/class/net/wwan0 (net) (CONFIG_USB_NET_QMI_WWAN qmi_wwan)
+
+If for some reason you don't have all the drivers enabled above or have them static, you may find the /dev/ttyUSB devices enumerate in a different order. You can use a variety of ways to determine which device is which:
+ * {{{mmcli -m 0}}} will report details about detected modems and what devices they are on
+ * {{{ls -d /sys/bus/usb/drivers/ftdi_sio/*/ttyUSB*}}} will tell you which tty is attached to the {{{ftdi_sio}}} driver to attach the Bluetooth HCI_UART to
+ * {{{ls -d /sys/bus/usb/drivers/option/*/ttyUSB*}}} will tell you which tty's are attached to the {{{option}}} driver for the modem.
+
+[=#sara-r4]
+== u-blox SARA-R4 LTE Cat M-1 modem
+The [https://www.u-blox.com/sites/default/files/SARA-R4-N4_ProductSummary_%28UBX-16019228%29.pdf u-blox SARA-R410M-52B] LTE Cat M1 modem supports M1 bands 2,4,5,12,13.
+
+The modem features a Qualcomm chipset that uses the 'option1' and 'qmi_wwan' Linux drivers providing the following devices:
+ * /dev/ttyUSB1 (qcdm)
+ * /dev/ttyUSB2
+ * /dev/cdc-wdm0 (qmi)
+ * /sys/class/net/wwan0 (net)
+
+The modem is supported by Linux !ModemManager and libqmi-utils.
+
+
+[=#nina-b3]
+== u-blox NINA-B301 BLE module
+The u-blox [https://www.u-blox.com/sites/default/files/NINA-B30_ProductSummary_%28UBX-17052930%29.pdf NINA-B301] stand-alone Bluetooth 5 low engery module contains an open [https://www.nordicsemi.com/eng/Products/nRF52840 Nordic nRF52840] multiprotocol SoC.
+
+
+[=#hci]
+=== Bluetooth HCI (GW16126)
+The standard GW16126 comes the nRF52840 pre-programmed by Gateworks with [https://www.zephyrproject.org/ Zephyr Project]  [https://docs.zephyrproject.org/latest/samples/bluetooth/hci_uart/README.html hci_uart] offering a bluetooth HCI UART host controller. The Open-Source Zephyr Project provides a small scalable real-time operating system (RTOS) well suited for small ARM processors such as the one in the nRF52840 and its [https://docs.zephyrproject.org/latest/samples/bluetooth/hci_uart/README.html hci_uart] sample code implements a BLE HCI via the H4 UART protocol with the following:
+ * 1mbps baudrate
+ * 8bits, no parity, 1 stop bit
+ * hardware flow control required
+
+To use the GW16126 bluetooth HCI with Linux you need the following:
+ * Linux 4.10+ kernel with the following:
+  - FTDI UART support (CONFIG_USB_SERIAL_FTDI_SIO)
+  - HCI UART with H4 (CONFIG_BT_HCIUART and CONFIG_BT_HCIUART_H4) in order to provide a bluetooth HCI over UART
+  - crypto userspace API (CONFIG_CRYPTO_USER, CONFIG_CRYPTO_USER_API_AEAD, CONFIG_CRYPTO_USER_API_HASH, CONFIG_CRYPTO_USER_API_RNG, CONFIG_CRYPTO_USER_API_SKCIPHER) in order to generate a random Bluetooth MAC (BDADDR)
+ * Bluetooth stack such as BlueZ (4.45+)
+
+The following shows how you would interact with the BLE controller via BlueZ on Ubuntu bionic:
+{{{#!bash
+apt-get install bluez
+# configure bluez to run expirimental features
+sed -i '/^ExecStart=/ s/$/ -E/' /lib/systemd/system/bluetooth.service 
+# restart bluetoothd
+sudo systemctl daemon-reload
+sudo systemctl restart bluetooth
+# attach HCI UART
+dev=$(basename $(ls -d /sys/bus/usb/drivers/ftdi_sio/*/ttyUSB*))
+modprobe hci_uart
+btattach -B /dev/$dev -S 1000000 -P h4 &
+# scan for BLE devices
+hcitool -i hci0 lescan
+}}}
+
+Example:
+{{{#!bash
+root@bionic-newport:~# echo 8 > /proc/sys/kernel/printk
+root@bionic-newport:~# dev=$(basename $(ls -d /sys/bus/usb/drivers/ftdi_sio/*/tty
+root@bionic-newport:~# modprobe hci_uart
+[   35.314383] Bluetooth: Core ver 2.22
+[   35.318121] NET: Registered protocol family 31
+[   35.322614] Bluetooth: HCI device and connection manager initialized
+[   35.328997] Bluetooth: HCI socket layer initialized
+[   35.333904] Bluetooth: L2CAP socket layer initialized
+[   35.338983] Bluetooth: SCO socket layer initialized
+[   35.350560] Bluetooth: HCI UART driver ver 2.3
+[   35.355057] Bluetooth: HCI UART protocol H4 registered
+root@bionic-newport:~# btattach -B /dev/$dev -S 1000000 -P h4 &
+[1] 2138
+Attaching Primary controller to /dev/ttyUSB0
+Switched line discipline from 0 to 15
+Device index 0 attached
+[   57.834717] Bluetooth: BNEP (Ethernet Emulation) ver 1.3
+[   57.840137] Bluetooth: BNEP socket layer initialized
+root@bionic-newport:~# hciconfig 
+hci0:   Type: Primary  Bus: UART
+        BD Address: 00:00:00:00:00:00  ACL MTU: 27:7  SCO MTU: 0:0
+        UP RUNNING 
+        RX bytes:527 acl:0 sco:0 events:41 errors:0
+        TX bytes:258 acl:0 sco:0 commands:41 errors:0
+
+root@bionic-newport:~# hcitool -i hci0 lescan
+LE Scan ...
+3C:A3:08:10:51:FE (unknown)
+FC:B4:88:8E:32:61 (unknown)
+FC:B4:88:8E:32:61 (unknown)
+3C:A3:08:10:51:FE LEDBlue-081051FE 
+
+}}}
+
+ 
+
+[=#zephyr]
+=== Zephyr Project Firmware
+While the nRF52840 comes pre-programmed with firmware to make it a [https://docs.zephyrproject.org/latest/subsystems/bluetooth/bluetooth.html fully featured Bluetooth HCI] you could develop your own firmware and re-program it if desired.
+
+The [https://www.zephyrproject.org/ Zephyr Project] is a scaleable real-time operating system (RTOS) supporting multiple hardware architectures, optimized for resource constrained devices, and built with security in mind. The Zephyr Project supports the Nordic nRF58240 within the u-blox NINA-B3 BLE module and can be modified to give it a personality of its own. Some examples within the Zephyr Project that are suited for the GW16123 out of the box are:
+ * HCI uart
+ * BLE beacon
+
+Gateworks has added GW16126 board support to Zephyr [https://github.com/Gateworks/zephyr.git here] via [https://github.com/Gateworks/zephyr/commit/ba5f00ad5918b44e901f356a98e63e963516a429 commit ba5f00ad]
+
+Examples:
+ 1. Install Zephyr source
+{{{#!bash
+git clone https://github.com/Gateworks/zephyr.git
+cd ~/zephyr  # or to your directory where zephyr is cloned
+# install more requirements via pip
+pip3 install --user -r scripts/requirements.txt
+}}}
+ 1. Build HCI UART (what Gateworks pre-programms into the GW16126):
+{{{#!bash
+# setup shell for building Zephyr
+source zephyr-env.sh:
+cd $ZEPHYR_BASE/samples/bluetooth/hci_uart
+mkdir -p build/gw16126 && cd build/gw16126
+cmake -DBOARD=nrf52840_gw16126 ../..
+make
+ls zephyr/zephyr.hex
+}}}
+ 2. Build Bluetooth Beacon:
+{{{#!bash
+# setup shell for building Zephyr
+source zephyr-env.sh:
+cd $ZEPHYR_BASE/samples/bluetooth/beacon
+mkdir -p build/gw16126 && cd build/gw16126
+cmake -DBOARD=nrf52840_gw16126 ../..
+make
+ls zephyr/zephyr.hex
+}}}
+
+ 
+=== Programming the nRF58240
+While the nRF52840 comes pre-programmed with firmware to make it a [https://docs.zephyrproject.org/latest/subsystems/bluetooth/bluetooth.html fully featured Bluetooth HCI] you could develop your own firmware and re-program it if desired. The device can be programmed via SWD using the FT231X CBUS pins as follows:
+ * CBUS1 - SWDIO
+ * CBUS2 - SWDCLK
+
+To program you can use OpenOCD with the {{{sysfsgpio}}} interface as long as you have a kernel that supports GPIO in the ftdi-sio driver (Linux 4.20+).
+
+The following will create a gw16126.cfg OpenOCD interface file specifying SWD and mapping the SWCLK/SWDIO pins to the FT231X CBUS2/CBUS1 pins:
+ 1. Create an OpenOCD interface file for the GW16126 that defines the Linux gpio signals for SWD:
+{{{#!bash
+base=$(for i in $(ls -1d /sys/class/gpio/gpiochip*); do [ "ftdi-cbus" = "$(cat $i/label)" ] && cat $i/base; done)
+[ "$base" ] || { echo "Error: could not find ftdi-cbus device - Linux 4.20+ required"; }
+cat << EOF > gw16126.cfg
+interface sysfsgpio
+transport select swd
+Show quoted text
+sysfsgpio_swd_nums $((base + 2)) $((base + 1))
+EOF
+}}}
+ 2. Build OpenOCD from git master for nRF52840 support:
+{{{#!bash
+apt-get install build-essential git flex bison pkg-config libtool autoconf automake texinfo libusb-1.0-0-dev
+git clone git://git.code.sf.net/p/openocd/code openocd
+cd openocd
+./bootstrap
+./configure --enable-sysfsgpio
+make install
+}}}
+  - alternatively you can fetch from a zip archive via {{{wget --no-check-certificate
+ https://repo.or.cz/openocd.git/snapshot/refs/heads/master.zip}}} but note that the bootstrap script which checkout jimtcl as git submodules so this doesn't really help
+  - I've been having issues on bionic because NTP isn't working right which leads to certificate issues. You can disable by {{{git config --global http.sslverify false}}}
+ 3. Program firmware:
+{{{#!bash
+# openocd -f gw16126.cfg -f target/nrf52.cfg \
+   -c init -c "reset init" -c halt -c "nrf5 mass_erase" -c "program zephyr_uart_hci.hex verify" -c reset -c exit
+Open On-Chip Debugger 0.10.0+dev-00563-gda4b2d5b (2018-10-20-01:03)
+Licensed under GNU GPL v2
+For bug reports, read
+        http://openocd.org/doc/doxygen/bugs.html
+SysfsGPIO nums: swclk = 462, swdio = 461
+adapter speed: 1000 kHz
+cortex_m reset_config sysresetreq
+Info : SysfsGPIO JTAG/SWD bitbang driver
+Info : SWD only mode enabled (specify tck, tms, tdi and tdo gpios to add JTAG mode)
+Info : This adapter doesn't support configurable speed
+Info : SWD DPIDR 0x2ba01477
+Info : nrf52.cpu: hardware has 6 breakpoints, 4 watchpoints
+Info : Listening on port 3333 for gdb connections
+target halted due to debug-request, current mode: Thread
+xPSR: 0x01000000 pc: 0xfffffffe msp: 0xfffffffc
+Info : nRF52840-QIAA(build code: C0) 1024kB Flash
+target halted due to debug-request, current mode: Thread
+xPSR: 0x01000000 pc: 0xfffffffe msp: 0xfffffffc
+** Programming Started **
+auto erase enabled
+Warn : using fast async flash loader. This is currently supported
+Warn : only with ST-Link and CMSIS-DAP. If you have issues, add
+Warn : "set WORKAREASIZE 0" before sourcing nrf51.cfg/nrf52.cfg to disable it
+wrote 49152 bytes from file zephyr.hex in 117.544823s (0.408 KiB/s)
+** Programming Finished **
+** Verify Started **
+verified 47036 bytes in 2.723827s (16.864 KiB/s)
+** Verified OK **
+}}}
+
+
+=== u-blox Connectivity Software (GW16126-SP399)
+The GW16126-SP399 comes with the nRF52840 pre-programmed (and locked) by u-blox with the u-blox Connectivity Software.
+
+Connection parameters:
+ - 115200baud, 8 data bits no stop bit
+
+Protocol details:
+- [https://www.u-blox.com/ja/files/u-blox-short-range-modules-commands-manual UBX-14044127 u-blox Short Range Modules] - AT Commands Manual
+- [https://www.u-blox.com/sites/default/files/NINA-B31_GettingStarted_%28UBX-18022394%29.pdf UBX-18022394 NINA-B31 series Stand-alone Bluetooth 5 low energy modules Getting Started]
+
+Examples:
+ - Serial port interaction
+{{{#!bash
+# query configured role
+AT+UBTLE?
++UBTLE:2
+OK
+
+# set to central
+AT+UBTLE=1
+OK
+
+# store and power cycle
+AT&W
+OK
+AT+CPWROFF
+OK
+
++STARTUP
+
+# report scan results
+AT+UBTD
+
++UBTD:FCB4888E3261r,-76,"",2,0201061AFF4C0002156445C351577C4DA9AE12E57657E78C6F0000000000
++UBTD:FCB4888E3261r,-77,"",1,
+OK
+}}}
+ - command line usage:
+{{{#!bash
+dev=$(basename $(ls -d /sys/bus/usb/drivers/ftdi_sio/*/ttyUSB*))
+stty -F $dev 115200 ignbrk -brkint -icrnl -opost -onlcr -isig -icanon -iexten -echo -echoe -echok -echoctl -echoke
+cat $dev & # continually display responses from tty in background
+# request manufactuer identify
+printf 'AT+GMI\r\n' > $dev
+# request model
+printf 'AT+GMM\r\n' > $dev
+# request serial number
+printf 'AT+GSN\r\n' > $dev
+# request misc details
+printf 'AT+ATI0\r\n' > $dev
+# change role to central, write nvram, and reset
+printf 'AT+UBTLE=1\r\n' > $dev
+printf 'AT&W\r\n' > $dev
+printf 'AT+CPWROFF\r\n' > $dev
+# scan for BLE devices
+sleep 1
+printf 'AT+UBTD\r\n' > $dev
+}}}
+
+See also ublox s-center software for use on Windows
+
+
+[=#software]
+== Software Support
+The following software is necessary for the GW16126:
+ * LTE Cat-M1 modem:
+  - Linux 4.5 kernel with option driver (CONFIG_USB_SERIAL_OPTION) and qmi driver (CONFIG_USB_NET_QMI_WWAN)
+ * BLE hci:
+  - Linux 4.5 kernel
+  - hci_uart driver (CONFIG_BT_HCIUART, CONFIG_BT_HCIUART_H4 hci_uart)
+  - Userspace cryptographic algorithm support (CONFIG_CRYPTO_USER_API*) (for generation of random bdaddr in BlueZ)
+  - Bluetooth stack such as BlueZ
+
+Ubuntu bionic:
+ - requires: bluez modemmanager libqmi bluez
+ - works out of box
+
+OpenWrt 18.6.1:
+ - requires kmod-usb-net-opton, kmod-usb-net-qmi-wwan, kmod-usb-serial, kmod-usb-serial-ftdi, kmod-usb-serial-qualcomm, kmod-bluetooth, kmod-crypto-user, kmod-crypto-hash, bluez-daemon, uqmi
+ - works out of the box
+
+OpenWrt 16.02:
+ - will not work without backporting qmi raw-ip support and modem ID's to option1/qmi-wwan driver