On Mon, Sep 1, 2025 at 9:13 PM Matteo Golin <[email protected]> wrote: > That sounds like a good idea, Tomek. I'll take a look at the release 13.0.0 > planning. We just need to make sure anything we commit to publically is > really tackled in 13.0.0 and be transparent. It will be even worse for > users if we say we've stabilized certain parts of the code-base and then > break them later without warning because we reverted back to the old ways.
Thanks man :-) > I think the look of the documentation isn't terrible, but I believe the RST > docs are really meant to be targeted towards API documentation and > information about how frameworks can be used. Technical documentation, in > other words. I don't think RST documentation is well-suited towards some of > the other things we've been using it for, like written guides and large > explainers. Nah, RST is just a format, like MD, but a bit more complex and versatile. All projects I know use Sphinx now and RST. Even those who contain documentation directly in the code (i.e. Python modules). Sphinx gives us ability also to create PDF that is important for offline work and there was demo created some time ago. I would stick to Sphinx and RST. Content is most important. We should not break documentation again to switch tools :-P > This is pretty evidenced by how bad the Sphinx search feature > is unless it's given a symbol to find. That may need some investigation and fixing. All projects I know use Sphinx now and search works there. Maybe we just need some configuration tweaking? > Personally, I propose that the NuttX > main website gets some more pages added to it. Yup, current template does no build on my FreeBSD. We may switch generator to something that works. There is an issue for that but I did not have time to play sorry. > A really big one would be a > tutorials page, and I personally don't think that belongs in the RST docs. I think this should be part of the main documentation. Otherwise it gets out of sync from the code quickly. Also will be part of single documentation page. Maybe rearrangement would be enough? > It can link to written tutorials and also the video guides. We have YouTube NuttX channel :-) > I also think we > desperately need a testimonials page where people can see what projects > NuttX has been used for commercially and by hobbyists. +1 :-) > Maybe even a link to our Reddit. Sure it can be added here: https://nuttx.apache.org/community/ > So many people I've talked to have never heard of NuttX, but > they all know FreeRTOS and Zephyr (despite never using them). They don't > think NuttX can be good for new projects if they've never heard of it, even > though it's very mature! I think a little more advertising on the website > will help this sentiment, since then they can see the caliber of projects > NuttX supports. Yup, I really love Alan's demos and various hands-on examples, that convinced me to take a look at NuttX, we need more!! :-) On the other hand, people just go to what is more popular. I came to NuttX in the end after playing with all other RTOS and knowin their problems on my own butt :D > Regardless, it won't be hard to take guides written in RST and put them > elsewhere on the website later. That shouldn't slow us down in pushing > initially to get more tutorials and testimonials up, we can transfer > things/make it look pretty afterward or it will never get done. Perfect is > the enemy of good. I'll start planning out some possible issues we can > raise. Maybe we can set up another "mini survey" just to grab people's > photos/videos/links to projects they want featured? This time advertising > it on Reddit, LinkedIn and the mailing list? Currently we have static website that is converted from some template and the published to the web server. The similar mechanism for documentation. We may keep that for the main project site and documentation, as it only contains crucial information, and is hard to hack. We may have separate subdomain with wordpress just as for https://events.nuttx.apache.org/ but for projects / showcases. This should be easy to edit and update by many people. We talked about showcaes like that and it turned out to use Hackster and other channels to be better to maintain over our own wordpress. The main concern right now is not to create yet another site, but to have interesting content :-) Thanks :-) Tomek > > Matteo > > On Mon, Sep 1, 2025 at 3:00 PM Tomek CEDRO <[email protected]> wrote: > > > Thank you Filipe, that would be great if you could help our documentation! > > :-) > > Tomek > > > > > > On Mon, Sep 1, 2025 at 8:21 PM Filipe Cavalcanti > > <[email protected]> wrote: > > > > > > Great comment. > > > > > > I also really liked this survey. My recommendation is to expand it next > > time: post on LinkedIn and Reddit pages so we get more data. > > > > > > Regarding the documentation, which seems like one of the biggest issues, > > we can start formatting a new version of it. I will try and contribute to > > the API docs, which are more on the kernel side and it definetely needs > > some love. > > > ________________________________ > > > From: Matteo Golin <[email protected]> > > > Sent: Monday, September 1, 2025 1:28 AM > > > To: [email protected] <[email protected]> > > > Subject: Re: NuttX Hardware Survey 202508 > > > > > > > > > [External: This email originated outside Espressif] > > > > > > This survey was a really good idea! Looking at the feedback for things > > to improve, it looks like documentation, better tutorials/help resources > > and stability are the biggest wishes from the community. > > > > > > I think a lot of these suggestions can be turned into issues on the > > GitHub repo and actioned on. Things like adding a code owners file is a > > great idea and would be easy to start with. That way, PRs that touch > > certain files can get automatically suggested to be reviewed by the person > > who originally wrote the code. This might not catch everything but I'm > > thinking that would be smart for something like individually contributed > > drivers or initial architecture ports. We can just set up a baseline file > > (populated by cross-checking with git blame) and have users add themselves > > to certain parts of the codebase as they contribute stuff. > > > > > > We have quite a few different issues open for improving the > > documentation, mostly converting text files to .rst files and getting some > > information filled in about applications that are sitting with empty pages. > > I think the code owners file will help with this; I suggest people who find > > gaps in our documentation raise a GitHub issue and then we can easily > > determine from the code owner files who the original author is so that they > > can maybe quickly clear up the question. As they answer the user question, > > the issue comments can be summarized and converted to docs. The community > > is right though, the documentation is still pretty rough around the edges. > > Lots of duplicated information, difficulty navigating certain parts of it > > and big gaps with things like just setting up the NuttX repository and an > > app to start a project. I think the documentation could also use some > > well-placed links, like to tutorials on the NuttX YouTube channel or even > > just back-links to other documentation pages where something is relevant. > > Search engines tend to favour this as well. > > > > > > I may have some spare time to write/record some tutorials for using some > > of the RP2040 boards I own. I also think user requests for a forum that is > > more accessible than the mailing list are valid; e-mail is pretty > > antiquated. Discussing main concerns here for project direction is fine, > > but I think it would be good to advertise Reddit more as a public forum for > > Q&A/support. It doesn't have the problem of information getting lost like > > the Discord server, and is indexable by search engines. That will start to > > draw more users to the project as well I think. > > > > > > I also see a lot of the responders use ARM as a primary target > > architecture. That makes sense considering it also has so many supported > > chips. I think cleaning up the STM32 family of chips is probably a high > > priority based on what users have commented and also the number of people > > who use it & ARM. If we can reduce the size of the code for that > > architecture it should be easier to keep stable. Any new features/bug fixes > > will be accessible to all STM32 chips it can apply to, and anything that > > gets broken can be caught quickly by multiple people all using different > > STM32s. > > > > > > I also like the idea one user suggested of getting large semiconductor > > companies to use NuttX as a supported platform, but I think it may need to > > be stabilized a little further first. Maybe there are some ISO standards > > that are easy-ish to obtain/be compliant with as open source software that > > would encourage companies to use NuttX? I also would really like to see > > some more interesting applications in the NuttX suite of applications. A > > minimal SSH client/server would be very cool to have ported, or some IoT > > stuff. > > > > > > Definitely a lot to do but great that we got some insight about what the > > community actually wants to see focus on. Should a separate thread be > > started for turning the feedback into actionable issues on the GitHub > > tracker? > > > > > > Best, > > > Matteo > > > > > > On Sun, Aug 31, 2025 at 9:49 PM Tomek CEDRO <[email protected]> wrote: > > > > > > Thank you everyone for participating in the NuttX Hardware Survery > > 202508! > > > > > > Things we like are our current reward, things we need to improve should > > become our priorities to fix, as well as future focus goals. Turns out it > > was good to ask these questions :-) > > > > > > Now its time to discuss over the results.. all comments are welcome! > > Then I will try to sum things up and present on the NuttX International > > Workshop what do you think? :-) > > > > > > BIG THANK YOU! :-) > > > Tomek > > > > > > > > > > > > > > > > > > > > > > > > > > > WHAT DO YOU LIKE ABOUT NUTTX? > > > * Unix-based, lightweight. > > > * Overall architecture, build configuration system, very active and fast > > maintainers :) > > > * Rich features and easy to build apps over it. > > > * High performance, small footprint, featurer rich. > > > * It's POSIX compatibility, and how things are integrated. > > > * posix. > > > * Amazingly clean and elegant self-contained old-school and future-proof > > design. > > > * Community: enthusiasts, professionals, academic, retro, young, old, > > friends worldwide! > > > * POSIX. > > > * BSD like Unix on MCU. > > > * Portable from 8-bit to 64-bit and different CPU architectures. > > > * Extremely versatile but conservative approach. > > > * Over thousand ready to use firmware configurations. > > > * No enforced changes. > > > * Everything! > > > * The application easy port for other HWs. > > > * Configurability, libraries, POSIX. > > > * Open source, POSIX, and its license. > > > * One RTOS for many architectures, emphasis on POSIX. > > > * Good, quality code. Understandable layers of software. POSIX is the > > most beneficial thing and having the NSH is a big plus, since it gives a > > more "premium" feeling. It is very easy to work on and to build, since not > > many requirements are needed. > > > * Ease of use. Portability. Community. > > > * POSIX compliance. > > > * POSIX Compliance, Configurability, Community. > > > * POSIX, small and configurable, open source and great community. > > > * It's a nice bundle of drivers and APIs to make life easier. The > > nuttshell helps with debug and field config. POSIX allows certain code to > > be written on PC before porting it to an embedded system, accelerating > > development. Also good for portability. > > > > > > WHAT YOU DON'T LIKE ABOUT NUTTX? > > > * Could be better documented. > > > * Some architectural constraints are a bit obscure and must be learned > > from the source code rather than being clearly documented. > > > * The build process tends to appear "old" and clunky in some parts. > > > * Contributing changes to the upstream is sometimes time consuming due > > to the lack of an easy to use formatter/linter and not being able to run an > > exact copy of the CI environment locally (at least not in a documented and > > reproducible way). The same goes for development practices that are not > > clearly described anywhere. Also, when trying to do something for the first > > time (even basic actions like reading GPIO and such), it can be quite > > difficult to identify "the NuttX way" of doing so. Maybe more basic guides > > in the documentation would help, because the example apps are often either > > very simple or very complex, with few inbetweens. > > > * Not having a dedicated discussion forums like other communities, using > > mailing list is okay, but using it for everything is cumbersome. > > > * Patchy documentation (often out of date). > > > * PR's that seemed to be merged too quickly without proper discussion > > or, worse, testing. A feeling that some corporate "mergers" put their > > company's interests above all? > > > * Although it tries to emulate an operating system as much as possible - > > so POSIX compliant applications can run - there are several restrictions on > > how it is architectured. From "errno" value being used in both kernel & > > userspace, syslog calls all along the kernel - whereas it should be a > > userspace-only call, or the SIGEVENT not working when in protected builds. > > > * incompatibilit. > > > * Documentation needs an update, better tutorials and examples for > > newcomers. > > > * Hard to configure beyond existing examples. > > > * Partial support of most hardware, not always ready to production use > > in required configuration. > > > * Too strong duplication in some areas (i.e. competing STM32 drivers). > > > * Poor quality of some commits - too fast, too much, untested, > > undocumented, breaking. > > > * Dependencies on external SDK in some places (i.e. ESP32, rPI). > > > * Some board/archs have low maturity BS. > > > * Lack of security, i.e. Trustzone. > > > * Building is challenging and the documentation is rather poor. > > > * Please don't download third party code in the build without permission. > > > * Documentation on crucial stuff is outdated or not well written. That > > includes many APIs such as network, wireless, memory management. > > > * Most of the time, the documentation page is empty and I need to read > > the source code and look at examples, hoping to understand how the thing > > works. > > > * Entire NuttX needs a visual upgrade, from documentation page (which > > looks like an abandoned project) to an official website. > > > * Project management has improved but still needs some stuff, such as > > code owners (if possible) to avoid issues like one big refactor crashing > > boards, and it goes unnoticed because we have no tests, which brings me to > > the next big issue on NuttX: test. It is not possible to keep growing if we > > don't test. > > > * Breaking changes > > > * Roadmap/development is uncontrolled causing breaking changes to API. > > > * I have also spent much time fixing bugs in code i expected was mature. > > > * The errors seems to be introduced due to poor/no peer review and no > > testing. > > > * I work with the STM32H7 family and it is very unfortunate that the > > driver code is copy pasted for each MCU. > > > * Frustrating breakages that are hard to track down, lack of > > documentation/difficult to find documentation. > > > * APIs like IOCTLs should be more standardized and universal, increasing > > portability. > > > * There are also broken or unstable features or boards, this must be > > documented and tested. > > > * Also my biggest negative would be lack of documentation on how to > > structure a project (eg, out of tree boards and drivers, forking, external > > apps, out of tree apps.). > > > * I still haven't figured out the best way to maintain private NuttX > > projects. > > > > > > WHAT SHOULD WE FOCUS NEXT? > > > * Every time I return to it, I'm pleasantly surprised. > > > * I don't think I can say where it should focus, at my current level. > > > * Cleaning up old code and bringing it up to modern standards (intended > > as internal NuttX coding practices). > > > * Improving basic tooling and documentation. > > > * Extend CMake support to all boards. > > > * Possibly also add some architectural diagrams to the documentation, > > like the ones found here: https://deepwiki.com/apache/nuttx. > > > * NA > > > * Stability, documentation, insistence of using the approved PR > > process!!! > > > * SIGEVENT support on userspace when in protected mode. > > > * Stability. > > > * Assuring self-compatibility and long term maintenance as the ultimate > > goal. > > > * Clearly marking breaking changes with a quick-fix instructions if > > unavoidable. > > > * Documentation: sync with old docs, fill in missing places, tutorials, > > step-by-step examples, pdf output. > > > * Better commits quality and processing (i.e. respect to git master, > > descriptions, testing logs and instructions) over quantity. > > > * Better hardware runtime testing on a real world hardware. > > > * Cleanup of existing arch / boards / drivers code, add missing features. > > > * Trustzone. > > > * No expectations. > > > * Testing infrastructure. > > > * Test, test, test. > > > * LTS version. > > > * Attracting larger semiconductor companies to use NuttX as a supported > > platform. > > > * Quality, stability, incl automated test. > > > * A Long Term Support release would be of great value to me. > > > * I really want to see breaking changes well documented and new features > > well documented as they come in. > > > * If NuttX could take some time to make the documentation for existing > > functionality better and also show some projects made with NuttX, that > > would be great. > > > * Also use the Reddit! > > > * Universal / portable APIs. > > > * Document project structures. > > > * Mark broken things as broken (Quality control / assurance?). > > > > > > HOW CAN WE IMPROVE SURVEY? > > > * The survey is already a great idea. I can't add anything more at the > > moment. > > > * A more closed question on what is liked/disliked/improvable about > > NuttX could be helpful in addition to the open textbox, like a list of > > checkboxes. > > > * For the "rarely used"-like questions, better use an option circular > > button rather than a checklist, as all items can be checked and it doesn't > > make sense to "rarely use" something at the same time you "use it > > frequently" ;) > > > * Please remove Freescale from the list, they don't exist as company > > (they became part of the NXP) > > > > > > > > > > > > -- > > > CeDeROM, SQ7MHZ, http://www.tomek.cedro.info > > > > > > > > -- > > CeDeROM, SQ7MHZ, http://www.tomek.cedro.info > > -- CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
