feat(docs): migrate from .md to .rst (#4129)
This commit is contained in:
Kevin Schlosser
@@ -1,4 +1,5 @@
|
||||
# Cpp
|
||||
===
|
||||
Cpp
|
||||
===
|
||||
|
||||
In progress: https://github.com/lvgl/lv_binding_cpp
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Bindings
|
||||
========
|
||||
Bindings
|
||||
========
|
||||
|
||||
|
||||
```eval_rst
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
@@ -10,5 +10,3 @@
|
||||
cpp
|
||||
pikascript
|
||||
javascript
|
||||
```
|
||||
|
||||
@@ -1,113 +0,0 @@
|
||||
# JavaScript
|
||||
|
||||
With [lv_binding_js](https://github.com/lvgl/lv_binding_js) you can write lvgl with JavaScript.
|
||||
|
||||
It uses React's virtual DOM concept to manipulate lvgl UI components, providing a familiar React-like experience to users.
|
||||
|
||||
**Code**
|
||||
|
||||
<img src="../../_static/img/js_code.png">
|
||||
|
||||
|
||||
**Code Runing on Real Device**
|
||||
|
||||
<img src="../../_static/img/js_on_device.jpg" style="transform: rotate(270deg); max-width: 400px; padding-left: 100px;">
|
||||
|
||||
## 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 suport lvgl flex and grid style
|
||||
- support most lvgl style，just write like html5 css
|
||||
- support dynamic load image
|
||||
- Fully support lvgl animation
|
||||
|
||||
## 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-simualtor.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)
|
||||
- [Button](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Button.md)
|
||||
- [Text](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Text.md)
|
||||
- [Input](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Input.md)
|
||||
- [Textarea](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Textarea.md)
|
||||
- [Switch](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Switch.md)
|
||||
- [Checkbox](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Checkbox.md)
|
||||
- [Dropdownlist](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Dropdownlist.md)
|
||||
- [ProgressBar](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/ProgressBar.md)
|
||||
- [Line](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Line.md)
|
||||
- [Roller](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Roller.md)
|
||||
- [Keyboard](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Keyboard.md)
|
||||
- [Calendar](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Calendar.md)
|
||||
- [Chart](https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Chart.md)
|
||||
|
||||
## Font
|
||||
|
||||
[Buitin-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
|
||||
|
||||
- [position-size-layout](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/position-size-layout.md)
|
||||
- [boxing-model](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/boxing-model.md)
|
||||
- [color](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/color.md)
|
||||
- [flex](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/flex.md)
|
||||
- [grid](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/grid.md)
|
||||
- [font](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/font.md)
|
||||
- [opacity](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/opacity.md)
|
||||
- [display](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/display.md)
|
||||
- [background](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/background.md)
|
||||
- [scroll](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/scroll.md)
|
||||
- [shadow](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/shadow.md)
|
||||
- [recolor](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/recolor.md)
|
||||
- [line](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/line.md)
|
||||
- [transition](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/transition.md)
|
||||
- [transform](https://github.com/lvgl/lv_binding_js/blob/master/doc/style/transform.md)
|
||||
|
||||
## 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)
|
||||
- [dimension](https://github.com/lvgl/lv_binding_js/blob/master/doc/jsapi/dimension.md)
|
||||
|
||||
## Thanks
|
||||
|
||||
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
|
||||
[libuv](https://github.com/libuv/libuv): platform abstraction layer
|
||||
[curl](https://github.com/curl/curl): HTTP client
|
||||
[txiki.js](https://github.com/saghul/txiki.js): Tiny JavaScript runtime
|
||||
133
docs/get-started/bindings/javascript.rst
Normal file
133
docs/get-started/bindings/javascript.rst
Normal file
@@ -0,0 +1,133 @@
|
||||
==========
|
||||
JavaScript
|
||||
==========
|
||||
|
||||
With `lv_binding_js <https://github.com/lvgl/lv_binding_js>`__ you can
|
||||
write lvgl with JavaScript.
|
||||
|
||||
It uses React’s virtual DOM concept to manipulate lvgl UI components,
|
||||
providing a familiar React-like experience to users.
|
||||
|
||||
**Code**
|
||||
|
||||
**Code Runing 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 suport lvgl flex and grid style
|
||||
- support most lvgl style，just write like html5 css
|
||||
- support dynamic load image
|
||||
- Fully support lvgl animation
|
||||
|
||||
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-simualtor.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>`__
|
||||
- `Button <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Button.md>`__
|
||||
- `Text <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Text.md>`__
|
||||
- `Input <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Input.md>`__
|
||||
- `Textarea <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Textarea.md>`__
|
||||
- `Switch <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Switch.md>`__
|
||||
- `Checkbox <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Checkbox.md>`__
|
||||
- `Dropdownlist <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Dropdownlist.md>`__
|
||||
- `ProgressBar <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/ProgressBar.md>`__
|
||||
- `Line <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Line.md>`__
|
||||
- `Roller <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Roller.md>`__
|
||||
- `Keyboard <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Keyboard.md>`__
|
||||
- `Calendar <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Calendar.md>`__
|
||||
- `Chart <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Chart.md>`__
|
||||
|
||||
Font
|
||||
----
|
||||
|
||||
`Buitin-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
|
||||
|
||||
- `position-size-layout <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/position-size-layout.md>`__
|
||||
- `boxing-model <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/boxing-model.md>`__
|
||||
- `color <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/color.md>`__
|
||||
- `flex <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/flex.md>`__
|
||||
- `grid <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/grid.md>`__
|
||||
- `font <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/font.md>`__
|
||||
- `opacity <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/opacity.md>`__
|
||||
- `display <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/display.md>`__
|
||||
- `background <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/background.md>`__
|
||||
- `scroll <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/scroll.md>`__
|
||||
- `shadow <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/shadow.md>`__
|
||||
- `recolor <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/recolor.md>`__
|
||||
- `line <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/line.md>`__
|
||||
- `transition <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/transition.md>`__
|
||||
- `transform <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/transform.md>`__
|
||||
|
||||
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>`__
|
||||
- `dimension <https://github.com/lvgl/lv_binding_js/blob/master/doc/jsapi/dimension.md>`__
|
||||
|
||||
Thanks
|
||||
------
|
||||
|
||||
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 `libuv <https://github.com/libuv/libuv>`__: platform
|
||||
abstraction layer `curl <https://github.com/curl/curl>`__: HTTP client
|
||||
`txiki.js <https://github.com/saghul/txiki.js>`__: Tiny JavaScript
|
||||
runtime
|
||||
@@ -1,193 +0,0 @@
|
||||
# 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.
|
||||
|
||||
### 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: [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.)
|
||||
|
||||
---
|
||||
|
||||
## 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. 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 **`Change code` > `Build` > `Flash` > `Run`**.
|
||||
In Micropython it's just **`Change code` > `Run`** ! You can even run commands interactively using the [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) (the interactive prompt)
|
||||
|
||||
### 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 objects, 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.
|
||||
- Creating tools to work with LVGL at a higher level (e.g. drag-and-drop designer).
|
||||
|
||||
---
|
||||
|
||||
## So what does it look like?
|
||||
|
||||
**TL;DR:** It's very much like the C API, but Object-Oriented for LVGL components.
|
||||
|
||||
Let's dive right into an example!
|
||||
|
||||
### A simple example
|
||||
|
||||
```python
|
||||
import lvgl as lv
|
||||
lv.init()
|
||||
scr = lv.obj()
|
||||
btn = lv.btn(scr)
|
||||
btn.align(lv.ALIGN.CENTER, 0, 0)
|
||||
label = lv.label(btn)
|
||||
label.set_text('Hello World!')
|
||||
lv.scr_load(scr)
|
||||
```
|
||||
|
||||
## 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 edit a python script and run it.
|
||||
|
||||
[Click here to experiment on the online simulator](https://sim.lvgl.io/)
|
||||
|
||||
Many [LVGL examples](https://docs.lvgl.io/master/examples.html) are available also for Micropython.
|
||||
Just click the
|
||||
<img src="https://user-images.githubusercontent.com/11742638/198729010-35a12e49-4945-414a-8c3e-d32bc95da940.png" align=middle /> link!
|
||||
|
||||
### 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.)
|
||||
|
||||
[Click here to know more information 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.
|
||||
|
||||
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:
|
||||
- Display drivers:
|
||||
- SDL on Linux
|
||||
- ESP32 specific: ILI9341, ILI9488, GC9A01, ST7789, ST7735
|
||||
- Generic (pure Python): ILI9341, ST7789, ST7735
|
||||
- Input drivers:
|
||||
- SDL, XPT2046, FT6X36, ESP32 ADC with resistive touch
|
||||
|
||||
## 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)
|
||||
- The [LVGL micropython forum](https://forum.lvgl.io/c/micropython) (Feel free to ask anything!)
|
||||
- At Micropython: [docs](http://docs.micropython.org/en/latest/) and [forum](https://forum.micropython.org/)
|
||||
- [Blog Post](https://blog.lvgl.io/2019-02-20/micropython-bindings), a little outdated.
|
||||
|
||||
## 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) which is itself a submodule of [lv_micropython](https://github.com/lvgl/lv_micropython)).
|
||||
When building lv_micropython, the public LVGL C API is scanned and Micropython API is auto-generated. That means that lv_micropython provides LVGL API for **any** LVGL version, and generally does not require code changes as LVGL evolves.
|
||||
|
||||
### LVGL C API Coding Conventions
|
||||
|
||||
To support the auto-generation of the Python API, the LVGL C API must follow some coding conventions:
|
||||
|
||||
- Use `enum`s instead of macros. If inevitable to use `define`s export them with `LV_EXPORT_CONST_INT(defined_value)` right after the `define`.
|
||||
- In function arguments use `type name[]` declaration for array parameters instead of `type * name`
|
||||
- Use typed pointers instead of `void *` pointers
|
||||
- Widget constructor must follow the `lv_<widget_name>_create(lv_obj_t * parent)` pattern.
|
||||
- Widget members function must start with `lv_<modul_name>` and should receive `lv_obj_t *` as first argument which is a pointer to widget object itself.
|
||||
- `struct` APIs should follow the widgets' conventions. That is to receive a pointer to the `struct` as the first argument, and the prefix of the `struct` name should be used as the prefix of the function name too (e.g. `lv_disp_set_default(lv_disp_t * disp)`)
|
||||
- Functions and `struct`s which are not part of the public API must begin with underscore in order to mark them as "private".
|
||||
- Argument must be named in H files too.
|
||||
- Do not `malloc` into a static or global variables. Instead declare the variable in `LV_ITERATE_ROOTS` list in `lv_gc.h` and mark the variable with `GC_ROOT(variable)` when it's used.
|
||||
**See [Memory Management](#memory-management)**
|
||||
- To register and use callbacks one of the followings needs to be followed. **See [Callbacks](#callbacks)**
|
||||
- Pass a pointer to a `struct` as the first argument of both the registration function and the callback. That `struct` must contain `void * user_data` field.
|
||||
- The last argument of the registration function must be `void * user_data` and the same `user_data` needs to be passed as the last argument of the callback.
|
||||
|
||||
Most of these rules are simple and straightforward but there are two related concepts that worth a deeper look: **Memory Management** and **Callbacks**.
|
||||
|
||||
### Memory Management
|
||||
|
||||
When LVGL runs in Micropython, all dynamic memory allocations (`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):
|
||||
- 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
|
||||
|
||||
#### Identify The Problem
|
||||
|
||||
Problem happens when an allocated memory's pointer (return value of `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
|
||||
|
||||
- Replace the global/static local var with `LV_GC_ROOT(_var)`
|
||||
- Include `lv_gc.h` on files that use `LV_GC_ROOT`
|
||||
- Add `_var` to `LV_ITERATE_ROOTS` on `lv_gc.h`
|
||||
|
||||
#### Example
|
||||
|
||||
https://github.com/lvgl/lvgl/commit/adced46eccfa0437f84aa51aedca4895cc3c679c
|
||||
|
||||
#### More Information
|
||||
|
||||
- [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)
|
||||
|
||||
### 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 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 to save the *Micropython callable object* for a callback. This field must be provided when registering the function pointer, and provided to the callback function itself.
|
||||
Although called "user_data", the user is not expectd to read/write that field. Instead, the Micropython glue code uses `user_data` to automatically keep track of the Micropython callable object. The glue code updates it when the callback is registered, and uses it when the callback is called in order to invoke a call to the original callable object.
|
||||
|
||||
There are a few options for defining a callback in LVGL C API:
|
||||
- Option 1: `user_data` in a struct
|
||||
- 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
|
||||
- Option 2: `user_data` as a function argument
|
||||
- A parameter called `void * user_data` is provided to the registration function as the **last** argument
|
||||
- The callback itself recieves `void *` as the **last** argument
|
||||
- Option 3: both callback and `user_data` are struct fields
|
||||
- The API exposes a struct with both function pointer member and `user_data` member
|
||||
- The function pointer member receives the same struct as its **first** argument
|
||||
|
||||
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**.
|
||||
|
||||
#### Examples
|
||||
|
||||
- [lv_anim_t](https://github.com/lvgl/lvgl/blob/5d50fbc066938d1a4eb43a8366cf83fbd4ce29f2/src/misc/lv_anim.h#L73-L100) contains `user_data` field.
|
||||
[lv_anim_set_path_cb](https://github.com/lvgl/lvgl/blob/5d50fbc066938d1a4eb43a8366cf83fbd4ce29f2/src/misc/lv_anim.h#L197) registers `path_cb` callback. Both `lv_anim_set_path_cb` and [`lv_anim_path_cb_t`](https://github.com/lvgl/lvgl/blob/5d50fbc066938d1a4eb43a8366cf83fbd4ce29f2/src/misc/lv_anim.h#L46) recieve `lv_anim_t` as their first argument
|
||||
- [`path_cb` field](https://github.com/lvgl/lvgl/blob/5d50fbc066938d1a4eb43a8366cf83fbd4ce29f2/src/misc/lv_anim.h#L83) can also be assigned directly in the Python code because it's a member of `lv_anim_t` which contains `user_data` field, and [`lv_anim_path_cb_t`](https://github.com/lvgl/lvgl/blob/5d50fbc066938d1a4eb43a8366cf83fbd4ce29f2/src/misc/lv_anim.h#L46) recieve `lv_anim_t` as its first argument.
|
||||
- [`lv_imgfont_create`](https://github.com/lvgl/lvgl/blob/5d50fbc066938d1a4eb43a8366cf83fbd4ce29f2/src/others/imgfont/lv_imgfont.h#L43) registers `path_cb` and recieves `user_data` as the last argument. The callback [`lv_imgfont_get_path_cb_t`](https://github.com/lvgl/lvgl/blob/5d50fbc066938d1a4eb43a8366cf83fbd4ce29f2/src/others/imgfont/lv_imgfont.h#L29-L31) also receieves the `user_data` as the last argument.
|
||||
|
||||
#### More Information
|
||||
|
||||
- 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)
|
||||
316
docs/get-started/bindings/micropython.rst
Normal file
316
docs/get-started/bindings/micropython.rst
Normal file
@@ -0,0 +1,316 @@
|
||||
.. _micropython:
|
||||
|
||||
===========
|
||||
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.
|
||||
|
||||
|
||||
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:
|
||||
|
||||
- `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.)
|
||||
|
||||
--------------
|
||||
|
||||
|
||||
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.
|
||||
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
|
||||
**``Change code`` > ``Build`` > ``Flash`` > ``Run``**. In Micropython it's just
|
||||
**``Change code`` > ``Run``** ! You can even run commands interactively using the
|
||||
`REPL <https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop>`__ (the interactive prompt)
|
||||
|
||||
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 objects, 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.
|
||||
- Creating tools to work with LVGL at a higher level (e.g. drag-and-drop designer).
|
||||
|
||||
--------------
|
||||
|
||||
|
||||
So what does it look like?
|
||||
--------------------------
|
||||
|
||||
It's very much like the C API, but Object-Oriented for LVGL components.
|
||||
|
||||
Let's dive right into an example!
|
||||
|
||||
|
||||
A simple example
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code:: python
|
||||
|
||||
import lvgl as lv
|
||||
lv.init()
|
||||
scr = lv.obj()
|
||||
btn = lv.btn(scr)
|
||||
btn.align(lv.ALIGN.CENTER, 0, 0)
|
||||
label = lv.label(btn)
|
||||
label.set_text('Hello World!')
|
||||
lv.scr_load(scr)
|
||||
|
||||
|
||||
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
|
||||
edit a python script and run it.
|
||||
|
||||
`Click here to experiment on the online simulator <https://sim.lvgl.io/>`__
|
||||
|
||||
Many `LVGL examples <https://docs.lvgl.io/master/examples.html>`__ are available also for Micropython. Just click the link!
|
||||
|
||||
|
||||
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.)
|
||||
|
||||
`Click here to know more information 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.
|
||||
|
||||
- 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:
|
||||
|
||||
- Display drivers:
|
||||
|
||||
- SDL on Linux
|
||||
- ESP32 specific:
|
||||
|
||||
- ILI9341
|
||||
- ILI9488
|
||||
- GC9A01
|
||||
- ST7789
|
||||
- ST7735
|
||||
|
||||
- Generic (pure Python):
|
||||
|
||||
- ILI9341
|
||||
- ST7789
|
||||
- ST7735
|
||||
|
||||
- Input drivers:
|
||||
|
||||
- SDL
|
||||
- XPT2046
|
||||
- FT6X36
|
||||
- ESP32 ADC with resistive touch
|
||||
|
||||
|
||||
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>`__
|
||||
- The `LVGL micropython forum <https://forum.lvgl.io/c/micropython>`__ (Feel free to ask anything!)
|
||||
- At Micropython: `docs <http://docs.micropython.org/en/latest/>`__ and `forum <https://forum.micropython.org/>`__
|
||||
- `Blog Post <https://blog.lvgl.io/2019-02-20/micropython-bindings>`__, a little outdated.
|
||||
|
||||
|
||||
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>`__
|
||||
which is itself a submodule of `lv_micropython <https://github.com/lvgl/lv_micropython>`__).
|
||||
- When building lv_micropython, the public LVGL C API is scanned and Micropython API is auto-generated. That means that
|
||||
lv_micropython provides LVGL API for **any** LVGL version, and generally does not require code changes as LVGL evolves.
|
||||
|
||||
|
||||
LVGL C API Coding Conventions
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To support the auto-generation of the Python API, the LVGL C API must
|
||||
follow some coding conventions:
|
||||
|
||||
- Use ``enum``\ s instead of macros. If inevitable to use ``define``\ s
|
||||
export them with :cpp:expr:`LV_EXPORT_CONST_INT(defined_value)` right after the ``define``.
|
||||
- In function arguments use ``type name[]`` declaration for array parameters instead of :cpp:expr:`type * name`
|
||||
- Use typed pointers instead of :cpp:expr:`void *` pointers
|
||||
- Widget constructor must follow the ``lv_<widget_name>_create(lv_obj_t * parent)`` pattern.
|
||||
- Widget members function must start with ``lv_<modul_name>`` and should receive :cpp:expr:`lv_obj_t *` as first
|
||||
argument which is a pointer to widget object itself.
|
||||
- ``struct`` APIs should follow the widgets' conventions. That is to receive a pointer to the ``struct`` as the
|
||||
first argument, and the prefix of the ``struct`` name should be used as the prefix of the
|
||||
function name too (e.g. :cpp:expr:`lv_disp_set_default(lv_disp_t * disp)`)
|
||||
- Functions and ``struct``\ s which are not part of the public API must begin with underscore in order to mark them as “private”.
|
||||
- Argument must be named in H files too.
|
||||
- Do not ``malloc`` into a static or global variables. Instead declare the variable in :c:macro:`LV_ITERATE_ROOTS`
|
||||
list in ``lv_gc.h`` and mark the variable with :cpp:expr:`GC_ROOT(variable)` when it's used. **See** :ref:`memory_management`
|
||||
- To register and use callbacks one of the followings needs to be followed. **See** :ref:`callbacks`
|
||||
|
||||
- Pass a pointer to a ``struct`` as the first argument of both the registration function and the callback. That
|
||||
``struct`` must contain ``void * user_data`` field.
|
||||
- The last argument of the registration function must be ``void * user_data`` and the same ``user_data``
|
||||
needs to be passed as the last argument of the callback.
|
||||
|
||||
Most of these rules are simple and straightforward but there are two related concepts that worth a deeper look:
|
||||
:ref:`memory_management` and :ref:`callbacks`.
|
||||
|
||||
.. _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>`__:
|
||||
|
||||
- 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
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Solve The Problem
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
- Replace the global/static local var with :cpp:expr:`LV_GC_ROOT(_var)`
|
||||
- Include ``lv_gc.h`` on files that use :c:macro:`LV_GC_ROOT`
|
||||
- Add ``_var`` to :c:macro:`LV_ITERATE_ROOTS` on ``lv_gc.h``
|
||||
|
||||
Example
|
||||
^^^^^^^
|
||||
|
||||
https://github.com/lvgl/lvgl/commit/adced46eccfa0437f84aa51aedca4895cc3c679c
|
||||
|
||||
|
||||
More Information
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
- `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>`__
|
||||
|
||||
.. _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
|
||||
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
|
||||
to save the *Micropython callable object* for a callback. This field must be provided when registering the function
|
||||
pointer, and provided to the callback function itself.
|
||||
- Although called "user_data", the user is not expectd to read/write that field. Instead, the Micropython glue code uses
|
||||
``user_data`` to automatically keep track of the Micropython callable object. The glue code updates it when the callback
|
||||
is registered, and uses it when the callback is called in order to invoke a call to the original callable object.
|
||||
|
||||
There are a few options for defining a callback in LVGL C API:
|
||||
|
||||
- Option 1: ``user_data`` in a struct
|
||||
|
||||
- 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
|
||||
|
||||
- Option 2: ``user_data`` as a function argument
|
||||
|
||||
- A parameter called ``void * user_data`` is provided to the registration function as the **last** argument
|
||||
|
||||
- The callback itself recieves ``void *`` as the **last** argument
|
||||
|
||||
- Option 3: both callback and ``user_data`` are struct fields
|
||||
|
||||
- The API exposes a struct with both function pointer member and ``user_data`` member
|
||||
|
||||
- The function pointer member receives the same struct as its **first** argument
|
||||
|
||||
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**.
|
||||
|
||||
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`
|
||||
recieve :cpp:type:`lv_anim_t` as their first argument
|
||||
- ``path_cb`` field can also be assigned directly in the Python code because it's a member
|
||||
of :cpp:type:`lv_anim_t` which contains ``user_data`` field, and :cpp:type:`lv_anim_path_cb_t`
|
||||
recieve :cpp:type:`lv_anim_t` as its first argument.
|
||||
- :cpp:func:`lv_imgfont_create` registers ``path_cb`` and recieves ``user_data`` as the last
|
||||
argument. The callback :cpp:func:`lv_imgfont_get_path_cb_t` also receieves the ``user_data`` as the last argument.
|
||||
|
||||
.. _more-information-1:
|
||||
|
||||
More Information
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
- 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>`__
|
||||
@@ -1,162 +0,0 @@
|
||||
# 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 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.
|
||||
|
||||
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 or global tables manually. On the other hand, all C modules have sophisticated smart hints, even hinting at the types of your arguments .
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
## So how does it look like?
|
||||
|
||||
Here are some examples of lvgl that PikaScript can already run, they are mainly from the lvgl documentation examples
|
||||
|
||||
### LV_ARC
|
||||
|
||||
```python
|
||||
import pika_lvgl as lv
|
||||
import PikaStdLib
|
||||
mem = PikaStdLib.MemChecker()
|
||||
# Create an Arc
|
||||
arc = lv.arc(lv.scr_act())
|
||||
arc.set_end_angle(200)
|
||||
arc.set_size(150, 150)
|
||||
arc.center()
|
||||
print('mem used max: %0.2f kB' % (mem.getMax()))
|
||||
print('mem used now: %0.2f kB' % (mem.getNow()))
|
||||
```
|
||||
|
||||
### LV_BAR
|
||||
|
||||
``` python
|
||||
import pika_lvgl as lv
|
||||
import PikaStdLib
|
||||
mem = PikaStdLib.MemChecker()
|
||||
bar1 = lv.bar(lv.scr_act())
|
||||
bar1.set_size(200, 20)
|
||||
bar1.center()
|
||||
bar1.set_value(70, lv.ANIM.OFF)
|
||||
print('mem used max: %0.2f kB' % (mem.getMax()))
|
||||
print('mem used now: %0.2f kB' % (mem.getNow()))
|
||||
```
|
||||
|
||||
### LV_BTN
|
||||
|
||||
``` python
|
||||
import pika_lvgl as lv
|
||||
import PikaStdLib
|
||||
mem = PikaStdLib.MemChecker()
|
||||
def event_cb_1(evt):
|
||||
print('in evt1')
|
||||
print('mem used now: %0.2f kB' % (mem.getNow()))
|
||||
def event_cb_2(evt):
|
||||
print('in evt2')
|
||||
print('mem used now: %0.2f kB' % (mem.getNow()))
|
||||
btn1 = lv.btn(lv.scr_act())
|
||||
btn1.align(lv.ALIGN.TOP_MID, 0, 10)
|
||||
btn2 = lv.btn(lv.scr_act())
|
||||
btn2.align(lv.ALIGN.TOP_MID, 0, 50)
|
||||
btn1.add_event(event_cb_1, lv.EVENT.CLICKED, 0)
|
||||
btn2.add_event(event_cb_2, lv.EVENT.CLICKED, 0)
|
||||
print('mem used max: %0.2f kB' % (mem.getMax()))
|
||||
print('mem used now: %0.2f kB' % (mem.getNow()))
|
||||
```
|
||||
|
||||
### LV_CHECKBOX
|
||||
|
||||
``` python
|
||||
import pika_lvgl as lv
|
||||
import PikaStdLib
|
||||
mem = PikaStdLib.MemChecker()
|
||||
cb = lv.checkbox(lv.scr_act())
|
||||
cb.set_text("Apple")
|
||||
cb.align(lv.ALIGN.TOP_LEFT, 0 ,0)
|
||||
cb = lv.checkbox(lv.scr_act())
|
||||
cb.set_text("Banana")
|
||||
cb.add_state(lv.STATE.CHECKED)
|
||||
cb.align(lv.ALIGN.TOP_LEFT, 0 ,30)
|
||||
cb = lv.checkbox(lv.scr_act())
|
||||
cb.set_text("Lemon")
|
||||
cb.add_state(lv.STATE.DISABLED)
|
||||
cb.align(lv.ALIGN.TOP_LEFT, 0 ,60)
|
||||
cb = lv.checkbox(lv.scr_act())
|
||||
cb.add_state(lv.STATE.CHECKED | lv.STATE.DISABLED)
|
||||
cb.set_text("Melon")
|
||||
cb.align(lv.ALIGN.TOP_LEFT, 0 ,90)
|
||||
print('mem used max: %0.2f kB' % (mem.getMax()))
|
||||
print('mem used now: %0.2f kB' % (mem.getNow()))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How does it work?
|
||||
|
||||
PikaScript has a unique C module smart binding tool
|
||||
|
||||
Just write the Python interface in pika_lvgl.pyi (.pyi is the python interface file)
|
||||
|
||||
``` python
|
||||
# pika_lvgl.pyi
|
||||
class arc(lv_obj):
|
||||
def set_end_angle(self, angle: int): ...
|
||||
def set_bg_angles(self, start: int, end: int): ...
|
||||
def set_angles(self, start: int, end: int): ...
|
||||
```
|
||||
|
||||
Then PikaScript's pre-compiler can automatically bind the following C functions, simply by naming the functions in the module_class_method format, without any additional work, and all binding and registration is done automatically.
|
||||
|
||||
``` C
|
||||
/* pika_lvgl_arc.c */
|
||||
void pika_lvgl_arc_set_end_angle(PikaObj* self, int angle) {
|
||||
lv_obj_t* lv_obj = obj_getPtr(self, "lv_obj");
|
||||
lv_arc_set_end_angle(lv_obj, angle);
|
||||
}
|
||||
void pika_lvgl_arc_set_bg_angles(PikaObj *self, int start, int end){
|
||||
lv_obj_t* lv_obj = obj_getPtr(self, "lv_obj");
|
||||
lv_arc_set_bg_angles(lv_obj, start, end);
|
||||
}
|
||||
void pika_lvgl_arc_set_angles(PikaObj *self, int start, int end){
|
||||
lv_obj_t* lv_obj = obj_getPtr(self, "lv_obj");
|
||||
lv_arc_set_angles(lv_obj, start, end);
|
||||
}
|
||||
```
|
||||
|
||||
To use the module, just `import pika_lvgl` and the precompiler will automatically scan main.py and bind the `pika_lvgl` module
|
||||
|
||||
```
|
||||
$ ./rust-msc-latest-win10.exe
|
||||
(pikascript) packages installed:
|
||||
pikascript-core==v1.10.0
|
||||
PikaStdLib==v1.10.0
|
||||
PikaStdDevice==v1.10.0
|
||||
(pikascript) pika compiler:
|
||||
scaning main.py...
|
||||
binding pika_lvgl.pyi...
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## How can I use it?
|
||||
|
||||
The simulation repo on vs is available on https://github.com/pikasTech/lv_pikascript
|
||||
|
||||
---
|
||||
203
docs/get-started/bindings/pikascript.rst
Normal file
203
docs/get-started/bindings/pikascript.rst
Normal file
@@ -0,0 +1,203 @@
|
||||
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 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.
|
||||
|
||||
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 or global tables manually. On the other hand, all C
|
||||
modules have sophisticated smart hints, even hinting at the types of
|
||||
your arguments .
|
||||
|
||||
--------------
|
||||
|
||||
|
||||
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
|
||||
|
||||
|
||||
So how does it look like?
|
||||
-------------------------
|
||||
|
||||
Here are some examples of lvgl that PikaScript can already run, they are
|
||||
mainly from the lvgl documentation examples
|
||||
|
||||
|
||||
LV_ARC
|
||||
~~~~~~
|
||||
|
||||
.. code:: python
|
||||
|
||||
import pika_lvgl as lv
|
||||
import PikaStdLib
|
||||
mem = PikaStdLib.MemChecker()
|
||||
# Create an Arc
|
||||
arc = lv.arc(lv.scr_act())
|
||||
arc.set_end_angle(200)
|
||||
arc.set_size(150, 150)
|
||||
arc.center()
|
||||
print('mem used max: %0.2f kB' % (mem.getMax()))
|
||||
print('mem used now: %0.2f kB' % (mem.getNow()))
|
||||
|
||||
|
||||
LV_BAR
|
||||
~~~~~~
|
||||
|
||||
.. code:: python
|
||||
|
||||
import pika_lvgl as lv
|
||||
import PikaStdLib
|
||||
mem = PikaStdLib.MemChecker()
|
||||
bar1 = lv.bar(lv.scr_act())
|
||||
bar1.set_size(200, 20)
|
||||
bar1.center()
|
||||
bar1.set_value(70, lv.ANIM.OFF)
|
||||
print('mem used max: %0.2f kB' % (mem.getMax()))
|
||||
print('mem used now: %0.2f kB' % (mem.getNow()))
|
||||
|
||||
|
||||
LV_BTN
|
||||
~~~~~~
|
||||
|
||||
.. code:: python
|
||||
|
||||
import pika_lvgl as lv
|
||||
import PikaStdLib
|
||||
mem = PikaStdLib.MemChecker()
|
||||
def event_cb_1(evt):
|
||||
print('in evt1')
|
||||
print('mem used now: %0.2f kB' % (mem.getNow()))
|
||||
def event_cb_2(evt):
|
||||
print('in evt2')
|
||||
print('mem used now: %0.2f kB' % (mem.getNow()))
|
||||
btn1 = lv.btn(lv.scr_act())
|
||||
btn1.align(lv.ALIGN.TOP_MID, 0, 10)
|
||||
btn2 = lv.btn(lv.scr_act())
|
||||
btn2.align(lv.ALIGN.TOP_MID, 0, 50)
|
||||
btn1.add_event(event_cb_1, lv.EVENT.CLICKED, 0)
|
||||
btn2.add_event(event_cb_2, lv.EVENT.CLICKED, 0)
|
||||
print('mem used max: %0.2f kB' % (mem.getMax()))
|
||||
print('mem used now: %0.2f kB' % (mem.getNow()))
|
||||
|
||||
|
||||
LV_CHECKBOX
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. code:: python
|
||||
|
||||
import pika_lvgl as lv
|
||||
import PikaStdLib
|
||||
mem = PikaStdLib.MemChecker()
|
||||
cb = lv.checkbox(lv.scr_act())
|
||||
cb.set_text("Apple")
|
||||
cb.align(lv.ALIGN.TOP_LEFT, 0 ,0)
|
||||
cb = lv.checkbox(lv.scr_act())
|
||||
cb.set_text("Banana")
|
||||
cb.add_state(lv.STATE.CHECKED)
|
||||
cb.align(lv.ALIGN.TOP_LEFT, 0 ,30)
|
||||
cb = lv.checkbox(lv.scr_act())
|
||||
cb.set_text("Lemon")
|
||||
cb.add_state(lv.STATE.DISABLED)
|
||||
cb.align(lv.ALIGN.TOP_LEFT, 0 ,60)
|
||||
cb = lv.checkbox(lv.scr_act())
|
||||
cb.add_state(lv.STATE.CHECKED | lv.STATE.DISABLED)
|
||||
cb.set_text("Melon")
|
||||
cb.align(lv.ALIGN.TOP_LEFT, 0 ,90)
|
||||
print('mem used max: %0.2f kB' % (mem.getMax()))
|
||||
print('mem used now: %0.2f kB' % (mem.getNow()))
|
||||
|
||||
--------------
|
||||
|
||||
|
||||
How does it work?
|
||||
-----------------
|
||||
|
||||
PikaScript has a unique C module smart binding tool
|
||||
|
||||
Just write the Python interface in pika_lvgl.pyi (.pyi is the python
|
||||
interface file)
|
||||
|
||||
.. code:: python
|
||||
|
||||
# pika_lvgl.pyi
|
||||
class arc(lv_obj):
|
||||
def set_end_angle(self, angle: int): ...
|
||||
def set_bg_angles(self, start: int, end: int): ...
|
||||
def set_angles(self, start: int, end: int): ...
|
||||
|
||||
Then PikaScript’s pre-compiler can automatically bind the following C
|
||||
functions, simply by naming the functions in the module_class_method
|
||||
format, without any additional work, and all binding and registration is
|
||||
done automatically.
|
||||
|
||||
.. code:: c
|
||||
|
||||
/* pika_lvgl_arc.c */
|
||||
void pika_lvgl_arc_set_end_angle(PikaObj* self, int angle) {
|
||||
lv_obj_t* lv_obj = obj_getPtr(self, "lv_obj");
|
||||
lv_arc_set_end_angle(lv_obj, angle);
|
||||
}
|
||||
void pika_lvgl_arc_set_bg_angles(PikaObj *self, int start, int end){
|
||||
lv_obj_t* lv_obj = obj_getPtr(self, "lv_obj");
|
||||
lv_arc_set_bg_angles(lv_obj, start, end);
|
||||
}
|
||||
void pika_lvgl_arc_set_angles(PikaObj *self, int start, int end){
|
||||
lv_obj_t* lv_obj = obj_getPtr(self, "lv_obj");
|
||||
lv_arc_set_angles(lv_obj, start, end);
|
||||
}
|
||||
|
||||
To use the module, just ``import pika_lvgl`` and the precompiler will
|
||||
automatically scan main.py and bind the ``pika_lvgl`` module
|
||||
|
||||
::
|
||||
|
||||
$ ./rust-msc-latest-win10.exe
|
||||
(pikascript) packages installed:
|
||||
pikascript-core==v1.10.0
|
||||
PikaStdLib==v1.10.0
|
||||
PikaStdDevice==v1.10.0
|
||||
(pikascript) pika compiler:
|
||||
scaning main.py...
|
||||
binding pika_lvgl.pyi...
|
||||
|
||||
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.
|
||||
|
||||
--------------
|
||||
|
||||
How can I use it?
|
||||
-----------------
|
||||
|
||||
The simulation repo on vs is available on
|
||||
https://github.com/pikasTech/lv_pikascript
|
||||
Reference in New Issue
Block a user