search

lvgl / lv_demos

Examples, tutorials and applications for the LVGL embedded GUI library
https://lvgl.io
486 stars 366 forks source link

Rework the examples repo #31

Closed kisvegabor closed 4 years ago

kisvegabor commented 5 years ago

This repo should be reworked to make people easier to get started.

My vision is the following

Simple examples

Add very simple examples. It would be nice to use these examples in the documentation too (add lv_examples as a submodule to docs). I was collecting the recurring questions which could be answered with examples:

Ready to use / easy to modify applications

External libraries

Create a separate repo for examples when external libraries are used:

Blog post

Create blog posts about longer, more complex topics

Tutorials

Tests

Feedback is very welcome

embeddedt commented 5 years ago

All of it sounds good, and I'm happy to help where I can!

FAQ

I think this would be better as part of the documentation rather than a blog post. We could make it one of the first pages so people would easily see it. It's also easier (IMO) to update and add to.

embeddedt commented 5 years ago

I've created the dev-6.1 branch on this repository.

kisvegabor commented 5 years ago

I think this would be better as part of the documentation rather than a blog post. We could make it one of the first pages so people would easily see it. It's also easier (IMO) to update and add to.

Good idea. I'll add it soon.

I've created the dev-6.1 branch on this repository.

As it's not directly related to v6.1 (I'm planning to release it independently) I renamed the branch to rework.

I also updated with the examples from the docs and now the docs use lv_examples as a submodule.

kisvegabor commented 5 years ago

I've updated the Welcome page with the FAQ: https://docs.littlevgl.com/en/html/index.html

embeddedt commented 5 years ago

Another idea: we should have at least one example for really small displays (i.e. 178x128). Currently all of the examples are much too big for those.

kisvegabor commented 5 years ago

@embeddedt Good idea! Or with an even smaller screen like 128x64. Shal it be an example app, or a blog post? If an app then about what?

embeddedt commented 5 years ago

@kisvegabor An example application. Not entirely sure what for yet, but...

I'm thinking that we should design all the newer examples with some way of controlling their size automatically (i.e. have it driven by font size). That way we don't need separate examples for each screen.

I know this is true for container-based apps like lv_test_theme_1 already. But if I recall correctly there are also examples where objects are positioned manually using pixel-based values.

kisvegabor commented 5 years ago

I'm thinking that we should design all the newer examples with some way of controlling their size automatically (i.e. have it driven by font size). That way we don't need separate examples for each screen.

I agree, however, IMO the tiny monochrome displays are too very different from normal TFT display to expect the same behavior and quality. So it can be an exception.

In the apps, I'd like to show how beautiful UIs can be created with LittlevGL. So a UI designer or somebody with some sense to it could help a lot to design the screens.

For example, for the "Audio player", I can imagine something like this: https://dribbble.com/shots/1547422-Music-Player It doesn't even have to work with themes because it can be too specific to use generic themes.

Of course, the "File browser" and the "Wifi connect" can be more simple. They can work with themes too.

embeddedt commented 5 years ago

What folder would you like the new examples put in?

puzrin commented 5 years ago

How about switch everything to PIO (since 4.0 open-sourced all critical parts)? I think, mono-repo concept for examples is nice, but apps should be more "independent".

Now each app folder has only .mk file, and requires additional efforts to use. IMHO, it would be more convenient to open app folder it PIO and run build/upload without need to learn details immedeately.

The same for external libs use - IMO it would be more simple to use those as dependencies via PIO and forget about manual installs, paths and other mess.

I understand, nobody likes to change preferred instruments, and i don't like to push about such things. I'll be ok with any IDE, which can care about dependencies.

embeddedt commented 5 years ago

@puzrin Not everyone can or will use PIO. I don't think depending on PIO will be useful for the majority of users.

Now each app folder has only .mk file, and requires additional efforts to use.

Not necessarily. Eclipse will automatically find all the .c files and compile them. Only the include path needs to be added, which should take ~1-2 minutes.

puzrin commented 5 years ago

I don't think depending on PIO will be useful for the majority of users.

For old users - yes. But this repo seems to be targeted for new users. They don't care, what to install.

Also, nobody prohibits to keep existing .mk files for alternate builds.

Only the include path needs to be added, which should take ~1-2 minutes.

For my point of view, such things are not acceptable for good usability. It's not good to overload user's brain with not necessary technical details, if it's possible.

