Full rewrite of the Community Template readme with additional help and tips#26
Full rewrite of the Community Template readme with additional help and tips#26ccrawford wants to merge 9 commits intoMobiFlight:mainfrom
Conversation
Expanded the README with detailed instructions on MobiFlight firmware development, including prerequisites, initial build steps, testing, troubleshooting, and coding tips.
Added detailed instructions for device configuration and debugging.
Updated wording for clarity and fixed minor typos.
Updated wording for clarity and consistency in README.
Clarify coding tips for organizing code in [device].cpp and [device].h files. Provide additional details on handling variable updates and screen refresh methods.
Updated description of YouTube video series for clarity.
Add note about MobiFlight configuration precedence and device wipe requirement.
| MobiFlight firmware development uses the following free/open source tools: | ||
| * [VSCode](https://code.visualstudio.com/) Microsoft's free IDE | ||
| * [PlatformIO](https://platformio.org) extension to VS code | ||
| * [Python](https://www.python.org/downloads/) as a runtime for scripts (may already be installed as part of other installs) |
There was a problem hiding this comment.
Python is already part of platformIO, so no need to install it.
There was a problem hiding this comment.
Probably irrelevant as most users will have Python installed regardless. The reason I mention it here is I prefer to run the renaming script from the command line. Does the PIO Python install work outside of a PIO shell? I'm not sure. Regardless, if you want to leave this out, i'm fine.
| Clone the repository and open it in PlatformIO. | ||
| * Open a Windows shell | ||
| * cd to the parent directory for your project | ||
| * run ```git clone https://github.com/MobiFlight/CommunityTemplate``` |
There was a problem hiding this comment.
I think it would be better to fork it on github and clone this fork. If a user will use github later on and from the beginning it shouldn't point to the original repo.
Otherwise the user should download all files as zip file. In this case no git repo is initialized.
There is also the way to use the platformIO GUI to clone a repo which I would prefer to describe. As far as I remember I made some screenshots and posted them on discord.
There was a problem hiding this comment.
Agree. I will be the first to admit my git skills are limited. If this is the way it should be done, would you provide the correct directions?
I hate doing screen shots as the UI can change over time and the screen shots need to be maintained. The command line never changes so is easier for users and document maintainers.
| * rename the new 'CommunityTemplate' directory to something appropriate for your project | ||
|
|
||
| ## Renaming script to prepare the firmware | ||
| * cd into your new directory |
There was a problem hiding this comment.
Hmhm, why not from the build in terminal from PlatformIO as deescribed in the actual version?
At least when the user want's to built the FW he has to work within this teminal window, so he could do it right from the beginnung.
And the user doesn't have to change between CLI and PlatformIO
There was a problem hiding this comment.
I do all the pre-work in command line: create the home directory. Clone the repo. Do the rename. From there on I work in VS Code. It's just what I prefer. Certainly there's more than one way to do this as we've talked about in the past.
If you'd prefer that the instructions reflect your workflow, I'm totally fine with that and wouldn't be offended by your changes, but I'd need you do to the editing and screen shots because I don't know what you do.
We could provide streamlined, generic instructions as a tldr at the top:
- Fork and clone the community template from https://github.com/mobiflight/community_template
- Run the renaming script renaming.py
- Open the solution in VS Code w/ PlatformIO
- Edit the Board, Device .json the CustomDevice.cpp and .h and your class .cpp and .h
- Compile and Upload to your board and deploy the Community Folder.
2 participants
Description of changes
Fixes #25
Extensive re-write of the current Readme with more information on the role of key files, common traps, tips for improving workflow, and FAQs on community devices.