diff --git a/examples/zephyr/location/cellular/README.md b/examples/zephyr/location/cellular/README.md new file mode 100644 index 00000000..71019f5a --- /dev/null +++ b/examples/zephyr/location/cellular/README.md @@ -0,0 +1,199 @@ +# Golioth cellular location demo + +## Overview + +This sample demonstrates how to connect to Golioth and get location +using cellular network cell towers information. + +## Requirements + +* Golioth credentials +* Network connectivity + +## Building and Running + +### Authentication specific configuration + +#### PSK based auth - Hardcoded + +Configure the following Kconfig options based on your Golioth +credentials: + +* GOLIOTH_SAMPLE_PSK_ID - PSK ID of registered device +* GOLIOTH_SAMPLE_PSK - PSK of registered device + +by adding these lines to configuration file (e.g. `prj.conf`): + +```cfg +CONFIG_GOLIOTH_SAMPLE_PSK_ID="my-psk-id" +CONFIG_GOLIOTH_SAMPLE_PSK="my-psk" +``` + +#### PSK based auth - Runtime + +We provide an option for setting Golioth credentials through the Zephyr +shell. This is based on the Zephyr Settings subsystem. + +Enable the settings shell by including the following configuration overlay +file: + +```sh +$ west build -- -DEXTRA_CONF_FILE=../../common/runtime_settings.conf +``` + +Alternatively, you can add the following options to ``prj.conf``: + +```cfg +CONFIG_GOLIOTH_SAMPLE_HARDCODED_CREDENTIALS=n + +CONFIG_FLASH=y +CONFIG_FLASH_MAP=y +CONFIG_NVS=y + +CONFIG_SETTINGS=y +CONFIG_SETTINGS_RUNTIME=y +CONFIG_GOLIOTH_SAMPLE_SETTINGS=y +CONFIG_GOLIOTH_SAMPLE_WIFI_SETTINGS=y +CONFIG_GOLIOTH_SAMPLE_SETTINGS_AUTOLOAD=y +CONFIG_GOLIOTH_SAMPLE_SETTINGS_SHELL=y +``` + +At runtime, configure PSK-ID and PSK using the device shell based on your +Golioth credentials: + +```sh +uart:~$ settings set golioth/psk-id +uart:~$ settings set golioth/psk +uart:-$ kernel reboot cold +``` + +#### Certificate based auth + +Configure the following Kconfig options based on your Golioth +credentials: + +* CONFIG_GOLIOTH_AUTH_METHOD_CERT - use certificate-based + authentication +* CONFIG_GOLIOTH_SAMPLE_HARDCODED_CRT_PATH - device certificate +* CONFIG_GOLIOTH_SAMPLE_HARDCODED_KEY_PATH - device private key + +by adding these lines to configuration file (e.g. `prj.conf`): + +```cfg +CONFIG_GOLIOTH_AUTH_METHOD_CERT=y +CONFIG_GOLIOTH_SAMPLE_HARDCODED_CRT_PATH="keys/device.crt.der" +CONFIG_GOLIOTH_SAMPLE_HARDCODED_KEY_PATH="keys/device.key.der" +``` + +### Platform specific configuration + +#### Native Simulator + +This application has been built and tested with Native Simulator +(native_sim). + +On your Linux host computer, open a terminal window, locate the source +code of this sample application (i.e., `examples/zephyr/location/cellular`) +and type: + +```console +$ west build -b native_sim examples/zephyr/location/cellular +$ west build -t run +``` + +#### ESP32-DevKitC-WROVER + +Configure the following Kconfig options based on your WiFi AP +credentials: + +- GOLIOTH_SAMPLE_WIFI_SSID - WiFi SSID +- GOLIOTH_SAMPLE_WIFI_PSK - WiFi PSK + +by adding these lines to configuration file (e.g. `prj.conf`): + +```cfg +CONFIG_GOLIOTH_SAMPLE_WIFI_SSID="my-wifi" +CONFIG_GOLIOTH_SAMPLE_WIFI_PSK="my-psk" +``` + +On your host computer open a terminal window, locate the source code of +this sample application (i.e., `examples/zephyr/location/cellular`) and type: + +```console +$ west build -b esp32_devkitc_wrover/esp32/procpu examples/zephyr/location/cellular +$ west flash +``` + +#### nRF52840 DK + ESP32-WROOM-32 + +This subsection documents using nRF52840 DK running Zephyr with +offloaded ESP-AT WiFi driver and ESP32-WROOM-32 module based board (such +as ESP32 DevkitC rev. 4) running WiFi stack. See [AT Binary +Lists](https://docs.espressif.com/projects/esp-at/en/latest/AT_Binary_Lists/index.html) +for links to ESP-AT binaries and details on how to flash ESP-AT image on +ESP chip. Flash ESP chip with following command: + +```console +esptool.py write_flash --verify 0x0 PATH_TO_ESP_AT/factory/factory_WROOM-32.bin +``` + +Connect nRF52840 DK and ESP32-DevKitC V4 (or other ESP32-WROOM-32 based +board) using wires: + +| nRF52840 DK | ESP32-WROOM-32 | ESP32-WROVER-32 | +| ----------- | --------------- | ----------------| +| P1.01 (RX) | IO17 (TX) | IO22 (TX) | +| P1.02 (TX) | IO16 (RX) | IO19 (RX) | +| P1.03 (CTS) | IO14 (RTS) | IO14 (RTS) | +| P1.04 (RTS) | IO15 (CTS) | IO15 (CTS) | +| P1.05 | EN | EN | +| GND | GND | GND | + +Configure the following Kconfig options based on your WiFi AP +credentials: + +* GOLIOTH_SAMPLE_WIFI_SSID - WiFi SSID +* GOLIOTH_SAMPLE_WIFI_PSK - WiFi PSK + +by adding these lines to configuration file (e.g. `prj.conf` or +`board/nrf52840dk_nrf52840.conf`): + +```cfg +CONFIG_GOLIOTH_SAMPLE_WIFI_SSID="my-wifi" +CONFIG_GOLIOTH_SAMPLE_WIFI_PSK="my-psk" +``` + +On your host computer open a terminal window, locate the source code of +this sample application (i.e., `examples/zephyr/location/cellular`) and type: + +```console +$ west build -b nrf52840dk/nrf52840 examples/zephyr/location/cellular +$ west flash +``` + +### Sample output + +This is the output from the serial console: + +```console +*** Booting Zephyr OS build v4.0.0-1-gb39d67f51986 *** +[00:00:00.000,000] net_config: Initializing network +[00:00:00.000,000] net_config: IPv4 address: 192.0.2.1 +[00:00:00.000,000] location_cellular_main: main: Start cellular location sample +[00:00:00.000,000] golioth_mbox: Mbox created, bufsize: 1848, num_items: 10, item_size: 168 +[00:00:00.420,003] golioth_coap_client_zephyr: Golioth CoAP client connected +[00:00:00.420,003] location_cellular_main: Golioth client connected +[00:00:00.420,003] golioth_coap_client_zephyr: Entering CoAP I/O loop +[00:00:01.970,001] location_cellular_main: 50.657497640 17.947626110 (883) +[00:00:02.240,001] location_cellular_main: 50.668119190 17.938356400 (440) +[00:00:02.660,001] location_cellular_main: 50.668119190 17.938356400 (440) +[00:00:03.670,001] location_cellular_main: 50.668119190 17.938356400 (440) +[00:00:04.160,001] location_cellular_main: 50.671241280 17.938356400 (456) +[00:00:07.180,001] location_cellular_main: 50.672496560 17.947390080 (626) +[00:00:07.660,001] location_cellular_main: 50.672496560 17.947390080 (626) +[00:00:08.670,001] location_cellular_main: 50.672496560 17.947390080 (626) +[00:00:09.160,001] location_cellular_main: 50.672496560 17.947390080 (626) +[00:00:09.770,001] location_cellular_main: 50.672496560 17.947390080 (626) +[00:00:10.660,001] location_cellular_main: 50.667496920 17.953419690 (324) +[00:00:11.260,001] location_cellular_main: 50.672496560 17.947390080 (626) +```