Let's see https://github.com/littlevgl/lv_examples#add-the-examples-to-your-projects - why should i do all those actions manually instead of just open app folder in IDE?

My suggestion is not about IDE switch, but about making examples more frictionless.

embeddedt commented 5 years ago

@puzrin Examples are supposed to be used in the actual environment you would run your real application in. If somebody wants to use STM32CubeIDE for their real project - why should we make them use PlatformIO?

puzrin commented 5 years ago

@embeddedt seems my explanations were not enougth well. I don't suggest to start battle about best envs, that would be not constructive.

I short - That means adding PIO config to each folder and make sure no hardcoded paths used for #include (for configs and so on).

embeddedt commented 5 years ago

@puzrin It seems that I misunderstood you as well. Sorry about that. I don't see any issues with what you're suggesting.

Do you know whether the PIO config file is in text or binary format?

puzrin commented 5 years ago

Do you know whether the PIO config file is in text or binary format?

Is this what you asked about?

embeddedt commented 5 years ago

Is this what you asked about?

Yes, thanks for those links.

To simplify the discussion let's assume there are just two platforms (native and stm32). Obviously more could be added as necessary.

Would every example's platformio.ini need to contain an [env] statement for both of those platforms, or can there be a shared top-level file for that? It wasn't entirely clear from the documentation (they mention a "base" file but not how to include it).

I'd like to avoid duplication of config files as much as possible.

puzrin commented 5 years ago

Would every example's platformio.ini need to contain an [env] statement for both of those platforms, or can there be a shared top-level file for that? It wasn't entirely clear from the documentation (they mention a "base" file but not how to include it).

I'd like to avoid duplication of config files as much as possible.

I guess, you ask about extra_configs option http://docs.platformio.org/en/latest/projectconf/section_platformio.html#extra-configs.

The only drawback - right now users will have to manually set Use Development PIOcore in extension config, to force use 4.0 beta (3.x does not support this feature).

Also, forgot to mention, it may be useful to add ./vscode config https://github.com/speedcontrols/ac_sc_grinder/tree/master/.vscode. That will force vscode to suggest PIO install after first folder open.

Probably SDL2 binaries & headers for Windows can be distributed as separate PIO package. And for linux, small python script on pre-compile hook can show descriptive recommendation if lib is not instaled.

embeddedt commented 5 years ago

@puzrin Do you want:

puzrin commented 5 years ago

@puzrin Do you want:

  • A separate project for each example, or
  • One project with all examples (users will have to modify main.c to switch between them)

A separate platforio.ini for each example (in each subfolder). This concept is mono-repository - when you have a lot of small projects, independent but need to be in sync.

If you wish to use shared parts of config or shared scripts - that's ok (internal implementation details, not visible for user).

  • One project with all examples (users will have to modify main.c to switch between them)

Usually, as "stupid user" i wish open example and see what happens. If i need to learn something, modify code and so on - that's a pain. IMO concept of "open folder in IDE" is natural and preferable. Manual modification of source files does not look friendly.

kisvegabor commented 5 years ago

Regarding the Platform.Io support: I'm not against to add platforio.ini to examples/apps/external library projects.

Usually, as "stupid user" i wish open example and see what happens. If i need to learn something, modify code and so on - that's a pain. IMO concept of "open folder in IDE" is natural and preferable. Manual modification of source files does not look friendly.

It means every app needs to be a project. I don't how can we effectively support a lot of IDEs this way (Eclipse, Codeblocks, Visual studio, Platform IO, Arduino, ESP IDF, simple Makefile).

I like the idea to add every apps/ext. lib as a separate repo. This way it will be easier to document and overview them. My approach would be to add all the apps/ext. libs repos as submodules to the IDE projects. Instead of adding lv_some_app_conf.h for every app we can enable them in lv_conf.h. By default the apps are disabled but with e.g. LV_USE_ADUIO_PLAYER they can be enabled,

Forcing the user to call audio_player_create() and enable it in lv_conf.h to test the audio player is acceptable in my opinion. In Simulator projects (Eclipse, CodeBlocks, MS Visual studio) all apps can be enabled by default so only audio_player_create() needs to be called. The possible apps/ext. lib. tests can be listed in comments in main.c. IMO it's easy for everyone to see how to use an example.

puzrin commented 5 years ago

