Difference between revisions of "Zephyr driver demo"

Revision as of 23:40, 30 August 2021

Zephyr Driver and Separate Demo

- OVERVIEW - Here list and begin to describe key, salient features of a Zephyr RTOS based driver and separately build-able demo to exercise given driver. Driver for first version 0p0 is "out of tree", in other words outside of Zephyr project's source tree.

^ Key Zephyr App Files

Move to refs:

 *  https://dev.w3.org/html5/html-author/charref   å
 *  https://meta.wikimedia.org/wiki/Table_background_colors
 
 *  https://community.jaredwolff.com/d/4-nrf-cloud-agps-sample-no-gps-data/6

Key files in the two parts of Zephyr out-of-tree driver and demonstrating app:

demo (app)
   ¦
CMakeLists.txt  <- set toolchain variant and toolchain path
Kconfig         <- refers to Zephyr top level Kconfig
west.yml        <- chooses SDK, driver projects (1)

driver
   ¦
drivers/
dts/bindings/
include/
zephyr/
   ¦
   +--module.yml
CMakeLists.txt  <- · add subdirs when given drivers enabled,
                   ▸ add include dirs holding header files
Kconfig         <- · refers to Kconfig in child 'drivers' directory
README.md

Note: the out-of-tree driver has a zephyr/module.yml dir and file. The zephyr app does not.

All the more that is in Jared Wolff's AQW demo:

ted@localhost:~/projects/embedded/ncs/zephyr/samples/sandbox-de-ted/jared-wolff/demo$ tree -R
.
├── boards
│   ├── nrf52840dk_nrf52840.conf
│   └── nrf52840dk_nrf52840.overlay
├── CMakeLists.txt
├── Kconfig
├── prj.conf
├── prj.debug.conf
├── prj.release.conf
├── README.md
├── src
│   └── main.c
├── west.yml
└── z--build-messages-001--first-build.txt

2 directories, 11 files

^ Useful Commands To Manage Details

Command available on Ubuntu hosts to effectively locate Zephyr RTOS project installations:

   ted@localhost:~/projects/embedded$ locate VERSION | grep 'ION$'

Committing changes to Zephyr app dependencies which are secondary git repositories linked and locally updated via `west` and the given project's west.yml manifest file:

Command line excerpt - switch from git project detached head to 'main' branch of development, and merge:

 1053  git status
 1054  git checkout main
 1055  git merge c601129

In the above excerpt the argument to `git merge` is the start of the commit hash of the detached head commit history which, for some reason `west` meta-tool creates whenever developer issues `west update` in a local Zephyr application project. The commit hash here is arbitrary. It will be different pretty much every time a developer updates local code from remote repositories. Important to make a note of most recent hash before checking out a named branch!

^ New Zephyr app west init and update

Upon, after first invocation of `west init && west update` in a newly cloned Zephyr app project, files pulled down include:

ted@localhost:~/projects/sandbox-2/kionix-driver-demo$ ls
bootloader  modules  tools  west.yml  zephyr
ted@localhost:~/projects/sandbox-2/kionix-driver-demo$ git status .
On branch main
Your branch is up to date with 'origin/main'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	.west/
	bootloader/
	modules/
	tools/
	zephyr/

nothing added to commit but untracked files present (use "git add" to track)

The west.yml file specifies an ncs software development kit, which include Zephyr and bootloader. All the directories and files above not tracked by git were downloaded by the `west` meta-tool. So this non-tracking is consistent with the way `west` works, and brings in files to a `west manifest` project that is itself under git control.

^ Zephyr Overlay Files and Device Node Label Strings

Given a meta-compiled symbol assignment which takes a DTS node 'label' string, best to avoid use of minus character in these labels:

