Changes between Initial Version and Version 1 of expansion/gw16126


Ignore:
Timestamp:
11/07/2018 09:30:54 PM (11 months ago)
Author:
Tim Harvey
Comment:

initial page

Legend:

Unmodified
Added
Removed
Modified
  • expansion/gw16126

    v1 v1  
     1[[PageOutline]]
     2
     3= GW16126 miniPCIe BLE / LTE Cat-M1 modem
     4The 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.
     5
     6The GW16126 interfaces with a host over USB 2.0 and uses the following pins on the miniPCIe card edge:
     7 - GND: pin 4,9,15,18,21,26,27,29,34,35,40,43,50
     8 - VDD_3P3: pin 2,24,39,41,52
     9 - USB_DM: pin 36
     10 - USB_DP: pin 38
     11
     12Power 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
     13
     14On the USB bus the following are present:
     15 * USB2514 USB 2.0 2-port HUB
     16  * FT231X USB UART connected to a u-blox NINA-B30x BLE module
     17  * u-blox NINA-B301 BLE module USB 2.0 controller
     18  * u-blox SARA-R4 Cat M-1 / NB1 modem with nano-SIM socket
     19
     20These look like the following with {{{lsusb}}}:
     21{{{#!bash
     22ID 05c6:90b2 Qualcomm, Inc.
     23ID 0403:6015 Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)
     24ID 0424:2514 Standard Microsystems Corp. USB 2.0 Hub
     25}}}
     26
     27The following devices will be created by the kernel modules:
     28 * /dev/ttyUSB0 (hci_uart) (CONFIG_BT_HCIUART, CONFIG_BT_HCIUART_H4 hci_uart)
     29 * /dev/ttyUSB1 (qcdm) (CONFIG_USB_SERIAL_OPTION option)
     30 * /dev/ttyUSB2 (at) (CONFIG_USB_SERIAL_OPTION option)
     31 * /dev/cdc-wdm0 (qmi) (CONFIG_USB_NET_QMI_WWAN qmi_wwan)
     32 * /sys/class/net/wwan0 (net) (CONFIG_USB_NET_QMI_WWAN qmi_wwan)
     33
     34If 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:
     35 * {{{mmcli -m 0}}} will report details about detected modems and what devices they are on
     36 * {{{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
     37 * {{{ls -d /sys/bus/usb/drivers/option/*/ttyUSB*}}} will tell you which tty's are attached to the {{{option}}} driver for the modem.
     38
     39[=#sara-r4]
     40== u-blox SARA-R4 LTE Cat M-1 modem
     41The [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.
     42
     43The modem features a Qualcomm chipset that uses the 'option1' and 'qmi_wwan' Linux drivers providing the following devices:
     44 * /dev/ttyUSB1 (qcdm)
     45 * /dev/ttyUSB2
     46 * /dev/cdc-wdm0 (qmi)
     47 * /sys/class/net/wwan0 (net)
     48
     49The modem is supported by Linux !ModemManager and libqmi-utils.
     50
     51
     52[=#nina-b3]
     53== u-blox NINA-B301 BLE module
     54The 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.
     55
     56
     57[=#hci]
     58=== Bluetooth HCI (GW16126)
     59The 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:
     60 * 1mbps baudrate
     61 * 8bits, no parity, 1 stop bit
     62 * hardware flow control required
     63
     64To use the GW16126 bluetooth HCI with Linux you need the following:
     65 * Linux 4.10+ kernel with the following:
     66  - FTDI UART support (CONFIG_USB_SERIAL_FTDI_SIO)
     67  - HCI UART with H4 (CONFIG_BT_HCIUART and CONFIG_BT_HCIUART_H4) in order to provide a bluetooth HCI over UART
     68  - 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)
     69 * Bluetooth stack such as BlueZ (4.45+)
     70
     71The following shows how you would interact with the BLE controller via BlueZ on Ubuntu bionic:
     72{{{#!bash
     73apt-get install bluez
     74# configure bluez to run expirimental features
     75sed -i '/^ExecStart=/ s/$/ -E/' /lib/systemd/system/bluetooth.service
     76# restart bluetoothd
     77sudo systemctl daemon-reload
     78sudo systemctl restart bluetooth
     79# attach HCI UART
     80dev=$(basename $(ls -d /sys/bus/usb/drivers/ftdi_sio/*/ttyUSB*))
     81modprobe hci_uart
     82btattach -B /dev/$dev -S 1000000 -P h4 &
     83# scan for BLE devices
     84hcitool -i hci0 lescan
     85}}}
     86
     87Example:
     88{{{#!bash
     89root@bionic-newport:~# echo 8 > /proc/sys/kernel/printk
     90root@bionic-newport:~# dev=$(basename $(ls -d /sys/bus/usb/drivers/ftdi_sio/*/tty
     91root@bionic-newport:~# modprobe hci_uart
     92[   35.314383] Bluetooth: Core ver 2.22
     93[   35.318121] NET: Registered protocol family 31
     94[   35.322614] Bluetooth: HCI device and connection manager initialized
     95[   35.328997] Bluetooth: HCI socket layer initialized
     96[   35.333904] Bluetooth: L2CAP socket layer initialized
     97[   35.338983] Bluetooth: SCO socket layer initialized
     98[   35.350560] Bluetooth: HCI UART driver ver 2.3
     99[   35.355057] Bluetooth: HCI UART protocol H4 registered
     100root@bionic-newport:~# btattach -B /dev/$dev -S 1000000 -P h4 &
     101[1] 2138
     102Attaching Primary controller to /dev/ttyUSB0
     103Switched line discipline from 0 to 15
     104Device index 0 attached
     105[   57.834717] Bluetooth: BNEP (Ethernet Emulation) ver 1.3
     106[   57.840137] Bluetooth: BNEP socket layer initialized
     107root@bionic-newport:~# hciconfig
     108hci0:   Type: Primary  Bus: UART
     109        BD Address: 00:00:00:00:00:00  ACL MTU: 27:7  SCO MTU: 0:0
     110        UP RUNNING
     111        RX bytes:527 acl:0 sco:0 events:41 errors:0
     112        TX bytes:258 acl:0 sco:0 commands:41 errors:0
     113
     114root@bionic-newport:~# hcitool -i hci0 lescan
     115LE Scan ...
     1163C:A3:08:10:51:FE (unknown)
     117FC:B4:88:8E:32:61 (unknown)
     118FC:B4:88:8E:32:61 (unknown)
     1193C:A3:08:10:51:FE LEDBlue-081051FE
     120
     121}}}
     122
     123 
     124
     125[=#zephyr]
     126=== Zephyr Project Firmware
     127While 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.
     128
     129The [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:
     130 * HCI uart
     131 * BLE beacon
     132
     133Gateworks has added GW16126 board support to Zephyr [https://github.com/Gateworks/zephyr.git here] via [https://github.com/Gateworks/zephyr/commit/ba5f00ad5918b44e901f356a98e63e963516a429 commit ba5f00ad]
     134
     135Examples:
     136 1. Install Zephyr source
     137{{{#!bash
     138git clone https://github.com/Gateworks/zephyr.git
     139cd ~/zephyr  # or to your directory where zephyr is cloned
     140# install more requirements via pip
     141pip3 install --user -r scripts/requirements.txt
     142}}}
     143 1. Build HCI UART (what Gateworks pre-programms into the GW16126):
     144{{{#!bash
     145# setup shell for building Zephyr
     146source zephyr-env.sh:
     147cd $ZEPHYR_BASE/samples/bluetooth/hci_uart
     148mkdir -p build/gw16126 && cd build/gw16126
     149cmake -DBOARD=nrf52840_gw16126 ../..
     150make
     151ls zephyr/zephyr.hex
     152}}}
     153 2. Build Bluetooth Beacon:
     154{{{#!bash
     155# setup shell for building Zephyr
     156source zephyr-env.sh:
     157cd $ZEPHYR_BASE/samples/bluetooth/beacon
     158mkdir -p build/gw16126 && cd build/gw16126
     159cmake -DBOARD=nrf52840_gw16126 ../..
     160make
     161ls zephyr/zephyr.hex
     162}}}
     163
     164 
     165=== Programming the nRF58240
     166While 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:
     167 * CBUS1 - SWDIO
     168 * CBUS2 - SWDCLK
     169
     170To 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+).
     171
     172The following will create a gw16126.cfg OpenOCD interface file specifying SWD and mapping the SWCLK/SWDIO pins to the FT231X CBUS2/CBUS1 pins:
     173 1. Create an OpenOCD interface file for the GW16126 that defines the Linux gpio signals for SWD:
     174{{{#!bash
     175base=$(for i in $(ls -1d /sys/class/gpio/gpiochip*); do [ "ftdi-cbus" = "$(cat $i/label)" ] && cat $i/base; done)
     176[ "$base" ] || { echo "Error: could not find ftdi-cbus device - Linux 4.20+ required"; }
     177cat << EOF > gw16126.cfg
     178interface sysfsgpio
     179transport select swd
     180Show quoted text
     181sysfsgpio_swd_nums $((base + 2)) $((base + 1))
     182EOF
     183}}}
     184 2. Build OpenOCD from git master for nRF52840 support:
     185{{{#!bash
     186apt-get install build-essential git flex bison pkg-config libtool autoconf automake texinfo libusb-1.0-0-dev
     187git clone git://git.code.sf.net/p/openocd/code openocd
     188cd openocd
     189./bootstrap
     190./configure --enable-sysfsgpio
     191make install
     192}}}
     193  - alternatively you can fetch from a zip archive via {{{wget --no-check-certificate
     194 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
     195  - 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}}}
     196 3. Program firmware:
     197{{{#!bash
     198# openocd -f gw16126.cfg -f target/nrf52.cfg \
     199   -c init -c "reset init" -c halt -c "nrf5 mass_erase" -c "program zephyr_uart_hci.hex verify" -c reset -c exit
     200Open On-Chip Debugger 0.10.0+dev-00563-gda4b2d5b (2018-10-20-01:03)
     201Licensed under GNU GPL v2
     202For bug reports, read
     203        http://openocd.org/doc/doxygen/bugs.html
     204SysfsGPIO nums: swclk = 462, swdio = 461
     205adapter speed: 1000 kHz
     206cortex_m reset_config sysresetreq
     207Info : SysfsGPIO JTAG/SWD bitbang driver
     208Info : SWD only mode enabled (specify tck, tms, tdi and tdo gpios to add JTAG mode)
     209Info : This adapter doesn't support configurable speed
     210Info : SWD DPIDR 0x2ba01477
     211Info : nrf52.cpu: hardware has 6 breakpoints, 4 watchpoints
     212Info : Listening on port 3333 for gdb connections
     213target halted due to debug-request, current mode: Thread
     214xPSR: 0x01000000 pc: 0xfffffffe msp: 0xfffffffc
     215Info : nRF52840-QIAA(build code: C0) 1024kB Flash
     216target halted due to debug-request, current mode: Thread
     217xPSR: 0x01000000 pc: 0xfffffffe msp: 0xfffffffc
     218** Programming Started **
     219auto erase enabled
     220Warn : using fast async flash loader. This is currently supported
     221Warn : only with ST-Link and CMSIS-DAP. If you have issues, add
     222Warn : "set WORKAREASIZE 0" before sourcing nrf51.cfg/nrf52.cfg to disable it
     223wrote 49152 bytes from file zephyr.hex in 117.544823s (0.408 KiB/s)
     224** Programming Finished **
     225** Verify Started **
     226verified 47036 bytes in 2.723827s (16.864 KiB/s)
     227** Verified OK **
     228}}}
     229
     230
     231=== u-blox Connectivity Software (GW16126-SP399)
     232The GW16126-SP399 comes with the nRF52840 pre-programmed (and locked) by u-blox with the u-blox Connectivity Software.
     233
     234Connection parameters:
     235 - 115200baud, 8 data bits no stop bit
     236
     237Protocol details:
     238- [https://www.u-blox.com/ja/files/u-blox-short-range-modules-commands-manual UBX-14044127 u-blox Short Range Modules] - AT Commands Manual
     239- [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]
     240
     241Examples:
     242 - Serial port interaction
     243{{{#!bash
     244# query configured role
     245AT+UBTLE?
     246+UBTLE:2
     247OK
     248
     249# set to central
     250AT+UBTLE=1
     251OK
     252
     253# store and power cycle
     254AT&W
     255OK
     256AT+CPWROFF
     257OK
     258
     259+STARTUP
     260
     261# report scan results
     262AT+UBTD
     263
     264+UBTD:FCB4888E3261r,-76,"",2,0201061AFF4C0002156445C351577C4DA9AE12E57657E78C6F0000000000
     265+UBTD:FCB4888E3261r,-77,"",1,
     266OK
     267}}}
     268 - command line usage:
     269{{{#!bash
     270dev=$(basename $(ls -d /sys/bus/usb/drivers/ftdi_sio/*/ttyUSB*))
     271stty -F $dev 115200 ignbrk -brkint -icrnl -opost -onlcr -isig -icanon -iexten -echo -echoe -echok -echoctl -echoke
     272cat $dev & # continually display responses from tty in background
     273# request manufactuer identify
     274printf 'AT+GMI\r\n' > $dev
     275# request model
     276printf 'AT+GMM\r\n' > $dev
     277# request serial number
     278printf 'AT+GSN\r\n' > $dev
     279# request misc details
     280printf 'AT+ATI0\r\n' > $dev
     281# change role to central, write nvram, and reset
     282printf 'AT+UBTLE=1\r\n' > $dev
     283printf 'AT&W\r\n' > $dev
     284printf 'AT+CPWROFF\r\n' > $dev
     285# scan for BLE devices
     286sleep 1
     287printf 'AT+UBTD\r\n' > $dev
     288}}}
     289
     290See also ublox s-center software for use on Windows
     291
     292
     293[=#software]
     294== Software Support
     295The following software is necessary for the GW16126:
     296 * LTE Cat-M1 modem:
     297  - Linux 4.5 kernel with option driver (CONFIG_USB_SERIAL_OPTION) and qmi driver (CONFIG_USB_NET_QMI_WWAN)
     298 * BLE hci:
     299  - Linux 4.5 kernel
     300  - hci_uart driver (CONFIG_BT_HCIUART, CONFIG_BT_HCIUART_H4 hci_uart)
     301  - Userspace cryptographic algorithm support (CONFIG_CRYPTO_USER_API*) (for generation of random bdaddr in BlueZ)
     302  - Bluetooth stack such as BlueZ
     303
     304Ubuntu bionic:
     305 - requires: bluez modemmanager libqmi bluez
     306 - works out of box
     307
     308OpenWrt 18.6.1:
     309 - 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
     310 - works out of the box
     311
     312OpenWrt 16.02:
     313 - will not work without backporting qmi raw-ip support and modem ID's to option1/qmi-wwan driver