It means every app needs to be a project. I don't how can we effectively support a lot of IDEs this way (Eclipse, Codeblocks, Visual studio, Platform IO, Arduino, ESP IDF, simple Makefile).

I think, supporting of multiple IDEs this way would be nice, but not main goal. Nearest goal is to provide "at least one" way to open apps (or example?) without pain.

I like the idea to add every apps/ext. lib as a separate repo.

That may make too much of noise. I'd suggest keep mono repo for small things (like current examples) and separate repos for complex things like "settings menu".

embeddedt commented 5 years ago

Nearest goal is to provide "at least one" way to open apps (or example?) without pain

I think that we need to establish an objective definition of "pain".

puzrin commented 5 years ago

I think that we need to establish an objective definition of "pain".

I'm not sure this can be objective :), but can explain what i mean. I need to care abut multiple different projects, and it's not possible to keep everything in head. Solution is "zero memory" approach - don't remember anything, but make projects such way to minimize context switch. Or, in other words, "even novice should understand everything with zero efforts".

When i inspect samples, i may have 2 needs:

If i had to think every time about how to install & configure things - that's an extra efforts. All extra efforts are "pain" because i need to switch context and think about something else, instead of things i really need.

embeddedt commented 5 years ago

If i had to think every time about how to install & configure things - that's an extra efforts.

It's a one-time installation. Once you have a project set up in your IDE, switching examples is rather effortless.

We can't create an absolute "zero-effort" solution. Personally, I think @kisvegabor's existing method does a pretty good job of simplifying things. I would rather make slight modifications to that than adopt a whole new methodology.

puzrin commented 5 years ago

It's a one-time installation. Once you have a project set up in your IDE, switching examples is rather effortless.

I don't keep project on disk after played with it (anyway, after 1 week i will not remember what happens in that folder). So, i will have to learn installation details every time.

Things like IDE install are done once. But project-specific things like dependencies and paths now should be replayed everytime. Also, instead of single app "all apps + switch" is suggested - i understand this as programmer :), but find it strange as user.

We can't create an absolute "zero-effort" solution.

Sure, even with PIO user still have to install drivers of configure udev rules, to make flashers work. But it still worth to minimize efforts when it's possible. IMO with PIO difference is significant.

embeddedt commented 5 years ago

Also, instead of single app "all apps + switch" is suggested - i understand this as programmer :), but find it strange as user.

LittlevGL is intended for programmers, not users, if you get my meaning :wink: .

I don't keep project on disk after played with it (anyway, after 1 week i will not remember what happens in that folder). So, i will have to learn installation details every time.

That's something specific to your setup - and not LittlevGL as a whole, right?

puzrin commented 5 years ago

LittlevGL is intended for programmers, not users, if you get my meaning.

In this case programmers = users, and you probably mean "real programmers" :smile: . I understand such approach, and used it 20 years ago myself :). But that works only if users have no alternatives, and does not make people happy.

Now we have possibility to reduce user's efforts almost to zero, if they agree to use PIO. And that does not look expensive.

That's something specific to your setup - and not LittlevGL as a whole, right?

Yes, that's not specific to LittlevGL. But that's also not unique of my person - that's "zero-memory" approach. When LittlevGL is your main project, you can remember every detail. But when you switch between a lot of completely different things, you forget details very fast. Edge approach sounds as "forget as much as possible, as soon as possible".

For example, it may sounds strange, but i already don't remember details of font convertor and don't remember i18n at all :). But those are written such way to require minimal efforts to remember.

kisvegabor commented 5 years ago

Nearest goal is to provide "at least one" way to open apps (or example?) without pain.

That one can be the PIO, right? Correct me if I'm wrong but if each apps are in separate repos with a plataformio.ini file you can easily reference them as dependencies in the main PIO project, right? This way we still have the flexibility to easily add and use an app or ext. lib as submodules in Eclipse (like file browser of PNG decoder)

puzrin commented 5 years ago

Let's keep things separate. If you wish independent apps, then storing apps in subfolders or in separate repo is a maintenance question, not related to other things. From my experience, a big number of repos is boring too. It may be convenient to keep small things in mono-repo (as subfolders).

PIO simplifies dependencies management/install and helps to keep repo free of "garbage" (manually copied foreign libs, submodules and other things). Yes, from my point of view, it's possible to open projects via PIO with minimal efforts. I don't know if other IDEs can solve this (could not find).