ted@ubuntu-vm-0p2:~/embedded/z1-sandbox-2021-08-26/kionix-driver-demo$ grep -nr KX132-1211 ./*

Binary file ./boards/.sparkfun_thing_plus_nrf9160.overlay.swp matches
./boards/nrf9160dk_nrf9160ns.overlay:14:                label = "KX132-1211";
./boards/sparkfun_thing_plus_nrf9160.overlay:15:                label = "KX132-1211";
./boards/nrf9160dk_nrf9160.overlay:14:                label = "KX132-1211";
./build/mcuboot/zephyr/.config:421:# KX132-1211 driver
./build/mcuboot/zephyr/.config:423:# end of KX132-1211 driver
./build/zephyr/include/generated/autoconf.h:61:#define CONFIG_KX132_1211_DRV_NAME "KX132-1211"
./build/zephyr/include/generated/devicetree_unfixed.h:6118:#define DT_N_S_soc_S_peripheral_50000000_S_i2c_9000_S_kx132_1211_1f_P_label "KX132-1211"
./build/zephyr/sparkfun_thing_plus_nrf9160.dts.pre.tmp:645:                label = "KX132-1211";
./build/zephyr/zephyr.dts:253:                                  label = "KX132-1211";
./build/zephyr/.config:346:# KX132-1211 driver
./build/zephyr/.config:349:CONFIG_KX132_1211_DRV_NAME="KX132-1211"
./build/zephyr/.config:350:# end of KX132-1211 driver
Binary file ./build/zephyr/edt.pickle matches

ted@ubuntu-vm-0p2:~/embedded/z1-sandbox-2021-08-26/kionix-driver-demo$

^ Zephyr Project Uniform Sensor API

Zephyr Project's notion of sensor channels for reading back data in given units is important. Here is a starting point documentation on this topic:

• https://docs.zephyrproject.org/1.14.1/reference/peripherals/sensor.html

^ Programmatic Chain From main Function To Print Sensor Readings

This section aims to capture a clear sequence of C-based routines and routine calls, from int main() to an effective printf() type of function in a Zephyr RTOS application. In part this wiki page section is motivated by Zephyr's multiple ways of obtaining programmatic handles or pointers to devices, and what appear to be at least two distinct but strictly guided ways of connecting app code to a sensor driver API.

Though we cannot build and test it for lack of specific development board, Jared Wolff's Air Quality Wing driver demo we assume compiles and runs correctly given Jared's sharing of the project, and addition of two sensors in the past two weeks. We'll use this as a starting point looking at 'main.c' and 'inc main()' there . . .

err = aqw_init(sensors, ARRAY_SIZE(sensors), sensor_cb);

Hmm we haven't searched very far and already find that 'device_get_binding()' is not directly defined seemingly anywhere in Zephyr 2.6.0 sources. In zephyr/kernel/device.c there are defs for const struct device *z_impl_device_get_binding() and static inline const struct device *z_vrfy_device_get_binding().

./kernel/device.c:104:const struct device *z_impl_device_get_binding(const char *name)
./kernel/device.c:136:static inline const struct device *z_vrfy_device_get_binding(const char *name)

Some related information and explanation of the two ways to obtain handles/pointers to devices in Zephyr app in this document:

• https://docs.zephyrproject.org/latest/guides/dts/howtos.html#get-devicetree-outputs
• https://docs.zephyrproject.org/latest/guides/dts/howtos.html#get-a-struct-device-from-a-devicetree-node

Research and review also zephyr/include/device.h header file section with comment block:

 .
 .
 .
122 /**
123  * @def DEVICE_DEFINE
124  *
125  * @brief Create device object and set it up for boot time initialization,
126  * with the option to pm_control. In case of Device Idle Power
127  * Management is enabled, make sure the device is in suspended state after
128  * initialization.
129  *
130  * @details This macro defines a device object that is automatically
131  * configured by the kernel during system initialization. Note that
132  * devices set up with this macro will not be accessible from user mode
133  * since the API is not specified;
134  *
135  * @param dev_name Device name. This must be less than Z_DEVICE_MAX_NAME_LEN
136  * characters (including terminating NUL) in order to be looked up from user
137  * mode with device_get_binding().
138  *
 .
 .
 .