diff --git a/docs/get-started/os/zephyr.rst b/docs/get-started/os/zephyr.rst index 5820814bd..40fca6620 100644 --- a/docs/get-started/os/zephyr.rst +++ b/docs/get-started/os/zephyr.rst @@ -2,4 +2,167 @@ Zephyr ====== -TODO +What is Zephyr? +--------------- + +`Zephyr `__ is an `open +source `__ real-time operating +system (RTOS) that is easy to deploy, secure, connect and manage. +It has a growing set of software libraries that can be used +across various applications and industry sectors such as +Industrial IoT, wearables, machine learning and more. +Zephyr is built with an emphasis on broad chipset support, +security, dependability, longterm support releases and a +growing open source ecosystem. + +Highlights of Zephyr +~~~~~~~~~~~~~~~~~~~~ + +- **Small** - Runs on microcontrollers as small as 8 kB Flash + and 5 kB of RAM. +- **Scalable** - Usable for complex multicore systems. +- **Customizable** - Out-of-the-box support for 500+ boards + and high portability. +- **Secure** - Built with safety and security in mind, + offers Long-term support. +- **Ecosystem** - Zephyr not only provides the RTOS kernel but + also developer tooling, device drivers, connectivity, logging, + tracing, power management and much more. +- **Decoupling** - Leverages devicetree to describe and + configure the target system. +- **Compliant** - Apps are runnable as native Linux applications, + which simplifies debugging and profiling. + +How to run LVGL on Zephyr? +-------------------------- + +To setup your development environment refer to the +`getting started guide `__. + +After you completed the setup above you can check out all of the `provided samples `__ for various boards. +You can check the list of available boards using: + +.. code:: shell + + $ west boards + +After you chose a board you can build one of the LVGL demos for it. Here we are using the :code:`native_posix` +board, which allows for running the application on your posix compliant host system: + +.. code:: shell + + $ west build -b native_posix samples/modules/lvgl/demos + +To run the application on your host: + +.. code:: shell + + $ west build -t run + +In case you chose any of the other supported boards you can flash to the device with: + +.. code:: shell + + $ west flash + +If you want to build any of the other demo applications check out the samples +`README `__. + +Leveraging Zephyr Features +-------------------------- + +Shell +~~~~~ + +Zephyr includes a powerful shell implementation that can be enabled with the Kconfig symbols +:code:`CONFIG_SHELL` and :code:`CONFIG_LV_Z_SHELL` (the demos from above have it enabled by default). + +The shell offers enabling/disabling of LVGL monkeys: + +.. code:: shell + + # Create a new monkey with the given indev type + uart$ lvgl monkey create [pointer|keypad|button|encoder] + + # Enable/Disable a monkey + uart$ lvgl monkey set + +This is useful for checking your application for memory leaks and other bugs. +Speaking of memory leaks, you can also aquire stats of the memory used by LVGL + +.. code:: shell + + uart$ lvgl stats memory + +For more details refer to the `shell documentation `__. + +Devicetree +~~~~~~~~~~ + +Zephyr uses the devicetree description language to create and manage LVGL input devices. + +The pseudo device binding descriptions can be found at: + +- `button input `__ +- `pointer input `__ +- `encoder input `__ + +Essentially those buffer the :code:`input_event` generated by the device pointed to by the :code:`input` phandle or if left +empty the binding captures all events regardless of the source. You do not have to instantiate or manage the devices yourself, +they are created at application start up before :code:`main()` is executed. + +Most boards or shields that have a display or display connector have the pointer input device already declared: + +.. code:: + + lvgl_pointer { + compatible = "zephyr,lvgl-pointer-input"; + input = <&ft5336_touch>; + }; + +You can access the underlying lvgl :code:`lv_indev_t` for configuration. +Example with the encoder device to assign a :code:`lv_group_t`: + +.. code:: c + + const struct device *lvgl_encoder = DEVICE_DT_GET(DT_COMPAT_GET_ANY_STATUS_OKAY(zephyr_lvgl_encoder_input)); + + lv_obj_t *arc; + lv_group_t *arc_group; + + arc = lv_arc_create(lv_scr_act()); + lv_obj_align(arc, LV_ALIGN_CENTER, 0, 0); + lv_obj_set_size(arc, 150, 150); + + arc_group = lv_group_create(); + lv_group_add_obj(arc_group, arc); + lv_indev_set_group(lvgl_input_get_indev(lvgl_encoder), arc_group); + + +Kconfig +~~~~~~~~ + +Aside from enabling the shell you can also use Kconfig to finetune +the footprint of your application. + +.. code:: + + # Size of the memory region from which lvgl memory is allocated + CONFIG_LV_Z_MEM_POOL_SIZE=8192 + + # Do not include every widget/theme by default, enable them as needed. + CONFIG_LV_CONF_MINIMAL=y + +Overlays can be used to enable/disable features for specific boards or build +targets. For more information refer to the +`application development guide `__. + + +Where can I find more information? +---------------------------------- + +- Zephyr Documentation: `Zephyr Documentation `__ +- Zephyr mailing list: `Zepyhr Mailing + List `__ +- Zephyr Discord server: `Zepyhr Discord + server `__