https://docs.platformio.org/en/latest/ide/eclipse.html - PIO should be available for eclipse too, but i did not tested it. Currently use PIO with VScode.

kisvegabor commented 5 years ago

If you wish independent apps, then storing apps in subfolders or in separate repo is a maintenance question, not related to other things. From my experience, a big number of repos is boring too. It may be convenient to keep small things in mono-repo (as subfolders).

My vision is:

What do you think?

@puzrin The platform.ini in apps will require lvgl so the user can open the e.g. audio player example and will get everything he needs, or the user needs to add the lv_audio_player as a dependency to his "main" platform.io project?

PIO should be available for eclipse too, but i did not tested it. Currently use PIO with VScode.

Personally, I'm happy with the old-fashioned way, it's not a big burden for me to add the files/files. At least it does what I really want. :slightly_smiling_face: I had some painful hours while I was trying Platformio but maybe it came only from my inexperience.

puzrin commented 5 years ago

What do you think?

I would move snippets in rework branch from root level into subfolder. Reasons are the same as in my suggestion about lvgl folders :)

@puzrin The platform.ini in apps will require lvgl so the user can open the e.g. audio player example and will get everything he needs, or the user needs to add the lv_audio_player as a dependency to his "main" platform.io project?

From my point of view, each app should be independent and consistent. So, each should have it's own platformio.ini, with lvgl & sdl drivers as external libs.

In the same time, if apps are small (current ones have only 1 file each), they can be placed in the same repo, each in it's own subfolder. As far as i understand, those app are like "blinky" demo, not a real products.

Personally, I'm happy with the old-fashioned way, it's not a big burden for me to add the files/files. At least it does what I really want. :slightly_smiling_face:

I understand. When i need new lib for my project, i carefully inspect sources to understand all details. But when i need just run demo, every extra action looks like waste of time. There are no need to push user learn tools when he wish another things.

I had some painful hours while I was trying Platformio but maybe it came only from my inexperience.

Sorry for that. I can only say, PIO 4 is based on python3. Probably it will have no conflict in your system. Try to set extension setting Use Development PIO Core to true. If PIO hangs and you can't do this via menu, put this settings.json to .vscode folder of your project (i expect you experiment with vscode + pio):

{
    "platformio-ide.useDevelopmentPIOCore": true
}
kisvegabor commented 5 years ago

I would move snippets in rework branch from root level into subfolder. Reasons are the same as in my suggestion about lvgl folders :)

Ahh, good idea. I've just updated it.

In the same time, if apps are small (current ones have only 1 file each), they can be placed in the same repo, each in it's own subfolder. As far as i understand, those app are like "blinky" demo, not a real products.

True, in case of apps it's still questionable. With ext. libs. IMO it's clear to use one repo for each library.

Some of the apps can be adapted to real life projects. For example a File Browser.

The pros of using a mono repo for apps:

The cons:

I understand. When i need new lib for my project, i carefully inspect sources to understand all details. But when i need just run demo, every extra action looks like waste of time. There are no need to push user learn tools when he wish another things.

It seems we are on the right path then. People who are interesting a more modern "one-click" solution can use PlatformIO, others can use the submodules or just copy/past the source code.

Sorry for that. I can only say, PIO 4 is based on python3. Probably it will have no conflict in your system.

I'll keep it in mind. Once I'll need the functionality of PIO, I'll try it! Probably with Eclipse.

puzrin commented 5 years ago

IMO it's clear to use one repo for each library.

If you don't plan to actively create new demo apps - no problem. If apps count increase (in long term), org will be "polluted". I don't know you plans, so describe only key factors.

More difficult and update only one specific app in your project.

Could you explain what do you mean? As far as i understand, app is one-time demo, to learn how to code.

kisvegabor commented 5 years ago

Could you explain what do you mean? As far as i understand, app is one-time demo, to learn how to code.

Sure! Let's say you want to use the File browser app in your project. The File Browser will be improved continuously and you want to use the most recent version. If the app was in a lv_app_file_browser repo then you just need to git pull .... If there was a common lv_apps repo and you have manually copied lv_app_file_browser.c/h to your project and even modified it, it would be difficult to update your version.

As I'm thinking the mono app repo can also work if you can enable only the app you need. So git pull lv_apps and disable all apps you don't need. However, will it work will with Pio? Will you be able to add more apps to your project if there is a common lv_apps repo?

puzrin commented 5 years ago

