github-code/lvgl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(bindings): proofread batch 20 (#7764)

Browse Source
This commit is contained in:
Victor Wheeler
2025-02-24 15:24:51 -07:00
committed by GitHub
parent d4b5bf8af0
commit fb3903c55e
6 changed files with 396 additions and 350 deletions
Download Patch File Download Diff File Expand all files Collapse all files

335
docs/details/integration/bindings/api_json.rst
View File

@@ -1,258 +1,273 @@
Output API as JSON data
.. _output_api_as_json_data:
=======================
Output API as JSON Data
=======================
We have written a script that will read the header files in LVGL and outputs a more friendly JSON format for the API.
This is done so that bindings that generate code automatically will have an easy way to collect the needed information
without having to reinvent the wheel. The JSON data format has already made libraries for reading the format for just
about every programming language out there.
As of 20-Jun-2024, LVGL comes packaged with a Python script
(``./scripts/gen_json/gen_json.py``) that reads the header files in LVGL and outputs
a more friendly JSON format for the API. This is done so that bindings that generate
code automatically will have an easy way to collect the needed information without
having to reinvent the wheel. JSON format was chosen because there are libraries for
reading JSON data in almost every programming language.
The script in order to run does have some requirements.
Requirements
************
- Python >= 3.10
- Pycparser >= 2.21: Python Library for reading the preprocessor ouotput from the C compiler
- PyMSVC >= 0.4.0: Python library is using MSVC Compiler
- C compiler, gcc for Linux, clang for OSX and MSVC for Windows
- Doxygen: used to read the docstrings from the header files.
- Pycparser >= 2.22: Python Library for reading C preprocessor output
- PyMSVC >= 0.4.0: Python library for using the MSVC Compiler
- A C compiler: gcc for Linux, clang for OSX and MSVC for Windows
- Doxygen: used to read Doxygen comments (the API documentation) from the header files.
There are several options when running the script. They are as follows
- `--output-path`: output directory for JSON file. If one is not supplied then it will be output stdout
- `--lvgl-config`: path to lv_conf.h (including file name), if this is not set then a config file will be
generated that has most common things turned on
- `--develop`: leaves the temporary folder in place.
Usage
*****
Command-Line Options
--------------------
to use the script
- ``--output-path``: output directory for JSON file. If one is not supplied then it
will be output to stdout.
- ``--lvgl-config``: path to lv_conf.h (including file name). If this is not set then
a config file will be generated that has the most common LVGL options turned on.
- ``--develop``: leaves the files generated in the temporary folder in place.
Examples
--------
Normal usage:
.. code-block:: shell
python /scripts/gen_json/gen_json.py --output-path=json/output/directory --lvgl-config=path/to/lv_conf.h
python ./scripts/gen_json/gen_json.py --output-path=json/output/directory --lvgl-config=path/to/lv_conf.h
or if you want to run a subprocess from inside of a generation script and read the output from stdout
If you want to run a subprocess from inside of a generation script and read the output from stdout:
.. code-block:: shell
python /scripts/gen_json/gen_json.py --lvgl-config=path/to/lv_conf.h
python ./scripts/gen_json/gen_json.py --lvgl-config=path/to/lv_conf.h
Output Data
-----------
The JSON data is broken apart into a couple of main categories.
The contents of the output file is a large JSON object (``{...}``) with the following
key/value pairs (these are the keys):
- enums
- functions
- function_pointers
- structures
- unions
- variables
- typedefs
- forward_decls
- macros
.. parsed-literal::
Those categories are the element names undert the root of the JSON data.
The value for each categry is an array of JSON elements. There is a bit of
nesting with the elements in the arrays and I have created "json_types" that
will allow you to identify exactly what you are dealing with.
{
"enums" : [...],
"functions" : [...],
"function_pointers": [...],
"structures" : [...],
"unions" : [...],
"variables" : [...],
"typedefs" : [...],
"forward_decls" : [...],
"macros" : [...]
}
The different "json_types" are as follows:
As you can see, the value of each of these elements is an array. The elements in
each array are JSON objects, each with a structure unique to the type indicated by
the parent element name (e.g. "enums", "functions", etc.).
A key/value pair has been added to each object (key = "json_type") to make it possible
to pass an object to a generic function and have each object know its own type through
this field. The possible "json_type" values are:
- ``"array"``: The array type is used to identify arrays.
Available JSON fields:
- ``"dim"``: number of items in the array
Fields:
- ``"dim"``: number of items in array
- ``"quals"``: array of qualifiers, IE "const"
- ``"type"``: This may or may not be available.
- ``"name"``: the name of the data type
- ``"name"``: name of data type
- ``"field"``: This type is used to describe fields in structures and unions.
It is used in the ``"fields"`` array of the ``"struct"`` and ``"union"`` JSON types.
It is used in the ``"fields"`` array of the ``"struct"`` and ``"union"`` types
covered below.
Available JSON fields:
- ``"name"``: The name of the field.
- ``"type"``: This contains the type information for the field. Check the
``"json_type"`` to know what type you are dealing with.
- ``"bitsize"``: The number of bits the field has or ``null``
if there is no bit size defined
- ``"docstring"``: you should know what this is.
Fields:
- ``"name"``: field name
- ``"type"``: data type
``"json_type"`` carries object type (e.g. "enum", "function", etc.) identifying the top-level group it comes from
- ``"bitsize"``: The number of bits for bit-fields, or ``null`` for normal field types.
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"arg"``: Used to describe an argument/parameter in a function or a function pointer.
- ``"arg"``: Describes a function argument
Available JSON fields:
- ``"name"``: The name of the argument/parameter.
- ``"type"``: This contains the type information for the field. Check the
``"json_type"`` to know what type you are dealing with.
- ``"docstring"``: you should know what this is.
- ``"quals"``: array of qualifiers, IE "const"
Fields:
- ``"name"``: argument name
- ``"type"``: data type
``"json_type"`` carries object type (e.g. "enum", "function", etc.) identifying the top-level group it comes from.
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"forward_decl"``: Describes a forward declaration.There are structures in
- ``"forward_decl"``: Describes a forward declaration. There are structures in
LVGL that are considered to be private and that is what these desccribe.
Available JSON fields:
- ``"name"``: The name of the formard declaration.
- ``"type"``: This contains the type information for the field. Check the
``"json_type"`` to know what type you are dealing with.
- ``"docstring"``: you should know what this is.
- ``"quals"``: array of qualifiers, IE "const"
Fields:
- ``"name"``: name of forward declaration
- ``"type"``: data type
``"json_type"`` carries object type (e.g. "enum", "function", etc.) identifying the top-level group it comes from.
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"function_pointer"``: Describes a function pointer. These are used when
- ``"function_pointer"``: Describes a function pointer. These are used when
registering callback functions in LVGL.
Available JSON fields:
- ``"name"``: The name of the function pointer.
- ``"type"``: This contains the return type information for the function pointer.
- ``"docstring"``: you should know what this is.
- ``"args"``: array of ``"arg"`` Widgets. This describes the function arguments/parameters.
- ``"quals"``: array of qualifiers, IE "const"
Fields:
- ``"name"``: name of function pointer
- ``"type"``: function return type
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"args"``: array of ``"arg"`` objects described above
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"variable"``: Describes a global variable.
Available JSON fields:
- ``"name"``: The name of the variable.
- ``"type"``: This contains the type information for the field. Check the
``"json_type"`` to know what type you are dealing with.
- ``"docstring"``: you should know what this is.
- ``"quals"``: array of qualifiers, IE "const"
- ``"storage"``: array of storage classifiers, IE "extern"
Fields:
- ``"name"``: variable name
- ``"type"``: data type
``"json_type"`` carries object type (e.g. "enum", "function", etc.) identifying the top-level group it comes from.
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"storage"``: array of any storage-class specifiers present (e.g. "auto", "static", "extern", etc.)
- ``"special_type"``: Currently only used to describe an ellipsis argument
for a function.
- ``"special_type"``: Currently only used to describe an ellipsis argument of a function.
Available JSON fields:
- ``"name"``: will always be "ellipsis".
Fields:
- ``"name"``: always "ellipsis"
- ``"primitive_type"``: This is a base type. There or no other types beneith this.
This tells you that the type is a basic or primitive C type.
IE: struct, union, int, unsigned int, etc...
- ``"primitive_type"``: Data type that does not begin with ``"lv_"`` and end with
``"_t"``. Compare to ``"lvgl_type"`` This includes struct, union, integral types
(e.g. int, unsigned int), etc..
Available JSON fields:
- ``"name"``: The name of the primitive type.
Fields:
- ``"name"``: name of primitive type
- ``"enum"``: Describes a grouping of enumeration items/members.
- ``"enum"``: C enumerations
Available JSON fields:
- ``"name"``: The name of the enumeration group/type.
- ``"type"``: This contains the type information for the enumeration group.
This is always going to be an "int" type. Make sure you do not use this
type as the type for the members of this enumeration group. Check the
enumeration members type to get the correct type.
- ``"docstring"``: you should know what this is.
- ``"members"``: array of ``"enum_member"`` Widgets
Fields:
- ``"name"``: If enumeration is the result of a ``typedef``, this field carries
the type name defined. Example: ``lv_align_t``. (Not always available.)
- ``"type"``: type of enumerators (always "int")
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"members"``: array of ``"enum_member"`` objects
- ``"enum_member"``: Describes an enumeration item/member. Only found under
the ``"members"`` field of an ``"enum"`` JSON type
- ``"enum_member"``: enumerator (enumeration value). This "json_type" is only found
in the ``"members"`` array of an ``"enum"`` object
Available JSON fields:
- ``"name"``: The name of the enumeration.
- ``"type"``: This contains the type information for the enum member.
This gets a bit tricky because the type specified in here is not always
going to be an "int". It will usually point to an lvgl type and the type
of the lvgl type can be found in the ``"typedefs"`` section.
- ``"docstring"``: you should know what this is.
- ``"value"``: the enumeration member/item's value
Fields:
- ``"name"``: enumerator name
- ``"type"``: If enumeration is the result of a ``typedef``, this field carries
the type name defined. Example: ``lv_align_t``.
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"value"``: enumerator value
- ``"lvgl_type"``: This is a base type. There or no other types beneith this.
This tells you that the type is an LVGL data type.
- ``"lvgl_type"``: Data type defined in LVGL (begins with ``"lv_"`` and ends with ``"_t"``.
Available JSON fields:
- ``"name"``: The name of the type.
- ``"quals"``: array of qualifiers, IE "const
Fields:
- ``"name"``: type name
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"struct"``: Describes a structure
- ``"struct"``: C struct
Available JSON fields:
- ``"name"``: The name of the structure.
- ``"type"``: This contains the primitive type information for the structure.
- ``"docstring"``: you should know what this is.
Fields:
- ``"name"``: struct name (data type if defined by ``typedef``)
- ``"type"``: a "primitive_type" object {"name": "struct", "json_type": "primitive_type"}. (See definition above.)
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"fields"``: array of ``"field"`` objects (See definition above.)
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"union"``: C union
Fields:
- ``"name"``: union name (data type if defined by ``typedef``)
- ``"type"``: a "primitive_type" object {"name": "union", "json_type": "primitive_type"}. (See definition above.)
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"fields"``: array of ``"field"`` elements.
- ``"quals"``: array of qualifiers, IE "const"
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"union"``: Describes a union
Available JSON fields:
- ``"name"``: The name of the union.
- ``"type"``: This contains the primitive type information for the union.
- ``"docstring"``: you should know what this is.
- ``"fields"``: array of ``"field"`` elements.
- ``"quals"``: array of qualifiers, IE "const"
- ``"macro"``: describes a macro. There is limited information that can be
- ``"macro"``: C macro. There is limited information that can be
collected about macros and in most cases a binding will need to have these
statically added to a binding. It is more for collecting the docstrings than
statically added to a binding. It is more for collecting the docstrings than
anything else.
Available JSON fields:
- ``"name"``: The name of the macro.
- ``"docstring"``: you should know what this is.
Fields:
- ``"name"``: macro name
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"ret_type"``: return type from a function. This is only going to be seen in the ``"type"``
element of a ``"function"`` type.
Available JSON fields:
- ``"type"``: This contains the type information for the field. Check the
``"json_type"`` to know what type you are dealing with.
- ``"docstring"``: you should know what this is.
Fields:
- ``"type"``: data type
``"json_type"`` carries object type (e.g. "enum", "function", etc.) identifying the top-level group it comes from.
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"function"``: Describes a function.
- ``"function"``: C function
Available JSON fields:
- ``"name"``: The name of the function.
- ``"type"``: This contains the type information for the return value.
- ``"docstring"``: you should know what this is.
- ``"args"``: array of ``"arg"`` json types. This describes the function arguments/parameters.
Fields:
- ``"name"``: function name
- ``"type"``: A "ret_type" object. (See definition above.)
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"args"``: array of ``"arg"`` json types. (See definition above.)
- ``"stdlib_type"``: This is a base type, meaning that there are no more
type levels beneith this. This tells us that the type is from the C stdlib.
- ``"stdlib_type"``: C integral type (int, unsigned int, float, etc.)
Available JSON fields:
- ``"name"``: The name of the type.
- ``"quals"``: array of qualifiers, IE "const
Fields:
- ``"name"``: type name
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"unknown_type"``: This should not be seen. If it is then there needs to be
an adjustment made to the script. Please open an issue and let us know if you see this type.
Available JSON fields:
- ``"name"``: The name of the type.
- ``"quals"``: array of qualifiers, IE "const
Fields:
- ``"name"``: type name
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"pointer"``: This is a wrapper object to let you know that the type you
are dealing with is a pointer
- ``"pointer"``: C pointer
Available JSON fields:
- ``"type"``: This contains the type information for the pointer. Check the
``"json_type"`` to know what type you are dealing with.
- ``"quals"``: array of qualifiers, IE "const", may or may not be available.
Fields:
- ``"type"``: pointer type
``"json_type"`` carries object type (e.g. "enum", "function", etc.) identifying the top-level group it comes from.
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"typedef"``: type definitions. I will explain more on this below.
- ``"typedef"``: C type definition
Available JSON fields:
- ``"name"``: The name of the typedef.
- ``"type"``: This contains the type information for the field. Check the
``"json_type"`` to know what type you are dealing with.
- ``"docstring"``: you should know what this is.
- ``"quals"``: array of qualifiers, IE "const"
Fields:
- ``"name"``: type name (e.g. ``lv_part_t``)
- ``"type"``: a "primitive_type" object {"name": "uint32_t", "json_type": "stdlib_type"}. (See definition above.)
``"json_type"`` carries object type (e.g. "enum", "function", etc.) identifying the top-level group it comes from.
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"quals"``: array of any qualifiers present, e.g. "const"
Here is an example of what the output will look like.
Here is a shortened example of what the output looks like.
.. code-block:: json

46
docs/details/integration/bindings/javascript.rst
View File

@@ -2,31 +2,18 @@
JavaScript
==========
With `lv_binding_js <https://github.com/lvgl/lv_binding_js>`__ you can write lvgl with JavaScript.
With `lv_binding_js <https://github.com/lvgl/lv_binding_js>`__ you can use LVGL from within JavaScript.
It uses React's virtual DOM concept to manipulate lvgl UI components, providing a familiar React-like
It uses React's virtual DOM concept to manipulate LVGL UI components, providing a familiar React-like
experience to users.
**Code**
**Code Running on Real Device**
Table of Contents
-----------------
- `Features <#features>`__
- `Demo <#demo>`__
- `Building <#building>`__
- `Components <#components>`__
- `Font <#font>`__
- `Animation <#animation>`__
- `Style <#style>`__
- `JSAPI <#jsapi>`__
- `Thanks <#thanks>`__
Features
--------
********
- Support all lvgl built-in components
- Fully support lvgl flex and grid style
@@ -36,34 +23,33 @@ Features
Demo
----
****
See the `demo <https://github.com/lvgl/lv_binding_js/tree/master/demo>`__ folder
Building
--------
********
The following are developer notes on how to build lvgljs on your native platform. They are not complete guides,
but include notes on the necessary libraries, compile flags, etc.
lvgljs
~~~~~~
------
- `ubuntu build Notes for sdl simulator <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-ubuntu-arm.md>`__
- `macos x86 build Notes for sdl simulator <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-macos-x86-simulator.md>`__
- `ubuntu build Notes for platform arm <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-ubuntu-x86-simulator.md>`__
- `Build Notes for embedded Linux device <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-device.md>`__
- `Build Notes for SDL Simulator (Linux and macOS) <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-simulator.md>`__
JS Bundle
~~~~~~~~~
---------
- `JS Bundle build Notes <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/js-bundle.md>`__
Components
----------
**********
- `View <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/View.md>`__
- `Image <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Image.md>`__
@@ -83,19 +69,19 @@ Components
Font
----
****
- `Builtin-Symbol <https://github.com/lvgl/lv_binding_js/blob/master/doc/Symbol/symbol.md>`__
Animation
---------
*********
- `Animation <https://github.com/lvgl/lv_binding_js/blob/master/doc/animate/animate.md>`__
Style
-----
*****
.. include::https://github.com/lvgl/lv_binding_js/blob/master/doc/style/position-size-layout.md
@@ -117,7 +103,7 @@ Style
JSAPI
-----
*****
- `network <https://github.com/lvgl/lv_binding_js/blob/master/doc/jsapi/network.md>`__
- `filesystem <https://github.com/lvgl/lv_binding_js/blob/master/doc/jsapi/fs.md>`__
@@ -125,9 +111,9 @@ JSAPI
Thanks
------
******
lvgljs depends on following excellent work
**lvgljs** depends on following excellent work:
- `lvgl <https://github.com/lvgl/lvgl>`__: Create beautiful UIs for any MCU, MPU and display type
- `QuickJS <https://bellard.org/quickjs/>`__: JavaScript engine

151
docs/details/integration/bindings/micropython.rst
View File

@@ -6,46 +6,49 @@ MicroPython
What is MicroPython?
--------------------
********************
`MicroPython <http://micropython.org/>`__ is Python for microcontrollers. Using MicroPython, you can write Python3
code and run it even on a bare metal architecture with limited resources.
`MicroPython <http://micropython.org/>`__ is Python for microcontrollers. Using
MicroPython, you can write Python3 code and run it even on a bare metal architecture
with limited resources. One of its powerful features is the ability to change the
behavior of a device by changing the Python code on removable (or internal) storage,
without having to change the device's firmware.
Highlights of MicroPython
~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------
- **Compact**: Fits and runs within just 256k of code space and 16k of RAM. No OS is needed, although you
can also run it with an OS, if you want.
- **Compatible**: Strives to be as compatible as possible with normal Python (known as CPython).
- **Versatile**: Supports many architectures (x86, x86-64, ARM, ARM Thumb, Xtensa).
- **Interactive**: No need for the compile-flash-boot cycle. With the REPL (interactive prompt) you can type
commands and execute them immediately, run scripts, etc.
- **Popular**: Many platforms are supported. The user base is growing bigger. Notable forks:
:Compact: Fits and runs within just 256k of code space and 16k of RAM. No OS is
needed, although you can also run it with an OS, if you want.
:Compatible: Strives to be as compatible as possible with normal Python (known as CPython).
:Versatile: Supports many architectures (x86, x86-64, ARM, ARM Thumb, Xtensa).
:Interactive: No need for the compile-flash-boot cycle. With the REPL (interactive
prompt) you can type commands and execute them immediately, run scripts, etc.
:Popular: Many platforms are supported. The user base is growing larger. Notable forks:
- `MicroPython <https://github.com/micropython/micropython>`__
- `CircuitPython <https://github.com/adafruit/circuitpython>`__
- `MicroPython_ESP32_psRAM_LoBo <https://github.com/loboris/MicroPython_ESP32_psRAM_LoBo>`__
- `MicroPython <https://github.com/micropython/micropython>`__
- `CircuitPython <https://github.com/adafruit/circuitpython>`__
- `MicroPython_ESP32_psRAM_LoBo <https://github.com/loboris/MicroPython_ESP32_psRAM_LoBo>`__
- **Embedded Oriented**: Comes with modules specifically for embedded systems, such as the
`machine module <https://docs.micropython.org/en/latest/library/machine.html#classes>`__
for accessing low-level hardware (I/O pins, ADC, UART, SPI, I2C, RTC, Timers etc.)
:Embedded Oriented: Comes with modules specifically for embedded systems, such as the
`machine module <https://docs.micropython.org/en/latest/library/machine.html#classes>`__
for accessing low-level hardware (I/O pins, ADC, UART, SPI, I2C, RTC, Timers etc.)
--------------
Why MicroPython + LVGL?
-----------------------
***********************
MicroPython `does not have a good native high-level GUI library <https://forum.micropython.org/viewtopic.php?f=18&t=5543>`__.
LVGL is an `Object-Oriented Component Based <https://blog.lvgl.io/2018-12-13/extend-lvgl-objects>`__
high-level GUI library, which seems to be a natural candidate to map into a higher level language, such as Python.
high-level GUI library, which is a natural candidate to map into a higher level language, such as Python.
LVGL is implemented in C and its APIs are in C.
Here are some advantages of using LVGL in MicroPython:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------------------------------
- Develop GUI in Python, a very popular high level language. Use paradigms such as Object-Oriented Programming.
- Usually, GUI development requires multiple iterations to get things right. With C, each iteration consists of
@@ -55,24 +58,26 @@ Here are some advantages of using LVGL in MicroPython:
MicroPython + LVGL could be used for:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------
- Fast prototyping GUI.
- Shortening the cycle of changing and fine-tuning the GUI.
- Modelling the GUI in a more abstract way by defining reusable composite Widgets, taking advantage of Python's language features
such as Inheritance, Closures, List Comprehension, Generators, Exception Handling, Arbitrary Precision Integers and others.
- Make LVGL accessible to a larger audience. No need to know C to create a nice GUI on an embedded system. This goes well with
- Fast GUI prototyping
- Shortening the cycle of changing and fine-tuning a GUI
- Modelling a GUI in a more abstract way by defining reusable composite Widgets,
taking advantage of Python's language features such as Inheritance, Closures, List
Comprehension, Generators, Exception Handling, Arbitrary Precision Integers and others.
- Make LVGL accessible to a larger audience. No need to know C to create a nice GUI
on an embedded system. This goes well with
`CircuitPython vision <https://learn.adafruit.com/welcome-to-circuitpython/what-is-circuitpython>`__.
CircuitPython was designed with education in mind, to make it easier for new or inexperienced users to get started with
embedded development.
CircuitPython was designed with education in mind, to make it easier for new or
inexperienced programmers to get started with embedded development.
- Creating tools to work with LVGL at a higher level (e.g. drag-and-drop designer).
--------------
So what does it look like?
--------------------------
What does it look like?
***********************
It's very much like the C API, but Object-Oriented for LVGL components.
@@ -80,7 +85,7 @@ Let's dive right into an example!
A simple example
~~~~~~~~~~~~~~~~
----------------
.. code-block:: python
@@ -97,12 +102,12 @@ A simple example
lv.screen_load(scr)
How can I use it?
-----------------
How Can I Use It?
*****************
Online Simulator
~~~~~~~~~~~~~~~~
----------------
If you want to experiment with LVGL + MicroPython without downloading anything, you can use our online
simulator! It's a fully functional LVGL + MicroPython that runs entirely in the browser and allows you to
@@ -114,27 +119,30 @@ Many :ref:`LVGL examples <examples>` are available also for MicroPython. Just cl
PC Simulator
~~~~~~~~~~~~
------------
MicroPython is ported to many platforms. One notable port is "unix", which allows you to build and run MicroPython
(+LVGL) on a Linux machine. (On a Windows machine you might need Virtual Box or WSL or MinGW or Cygwin etc.)
MicroPython is ported to many platforms. One notable port is to "Unix", which allows
you to build and run MicroPython (+LVGL) on a Linux machine. (On a Windows machine
you might need Virtual Box or WSL or MinGW or Cygwin etc.)
`Click here to know more information about building and running the unix port <https://github.com/lvgl/lv_micropython>`__
`Click here to learn more about building and running the Unix port. <https://github.com/lvgl/lv_micropython>`__
Embedded Platforms
~~~~~~~~~~~~~~~~~~
------------------
In the end, the goal is to run it all on an embedded platform. Both MicroPython and LVGL can be used on many embedded
architectures. `lv_micropython <https://github.com/lvgl/lv_micropython>`__ is a fork of MicroPython+LVGL and currently
supports Linux, ESP32, STM32 and RP2. It can be ported to any other platform supported by MicroPython.
In the end, the goal is to run it all on an embedded platform. Both MicroPython and LVGL can
be used on many embedded architectures. `lv_micropython <https://github.com/lvgl/lv_micropython>`__
is a fork of MicroPython+LVGL and currently supports Linux, ESP32, STM32 and RP2.
It can be ported to any other platform supported by MicroPython.
- You would also need display and input drivers. You can either use one of the existing drivers provided with lv_micropython,
or you can create your own input/display drivers for your specific hardware.
- Drivers can be implemented either in C as a MicroPython module, or in pure Python!
- You would also need display and input drivers. You can either use one of the
existing drivers provided with lv_micropython, or you can create your own
input/display drivers for your specific hardware.
- Drivers can be implemented either in C as a MicroPython module, or in pure Python.
lv_micropython already contains these drivers:
**lv_micropython** already contains these drivers:
- Display drivers:
@@ -164,7 +172,7 @@ lv_micropython already contains these drivers:
Where can I find more information?
----------------------------------
**********************************
- ``lv_micropython`` `README <https://github.com/lvgl/lv_micropython>`__
- ``lv_binding_micropython`` `README <https://github.com/lvgl/lv_binding_micropython>`__
@@ -174,7 +182,7 @@ Where can I find more information?
The MicroPython Binding is auto generated!
------------------------------------------
******************************************
- LVGL is a git submodule inside `lv_micropython <https://github.com/lvgl/lv_micropython>`__
(LVGL is a git submodule of `lv_binding_micropython <https://github.com/lvgl/lv_binding_micropython>`__
@@ -184,7 +192,7 @@ The MicroPython Binding is auto generated!
LVGL C API Coding Conventions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------
For a summary of coding conventions to follow see the :ref:`coding-style`.
@@ -192,30 +200,31 @@ For a summary of coding conventions to follow see the :ref:`coding-style`.
.. _memory_management:
Memory Management
~~~~~~~~~~~~~~~~~
-----------------
- When LVGL runs in MicroPython, all dynamic memory allocations (:cpp:func:`lv_malloc`) are handled by MicroPython's memory
manager which is `garbage-collected <https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)>`__ (GC).
- To prevent GC from collecting memory prematurely, all dynamic allocated RAM must be reachable by GC.
- GC is aware of most allocations, except from pointers on the `Data Segment <https://en.wikipedia.org/wiki/Data_segment>`__:
- To prevent GC from collecting memory prematurely, all dynamic allocated RAM must be reachable by the GC.
- GC is aware of most allocations, except from pointers to the `Data Segment <https://en.wikipedia.org/wiki/Data_segment>`__:
- Pointers which are global variables
- Pointers which are static global variables
- Pointers which are static local variables
Such pointers need to be defined in a special way to make them reachable by GC
Such pointers need to be defined in a special way to make them reachable by the GC.
Identify The Problem
^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~
Problem happens when an allocated memory's pointer (return value of :cpp:func:`lv_malloc`) is stored only in either **global**,
**static global** or **static local** pointer variable and not as part of a previously allocated ``struct`` or other variable.
A problem occurs when an allocated memory's pointer (return value of :cpp:func:`lv_malloc`)
is stored only in either **global**, **static global** or **static local** pointer
variable and not as part of a previously allocated ``struct`` or other variable.
Solve The Problem
^^^^^^^^^^^^^^^^^
Solving the Problem
~~~~~~~~~~~~~~~~~~~
- Replace the global/static local var with :cpp:expr:`(LV_GLOBAL_DEFAULT()->_var)`
- Include ``lv_global.h`` on files that use ``LV_GLOBAL_DEFAULT``
@@ -223,11 +232,11 @@ Solve The Problem
Example
^^^^^^^
~~~~~~~
More Information
^^^^^^^^^^^^^^^^
Further Reading on Memory Management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- `In the README <https://github.com/lvgl/lv_binding_micropython#memory-management>`__
- `In the Blog <https://blog.lvgl.io/2019-02-20/micropython-bindings#i-need-to-allocate-a-littlevgl-struct-such-as-style-color-etc-how-can-i-do-that-how-do-i-allocatedeallocate-memory-for-it>`__
@@ -236,13 +245,13 @@ More Information
.. _callbacks:
Callbacks
~~~~~~~~~
---------
In C a callback is just a function pointer. But in MicroPython we need to register a *MicroPython callable object* for each
callback. Therefore in the MicroPython binding we need to register both a function pointer and a MicroPython object for every callback.
Therefore we defined a **callback convention** for the LVGL C API that expects lvgl headers to be defined in a certain
way. Callbacks that are declared according to the convention would allow the binding to register a MicroPython object
Therefore we defined a **callback convention** for the LVGL C API that expects LVGL headers to be defined in a certain
way. Callbacks that are declared according to this convention allow the binding to register a MicroPython object
next to the function pointer when registering a callback, and access that object when the callback is called.
- The basic idea is that we have ``void * user_data`` field that is used automatically by the MicroPython Binding
@@ -259,8 +268,8 @@ There are a few options for defining a callback in LVGL C API:
- There's a struct that contains a field called ``void * user_data``
- A pointer to that struct is provided as the **first** argument of a callback registration function
- A pointer to that struct is provided as the **first** argument of the callback itself
- A pointer to that struct is provided as the **first** argument of a callback registration function.
- A pointer to that struct is provided as the **first** argument of the callback itself.
- Option 2: ``user_data`` as a function argument
@@ -277,11 +286,11 @@ There are a few options for defining a callback in LVGL C API:
In practice it's also possible to mix these options, for example provide a struct pointer when registering a callback
(option 1) and provide ``user_data`` argument when calling the callback (options 2),
**as long as the same ``user_data`` that was registered is passed to the callback when it's called**.
**as long as the same** ``user_data`` **that was registered is passed to the callback when it's called**.
Examples
^^^^^^^^
~~~~~~~~
- :cpp:type:`lv_anim_t` contains ``user_data`` field. :cpp:func:`lv_anim_set_path_cb` registers `path_cb` callback.
Both ``lv_anim_set_path_cb`` and :cpp:type:`lv_anim_path_cb_t` receive :cpp:type:`lv_anim_t` as their first argument
@@ -293,12 +302,12 @@ Examples
.. _more-information-1:
More Information
^^^^^^^^^^^^^^^^
Further Reading on Callbacks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- In the `Blog <https://blog.lvgl.io/2019-08-05/micropython-pure-display-driver#using-callbacks>`__
and in the `README <https://github.com/lvgl/lv_binding_micropython#callbacks>`__
- `[v6.0] Callback conventions #1036 <https://github.com/lvgl/lvgl/issues/1036>`__
- Various discussions: `here <https://github.com/lvgl/lvgl/pull/3294#issuecomment-1184895335>`__
and `here <https://github.com/lvgl/lvgl/issues/1763#issuecomment-762247629>`__
and`here <https://github.com/lvgl/lvgl/issues/316#issuecomment-467221587>`__
and `here <https://github.com/lvgl/lvgl/issues/316#issuecomment-467221587>`__

57
docs/details/integration/bindings/pikascript.rst
View File

@@ -1,19 +1,21 @@
==========
PikaScript
==========
What is PikaScript ?
--------------------
What is PikaScript?
*******************
`PikaScript <https://github.com/pikasTech/pikascript>`__ is a Python interpreter designed specifically for
microcontrollers, and it supports a subset of the common Python3 syntax.
It's lighter, requiring only 32k of code space and 4k of RAM, which means it can run on stm32f103c8 (blue-pill)
or even stm32g030c8, on the other hand, you can leave valuable space for more material or larger buffer areas.
It's lighter than MicroPython, requiring only 32k of code space and 4k of RAM, which
means it can run on stm32f103c8 (blue-pill) or even stm32g030c8. On the other hand,
you can leave valuable space for more material or larger buffer areas.
It is simpler, out of the box, runs with no porting and configuration at all, does not depend on OS or file
system, has good support for popular IDEs for Windows platforms like Keil, IAR, RT-Thread-Studio, and of course,
supports linux-gcc development platforms.
supports Linux gcc development platforms.
It's smarter, with a unique C module mechanism that allows you to generate bindings automatically by simply
writing the API for the C module in Python, and you don't need to deal with the headache of writing any macros
@@ -24,23 +26,24 @@ of your arguments .
--------------
Why PikaScript + LVGL ?
-----------------------
Why PikaScript + LVGL?
**********************
- PikaScript now supports the main features of LVGL8, and these APIs are fully compatible with MicroPython!
This means that you can continue to use already written code from MicroPython, and then use less code space and RAM.
- Enjoy detailed code hints down to the parameter type for a better programming experience
- Use a more convenient IDE, such as vs-based simulation projects
- PikaScript now supports the main features of LVGL8, and these APIs are fully compatible with MicroPython.
This means that you can continue to use already written code from MicroPython, but use less code space and RAM.
- Enjoy detailed code hints down to the parameter type for a better programming experience.
- Use a more convenient IDE, such as Visual-Studio-based simulation projects.
So how does it look like?
-------------------------
What Does It Look Like?
***********************
Here are some examples of lvgl that PikaScript can already run, they are mainly from the lvgl documentation examples
Here are some examples of using LVGL that PikaScript can already run. They are mainly
from the LVGL documentation examples.
LV_ARC
~~~~~~
------
.. code-block:: python
@@ -57,7 +60,7 @@ LV_ARC
LV_BAR
~~~~~~
------
.. code-block:: python
@@ -73,7 +76,7 @@ LV_BAR
LV_BTN
~~~~~~
------
.. code-block:: python
@@ -103,7 +106,7 @@ LV_BTN
LV_CHECKBOX
~~~~~~~~~~~
-----------
.. code-block:: python
@@ -132,12 +135,12 @@ LV_CHECKBOX
--------------
How does it work?
-----------------
How Does It Work?
*****************
PikaScript has a unique C module smart binding tool
PikaScript has a unique C module smart binding tool.
Just write the Python interface in pika_lvgl.pyi (.pyi is the python interface file)
Just write the Python interface in pika_lvgl.pyi (.pyi is a Python interface file)
.. code-block:: python
@@ -169,7 +172,7 @@ in the module_class_method format, without any additional work, and all binding
To use the module, just ``import pika_lvgl`` and the precompiler will automatically scan main.py and bind the
``pika_lvgl`` module
``pika_lvgl`` module.
.. code-block:: shell
@@ -183,7 +186,7 @@ To use the module, just ``import pika_lvgl`` and the precompiler will automatica
binding pika_lvgl.pyi...
The precompiler is written in Rust, runs on windows and linux, and is completely open source.
The precompiler is written in Rust, runs on Windows and Linux, and is completely open source.
In addition to binding C modules, the precompiler compiles Python scripts to bytecode in the PC, reducing the
size of the script and increasing its speed.
@@ -192,7 +195,7 @@ size of the script and increasing its speed.
--------------
How can I use it?
-----------------
How Can I Use It?
*****************
The simulation repo on vs is available on https://github.com/pikasTech/lv_pikascript
The simulation repository for Visual Studio is available at https://github.com/pikasTech/lv_pikascript .