examples: zephyr: location: cellular: add README

Signed-off-by: Marcin Niestroj <[email protected]>

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 <my-psk-id@my-project>
+uart:~$ settings set golioth/psk <my-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] <inf> net_config: Initializing network
+[00:00:00.000,000] <inf> net_config: IPv4 address: 192.0.2.1
+[00:00:00.000,000] <dbg> location_cellular_main: main: Start cellular location sample
+[00:00:00.000,000] <inf> golioth_mbox: Mbox created, bufsize: 1848, num_items: 10, item_size: 168
+[00:00:00.420,003] <inf> golioth_coap_client_zephyr: Golioth CoAP client connected
+[00:00:00.420,003] <inf> location_cellular_main: Golioth client connected
+[00:00:00.420,003] <inf> golioth_coap_client_zephyr: Entering CoAP I/O loop
+[00:00:01.970,001] <inf> location_cellular_main: 50.657497640 17.947626110 (883)
+[00:00:02.240,001] <inf> location_cellular_main: 50.668119190 17.938356400 (440)
+[00:00:02.660,001] <inf> location_cellular_main: 50.668119190 17.938356400 (440)
+[00:00:03.670,001] <inf> location_cellular_main: 50.668119190 17.938356400 (440)
+[00:00:04.160,001] <inf> location_cellular_main: 50.671241280 17.938356400 (456)
+[00:00:07.180,001] <inf> location_cellular_main: 50.672496560 17.947390080 (626)
+[00:00:07.660,001] <inf> location_cellular_main: 50.672496560 17.947390080 (626)
+[00:00:08.670,001] <inf> location_cellular_main: 50.672496560 17.947390080 (626)
+[00:00:09.160,001] <inf> location_cellular_main: 50.672496560 17.947390080 (626)
+[00:00:09.770,001] <inf> location_cellular_main: 50.672496560 17.947390080 (626)
+[00:00:10.660,001] <inf> location_cellular_main: 50.667496920 17.953419690 (324)
+[00:00:11.260,001] <inf> location_cellular_main: 50.672496560 17.947390080 (626)
+```