My suggestion about mono repo for apps was with assumption there can be a lot of trivial things, but not for direct reuse. Such micro-demos are convenient in one place both for users and for devs.

I think, if you expect code reuse, then it's a lib, and would be better in separate repo (and it can contain local wrapper for standalone demo). Everything depends on final goals - those define code layout.

As I'm thinking the mono app repo can also work if you can enable only the app you need. So git pull lv_apps and disable all apps you don't need. However, will it work will with Pio? Will you be able to add more apps to your project if there is a common lv_apps repo?

As far as i remember, PIO allows libraries publish from subfolders, but i'm not sure about direct git links (those are convenient in many cases). IMO monorepo for libs is not needed at current stage and in next years.

embeddedt commented 5 years ago

@kisvegabor I've commited the modal message box example as lv_ex_mbox_2.

EDIT: The slider+label demo has been added as lv_ex_slider_2.

kisvegabor commented 5 years ago

@embeddedt

@kisvegabor I've commited the modal message box example as lv_ex_mbox_2. EDIT: The slider+label demo has been added as lv_ex_slider_2.

Awesome, I'll add images and update the index.rst files today.

kisvegabor commented 5 years ago

@puzrin

My suggestion about mono repo for apps was with assumption there can be a lot of trivial things, but not for direct reuse. Such micro-demos are convenient in one place both for users and for devs. I think, if you expect code reuse, then it's a lib, and would be better in separate repo (and it can contain local wrapper for standalone demo). Everything depends on final goals - those define code layout.

Hm, I'll reconsider the organization of apps...

As far as i remember, PIO allows libraries publish from subfolders, but i'm not sure about direct git links (those are convenient in many cases). IMO monorepo for libs is not needed at current stage and in next years.

For ext. libs. I count on < 10 repos for the foreseeable. So there the 1 repo/ext. lib. should work.

embeddedt commented 5 years ago

@kisvegabor I've added the recoloring example as lv_ex_img_2.

From now on, instead of commenting every time I push a new example, I'll just edit the post to say its name.

embeddedt commented 5 years ago

@kisvegabor For apps like the file browser, should I be using the LittlevGL filesystem API or POSIX APIs?

kisvegabor commented 5 years ago

From now on, instead of commenting every time I push a new example, I'll just edit the post to say its name.

Perfect, I'll add the images and review them periodically.

For apps like the file browser, should I be using the LittlevGL filesystem API or POSIX APIs?

It should use LittelvGL file system API.

I was thinking about the organization of apps. IMO the mono repo can work here. @embeddedt If also agree, I'll create an lv_apps repo.

puzrin commented 5 years ago

May be downshift trivial apps to "examples"? What is principal the difference between (when you don't reuse code and app is small)?

kisvegabor commented 5 years ago

May be downshift trivial apps to "examples"? What is principal the difference between (when you don't reuse code and app is small)?

Good question. Examples are simple, short and related only to a specific object type. (the are listed in the documentation of object types). I've checked the list again with this in mind but it seems okay.

kisvegabor commented 5 years ago

@embeddedt I've added images to new examples. I've changed the examples a little bit as well. See: 16cee17

I've created the first examples without any decorations because these files are quite short the decoration takes significant space. I saw that you added the "regular" decoration used in other lvgl files. Do you think these decorations are really helpful here?

embeddedt commented 5 years ago

Do you think these decorations are really helpful here?

Not particularly, but since they were new examples I was trying to follow the coding standard. :wink: If you think they're not necessary I'll remove them.

kisvegabor commented 5 years ago

Not particularly, but since they were new examples I was trying to follow the coding standard.

Commendable attitude :smile:

If you think they're not necessary I'll remove them.

I think it'd be easier to read and digest the examples without the decorations.

embeddedt commented 5 years ago

I have a very basic implementation of the file browser working. All you can do at the moment is view the directory/file tree (no copy/paste/delete/rename/view contents) but it seems to be working. What are the main features are we aiming for?

I will post a screenshot soon.

kisvegabor commented 5 years ago

My intention was to make possible to browse in the directory structure a select a file or directory. (extension filter?)

Features like "copy/paste/delete/rename/view" would require some user experience work too. I'd like to immerse in UX for a long time so I'd be happy work on the "how would it be userfriendly" part.

embeddedt commented 5 years ago

@kisvegabor Maybe we could get some inspiration/ideas from Android file managers.