[[PageOutline]]

= GW16126 miniPCIe BLE / LTE Cat-M1 modem
[[Image(GW16126.png,400px)]]


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)

'''The drivers do not add the modem device ID (05c6:90b2) until mainline kernel 4.17'''.

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. For more info on the CATM1 standard and use cases see the following [https://www.u-blox.com/en/lte-cat-m1 CATM1 Explained Link]. 

The modem features a Qualcomm chipset that uses the 'option' 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.

General modem information that should be understood is located on the [wiki:wireless/modem Gateworks Modem Wiki Page]

''' Note, because this modem uses raw-ip, DHCP does not work and a IP will not automatically be applied to the interface. The provider will give an IP and then it must manually be applied to the wwan0 interface.'''

Sample set of commands for Ventana Ubuntu Bionic:
{{{
systemctl stop ModemManager #Stop modem manager, doing things manually
ifdown eth0  #bring down eth0 so not confused for WAN/LAN link.

echo "APN=ATT.APNI" > /etc/qmi-network.conf #replace with appropriate APN 
echo "PROXY=yes" >> /etc/qmi-network.conf # add prox
qmicli -p -d /dev/cdc-wdm0 --wda-set-data-format=raw-ip #set raw ip format
qmicli -p -d /dev/cdc-wdm0 --set-expected-data-format=raw-ip #set raw ip format
qmi-network /dev/cdc-wdm0 start #start the interface

qmicli --device /dev/cdc-wdm0 --wds-get-current-settings #retrieve IP address information

ifconfig wwan0 100.22.44.187 netmask 255.255.255.248 #assign IP 
route add default gw 100.75.76.188 wwan0 #assign route
echo "nameserver 198.224.182.135" > /etc/resolv.conf #assign nameserver
}}}


[=#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