1==========
2NuttX RTOS
3==========
4
5What is NuttX?
6--------------
7
8`NuttX <https://nuttx.apache.org/>`__ is a mature and secure real-time
9operating system (RTOS) with an emphasis on technical standards
10compliance and small size. It is scalable from 8-bit to 64-bit
11microcontrollers and microprocessors and compliant with the Portable
12Operating System Interface (POSIX) and the American National Standards
13Institute (ANSI) standards and with many Linux-like subsystems. The best
14way to think about NuttX is to think of it as a small Unix/Linux for
15microcontrollers.
16
17Highlights of NuttX
18~~~~~~~~~~~~~~~~~~~
19
20-  **Small** - Fits and runs in microcontrollers as small as 32 kB Flash
21   and 8 kB of RAM.
22-  **Compliant** - Strives to be as compatible as possible with POSIX
23   and Linux.
24-  **Versatile** - Supports many architectures (ARM, ARM Thumb, AVR,
25   MIPS, OpenRISC, RISC-V 32-bit and 64-bit, RX65N, x86-64, Xtensa,
26   Z80/Z180, etc.).
27-  **Modular** - Its modular design allows developers to select only
28   what really matters and use modules to include new features.
29-  **Popular** - NuttX is used by many companies around the world.
30   Probably you already used a product with NuttX without knowing it was
31   running NuttX.
32-  **Predictable** - NuttX is a preemptible Realtime kernel, so you can
33   use it to create predictable applications for realtime control.
34
35--------------
36
37Why NuttX + LVGL?
38-----------------
39
40Although NuttX has its own graphic library called
41`NX <https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=139629474>`__,
42LVGL is a good alternative because users could find more eye-candy demos
43and they can reuse code from previous projects. LVGL is an
44`Object-Oriented Component
45Based <https://blog.lvgl.io/2018-12-13/extend-lvgl-objects>`__
46high-level GUI library, that could fit very well for a RTOS with
47advanced features like NuttX. LVGL is implemented in C and its APIs are
48in C.
49
50Here are some advantages of using LVGL in NuttX
51~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
52
53-  Develop GUI in Linux first and when it is done just compile it for
54   NuttX. Nothing more, no wasting of time.
55-  Usually, GUI development for low level RTOS requires multiple
56   iterations to get things right, where each iteration consists of
57   **``Change code`` > ``Build`` > ``Flash`` > ``Run``**. Using LVGL,
58   Linux and NuttX you can reduce this process and just test everything
59   on your computer and when it is done, compile it on NuttX and that is
60   it.
61
62NuttX + LVGL could be used for
63~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
64
65-  GUI demos to demonstrate your board graphics capacities.
66-  Fast prototyping GUI for MVP (Minimum Viable Product) presentation.
67-  visualize sensor data directly and easily on the board without using
68   a computer.
69-  Final products with a GUI without a touchscreen (i.e. 3D Printer
70   Interface using Rotary Encoder to Input data).
71-  Final products with a touchscreen (and all sorts of bells and
72   whistles).
73
74--------------
75
76How to get started with NuttX and LVGL?
77---------------------------------------
78
79There are many boards in the `NuttX
80mainline <https://github.com/apache/incubator-nuttx>`__ with support for
81LVGL. Let's use the
82`STM32F429IDISCOVERY <https://www.st.com/en/evaluation-tools/32f429idiscovery.html>`__
83as an example because it is a very popular board.
84
85First you need to install the pre-requisites on your system
86~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
87
88Let's use the `Windows Subsystem for
89Linux <https://acassis.wordpress.com/2018/01/10/how-to-build-nuttx-on-windows-10/>`__
90
91.. code-block:: shell
92
93   $ sudo apt-get install automake bison build-essential flex gcc-arm-none-eabi gperf git libncurses5-dev libtool libusb-dev libusb-1.0.0-dev pkg-config kconfig-frontends openocd
94
95Now let's create a workspace to save our files
96~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
97
98.. code-block:: shell
99
100   $ mkdir ~/nuttxspace
101   $ cd ~/nuttxspace
102
103Clone the NuttX and Apps repositories:
104~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105
106.. code-block:: shell
107
108   $ git clone https://github.com/apache/incubator-nuttx nuttx
109   $ git clone https://github.com/apache/incubator-nuttx-apps apps
110
111Configure NuttX to use the stm32f429i-disco board and the LVGL Demo
112~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
113
114.. code-block:: shell
115
116   $ ./tools/configure.sh stm32f429i-disco:lvgl
117   $ make
118
119If everything went fine you should have now the file ``nuttx.bin`` to
120flash on your board:
121
122.. code-block:: shell
123
124   $ ls -l nuttx.bin
125   -rwxrwxr-x 1 alan alan 287144 Jun 27 09:26 nuttx.bin
126
127Flashing the firmware in the board using OpenOCD:
128~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
129
130.. code-block:: shell
131
132   $ sudo openocd -f interface/stlink-v2.cfg -f target/stm32f4x.cfg -c init -c "reset halt" -c "flash write_image erase nuttx.bin 0x08000000"
133
134Reset the board and using the 'NSH>' terminal start the LVGL demo:
135
136.. code-block:: shell
137
138   nsh> lvgldemo
139
140Configurations
141--------------
142Here are some configurations that you can use to customize your NuttX and LVGL setup:
143
144-  **LV_USE_NUTTX_INDEPENDENT_IMAGE_HEAP** - You can enable or disable the
145   LVGL image heap in NuttX. By default, it is disabled. If you enable
146   it, LVGL will use the NuttX heap instead.
147
148Where can I find more information?
149----------------------------------
150
151-  This blog post: `LVGL on
152   LPCXpresso54628 <https://acassis.wordpress.com/2018/07/19/running-nuttx-on-lpcxpresso54628-om13098/>`__
153-  NuttX mailing list: `Apache NuttX Mailing
154   List <http://nuttx.incubator.apache.org/community/>`__
155
156
157.. Comment:  The above blank line is necessary for Sphinx to not complain,
158    since it looks for the blank line after a bullet list.
159