From edb3b1f78c1582738f8ef499c6baa79bf7d5241e Mon Sep 17 00:00:00 2001 From: frozenwizard <172203+frozenwizard@users.noreply.github.com> Date: Mon, 12 Jun 2023 20:30:18 -0500 Subject: [PATCH] Adding in linting for markdown files --- .github/workflows/lint.yaml | 22 +++++++++++++++ .markdownlint.yaml | 5 ++++ .markdownlintignore | 2 ++ Makefile | 3 +- README.md | 51 ++++++++++++++++++++++++--------- docs/configuring_gunpla.md | 24 ++++++++++++---- docs/developer_setup.md | 25 +++++++++++++---- docs/installation.md | 56 ++++++++++++++++++++++++++++--------- docs/materials.md | 42 ++++++++++++++++++++-------- docs/overview.md | 5 +++- 10 files changed, 184 insertions(+), 51 deletions(-) create mode 100644 .github/workflows/lint.yaml create mode 100644 .markdownlint.yaml create mode 100644 .markdownlintignore diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml new file mode 100644 index 0000000..5dd0e34 --- /dev/null +++ b/.github/workflows/lint.yaml @@ -0,0 +1,22 @@ +name: Lint + +on: + push: + branches: + - main + pull_request: + branches: + - main +jobs: + lint-docs: + name: Lint docs + runs-on: ubuntu-latest + steps: + - name: Check out code + uses: actions/checkout@v2 + + - name: Lint docs + uses: docker://avtodev/markdown-lint:v1 + with: + args: '**/*.md' + config: .markdownlint.yaml \ No newline at end of file diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..a562769 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,5 @@ + +# MD013/line-length - Line length +MD013: + # Number of characters + line_length: 120 diff --git a/.markdownlintignore b/.markdownlintignore new file mode 100644 index 0000000..2314ecd --- /dev/null +++ b/.markdownlintignore @@ -0,0 +1,2 @@ +temp/ +target/ \ No newline at end of file diff --git a/Makefile b/Makefile index b8b2c10..ea0ff1c 100644 --- a/Makefile +++ b/Makefile @@ -55,7 +55,8 @@ format: ## Format the Python code autopep8 -i -r src/ .PHONY: lint -lint: ## Lints the python code +lint: ## Lints the python code and documents + markdownlint --fix **/*.md pylint src/ --ignore src/phew help: ## Show this help. diff --git a/README.md b/README.md index 46ffc1f..7585dcd 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,23 @@ # GunplaLED ## What is this? -This repo contains Python code that deploys to a [Raspberry Pi Pico W](https://www.raspberrypi.com/documentation/microcontrollers/raspberry-pi-pico.html#raspberry-pi-pico-w-and-pico-wh) that runs a web server allowing you to control individual LED's or program lightshows for a Gundam (or other gunpla) model kit. + +This repo contains Python code that deploys to a [Raspberry Pi Pico W](https://www.raspberrypi.com/documentation/microcontrollers/raspberry-pi-pico.html#raspberry-pi-pico-w-and-pico-wh) +that runs a web server allowing you to control individual LED's or program lightshows for a Gundam (or other gunpla) +model kit. ## Why? -When I was building RX-93 Nu Gundam ver ka, it lets you use a green LED module to light up the head. It was basically out of stock everywhere, so I had to look for alternatives. I also didn't like the idea of not having easy access to the on/off of the LED and having to replace batteries. So I wanted something more hardwired into an outlet that I could plug/unplug. I also do a lot of home automation, so I thought it'd be cool to have it connected to a smart plug. Seeing others on r/gunpla do more complicated LED setups and all the above made me think of running some sort of server I can cURL to make it light up. Then research led me here. + +When I was building RX-93 Nu Gundam ver ka, it lets you use a green LED module to light up the head. It was basically +out of stock everywhere, so I had to look for alternatives. I also didn't like the idea of not having easy access to +the on/off of the LED and having to replace batteries. So I wanted something more hardwired into an outlet that I could +plug/unplug. I also do a lot of home automation, so I thought it'd be cool to have it connected to a smart plug. +Seeing others on r/gunpla do more complicated LED setups and all the above made me think of running some sort of server +I can cURL to make it light up. Then research led me here. **tl;dr** A Pico W and green LED is about the same cost as the official LED module but cooler. ## Goals of this project + * Be simple for anyone not technical to install and configure LEDs to their gunpla * Widespread Gunpla kit support * Thorough LED installation documentation and simple configuration @@ -15,27 +25,42 @@ When I was building RX-93 Nu Gundam ver ka, it lets you use a green LED module t * Widespread community support ## Project Status -This project is in early alpha. It is considered to be functional and fulfills the minimum requirements of hosting a webserver that can control individual LEDs. However, there is still much to be done in terms of adding support for more gunpla models, expanding lightshows, bug fixes, etc. Therefore, until this project hits beta, there is no backwards support as areas of the codebase are rapidly changing and improving. Thus, when upgrading, it is recommended to start from the initial setup. -# Installation -At this time installation requires setting up a local Python development environment as some of the tooling requires it. The recommended OS's are GNU/Linux(Ubuntu) and macOS. Windows is not currently supported but is on the roadmap as it has a more complicated way of talking to the Raspberry Pi. +This project is in early alpha. It is considered to be functional and fulfills the minimum requirements of hosting a +webserver that can control individual LEDs. However, there is still much to be done in terms of adding support for more +gunpla models, expanding lightshows, bug fixes, etc. Therefore, until this project hits beta, there is no backwards +support as areas of the codebase are rapidly changing and improving. Thus, when upgrading, it is recommended to start +from the initial setup. + +## Installation + +At this time installation requires setting up a local Python development environment as some of the tooling requires it. +The recommended OS's are GNU/Linux(Ubuntu) and macOS. Windows is not currently supported but is on the roadmap as it +has a more complicated way of talking to the Raspberry Pi. See the [installation instructions](docs/installation.md) for a full walkthrough of how to install -## Requirements + +### Requirements + * cli: make, python, pip, pyenv (optional) -# Developer Setup -The [developer setup](docs/developer_setup.md) to add and contribute to the project mainly consists of setting up an IDE environment in addition to setting up the tooling in [installation](docs/installation.md). +## Developer Setup + +The [developer setup](docs/developer_setup.md) to add and contribute to the project mainly consists of setting up an +IDE environment in addition to setting up the tooling in [installation](docs/installation.md). + +## Contributing -# Contributing -Contributions are very much welcome. For bugs and/or feature requests file a [issue](https://github.com/frozenwizard/GunplaLED/issues). If you'd like to contribute to a specific area such as HTML, additional kit support, etc submit a [PR](https://github.com/frozenwizard/GunplaLED/pulls) as well. +Contributions are very much welcome. For bugs and/or feature requests file a [issue](https://github.com/frozenwizard/GunplaLED/issues) +. If you'd like to contribute to a specific area such as HTML, additional kit support, etc submit a [PR](https://github.com/frozenwizard/GunplaLED/pulls) +as well. + +## Roadmap -# Roadmap * Better documentation for installation of each LED's on each kit -* More Gunpla model support +* More Gunpla model support * Windows support * Better UI * More lightshows and LED effects * Easier installation and configuration * Package and deploy dependencies better * Add the ability to play sounds - diff --git a/docs/configuring_gunpla.md b/docs/configuring_gunpla.md index 1637cda..9974118 100644 --- a/docs/configuring_gunpla.md +++ b/docs/configuring_gunpla.md @@ -1,14 +1,18 @@ # Gunpla Configuration + This document describes how to modify the [settings.py](/src/settings.py) file and the associated config.json in src/config ## settings.py + This file is autogenerated during the ```make setup``` phase. It contains 3 important fields * **wifi configuration**: Enter your wifi information in ssid and password * **hostname:** Set the name of "url" to connect to -* **model**: This requires importing the appropriate gunpla model or using the generic model in src/gundpla in the top of the file and using a Python construction to create the Python model. +* **model**: This requires importing the appropriate gunpla model or using the generic model in src/gundpla in the top of +the file and using a Python construction to create the Python model. ### Example settings.py + ```python from src.gunpla.nu_gundam import NuGundam @@ -21,10 +25,20 @@ webserver = { ``` ## config.json -Every Python gunpla class (in src/gunpla) has an associated configuration file in src/config. This configuration file contains a mapping of LEDs to physical pins on the Pico board and a list of lightshows. [Nu Gundam](/src/config/nu_gundam.json) contains the current examples of how to add lightshows and disable individual leds. As this configuration evolves this document will be expanded to describe all the options. -LEDs to pins can be removed/updated or the entry can be modified to have ```"disabled": true``` inserted to disable the LED. Thus the configuration doesn't have to match what LED's you have installed in your kit. For example, [Nu Gundam](/src/config/nu_gundam.json) has all 6 fin funnels deployed, yours may just have 3 deployed and a beam saber you want lit up. Thus, change it to suit how you want to display your mobile suit. +Every Python gunpla class (in src/gunpla) has an associated configuration file in src/config. This configuration file +contains a mapping of LEDs to physical pins on the Pico board and a list of lightshows. [Nu Gundam](/src/config/nu_gundam.json) +contains the current examples of how to add lightshows and disable individual leds. As this configuration evolves this +document will be expanded to describe all the options. + +LEDs to pins can be removed/updated or the entry can be modified to have ```"disabled": true``` inserted to disable the +LED. Thus the configuration doesn't have to match what LED's you have installed in your kit. For example, [Nu Gundam](/src/config/nu_gundam.json) +has all 6 fin funnels deployed, yours may just have 3 deployed and a beam saber you want lit up. Thus, change it to +suit how you want to display your mobile suit. ### Lightshows -Lightshows are listed in the config.json, this contains a human-readable name(name) for it, a short url endpoint(path) and the associated Python function(method). -The implementation of a lightshow is primarily in Python. It uses helper functions to get the name of an LED and the class LEDEffects to perform advanced effects such as brightening, glowing, pulsating, etc. \ No newline at end of file + +Lightshows are listed in the config.json, this contains a human-readable name(name) for it, a short url endpoint(path) +and the associated Python function(method). +The implementation of a lightshow is primarily in Python. It uses helper functions to get the name of an LED and the +class LEDEffects to perform advanced effects such as brightening, glowing, pulsating, etc. diff --git a/docs/developer_setup.md b/docs/developer_setup.md index c046ead..c6763c1 100644 --- a/docs/developer_setup.md +++ b/docs/developer_setup.md @@ -1,30 +1,43 @@ # Developer Setup -The recommended IDE is [Pycharm Community](https://www.jetbrains.com/pycharm). You will need to install the [micropython plugin](https://plugins.jetbrains.com/plugin/9777-micropython). + +The recommended IDE is [Pycharm Community](https://www.jetbrains.com/pycharm). You will need to install the +[micropython plugin](https://plugins.jetbrains.com/plugin/9777-micropython) ## Tooling Installation -The tools needed to build and deploy are the same as the normal installation. Follow [this](/docs/installation.md#tooling-setup) for that setup. + +The tools needed to build and deploy are the same as the normal installation. Follow [this](/docs/installation.md#tooling-setup) +for that setup. ## Debugging -Right now, there is no IDE support for debugging remotely and pdb has not been tested. So all debugging needs to be done with a Pico board attached and primarily through log or print statments + +Right now, there is no IDE support for debugging remotely and pdb has not been tested. So all debugging needs to be +done with a Pico board attached and primarily through log or print statements. The easiest way is to connect the Pico to the computer and run the following commands: Build and deploy the latest code + ```shell make build deploy && rshell ``` + Navigate to the Pico board file system + ```shell cd /pyboard -``` +``` + Activate the interactive Python interpreter + ```shell repl -``` +``` + Import and run the webserver + ```python import main main.main() ``` -The server logs start to appear in the console. +The server logs start to appear in the console. diff --git a/docs/installation.md b/docs/installation.md index 2d461cd..ff635ea 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,56 +1,86 @@ # Installation + The following describes how to set up the necessary software tooling and deploys software to the Pico board. -It is assumed that the user knows what a terminal, shell, etc is and how to use it, but has nothing configured on their system. -#TODO: Link to an external overview of what the terminal and shell is, and how to use it. +It is assumed that the user knows what a terminal, shell, etc is and how to use it, but has nothing configured on their +system. TODO: Link to an external overview of what the terminal and shell is, and how to use it ## Tooling Setup + ### Prerequisites + #### macOS + Install [brew.sh](https://brew.sh) to install the macOS package manager + ```shell -brew install pyenv git wget +brew install pyenv git wget markdownlint-cli ``` + #### GNU/Linux(Ubuntu) + ```shell -sudo apt install pyenv git wget make +sudo apt install pyenv git wget make markdownlint-cli ``` After this make sure Pyenv is enabled correctly on your [shell](https://github.com/pyenv/pyenv#set-up-your-shell-environment-for-pyenv) ### Clone this repo -If you have not done so yet git clone this repo to your desired directory. The green '<>code' button in GitHub will give you options on how to do that. + +If you have not done so yet git clone this repo to your desired directory. The green '<>code' button in GitHub will +give you options on how to do that. ### Install tooling -Run the following make command to download micropython, install python, python requirements and generate the config file. This is a one time setup. + +Run the following make command to download micropython, install python, python requirements and generate the config +file. This is a one time setup. + ```shell make setup && pyenv activate gunpla ``` ### Install MicroPython to the Raspberry Pico board -MicroPython needs to be installed on the board before the project can be deployed. Plug a Micro-USB cable into the Pico board, hold down the [bootsel button](https://projects-static.raspberrypi.org/projects/getting-started-with-the-pico/725a421f3b51a5674c539d6953db5f1892509475/en/images/Pico-bootsel.png) and then plug the cable into your computer. -This sets the Pico board as a usb mass storage device. The following OS appropriate command will automatically deploy MicroPython to the Pico board. + +MicroPython needs to be installed on the board before the project can be deployed. Plug a Micro-USB cable into the Pico +board, hold down the [bootsel button](https://projects-static.raspberrypi.org/projects/getting-started-with-the-pico/725a421f3b51a5674c539d6953db5f1892509475/en/images/Pico-bootsel.png) +and then plug the cable into your computer. +This sets the Pico board as a usb mass storage device. The following OS appropriate command will automatically deploy +MicroPython to the Pico board. + ```shell make install-micropython-osx ``` + Or + ```shell make install-micropython-ubuntu ``` -After completion the board will disappear as a device and reappear silently, so wait 10 seconds before continuing. +After completion the board will disappear as a device and reappear silently, so wait 10 seconds before continuing. ## Deploy the test build -The test build is a simple Python script that helps to make sure the tooling has been setup correctly and things work. The test file will blink the onboard Pico LED several times and then stop. Run the following command, once the transfer has completed, unplug the Raspberry Pi Pico W and then plug it back in. You should see the onboard LEDs flash. + +The test build is a simple Python script that helps to make sure the tooling has been setup correctly and things work. +The test file will blink the onboard Pico LED several times and then stop. Run the following command, once the transfer +has completed, unplug the Raspberry Pi Pico W and then plug it back in. You should see the onboard LEDs flash. + ```shell make build-test deploy ``` + If there are any errors, they should be corrected before continuing to configure your gunpla. ## Deploy your gunpla server -Follow the steps in [configuring your gunpla](/docs/configuring_gunpla.md) to configure some important settings and make any modifications. It is recommended to set the configuration to the GenericGundam and make sure all the settings are correct before installing an LED's. Afterwards, run the following to build and deploy your configuration to the Pico board + +Follow the steps in [configuring your gunpla](/docs/configuring_gunpla.md) to configure some important settings and make +any modifications. It is recommended to set the configuration to the GenericGundam and make sure all the settings are +correct before installing an LED's. Afterwards, run the following to build and deploy your configuration to the Pico +board + ```shell make build deploy -``` +``` -Afterwards, you should be able to open a webpage to the hostname you set in the ```settings.py``` or find the IP address in your routers connected device list. If neither works, follow the [debugging guide](/docs/developer_setup.md) \ No newline at end of file +Afterwards, you should be able to open a webpage to the hostname you set in the ```settings.py``` or find the IP address +in your routers connected device list. If neither works, follow the [debugging guide](/docs/developer_setup.md) diff --git a/docs/materials.md b/docs/materials.md index 24a1cd9..8c2b0ed 100644 --- a/docs/materials.md +++ b/docs/materials.md @@ -1,57 +1,75 @@ # Materials -This document describes the needed materials to modify a gunpla kit to use this software. Individual guides contain specific list parts with regard to LEDs. + +This document describes the needed materials to modify a gunpla kit to use this software. Individual guides contain +specific list parts with regard to LEDs. There are 2 ways to install LEDs, a soldered version and solderless. -The soldered method is the preferred method and gives you far offers more flexibility in design, routing wires through the gunpla kit, etc. It requires basic soldering skills, primarily joining wires together and soldering wires to the holes on the Raspberry Pi Pico W. This is not covered in this project but tutorials can be found on youtube and the internet. This solution is a more permanent solution and is usually more difficult to change. +The soldered method is the preferred method and gives you far offers more flexibility in design, routing wires through +the gunpla kit, etc. It requires basic soldering skills, primarily joining wires together and soldering wires to the +holes on the Raspberry Pi Pico W. This is not covered in this project but tutorials can be found on youtube and the +internet. This solution is a more permanent solution and is usually more difficult to change. The solderless method is an alternative for those: + * who do not have soldering skills or equipment * who want an easy way to install things * who are test building and designing lightshows * who just try this repo out -It is also recommended to use the screw terminal boards listed in the [Solderless kit](#solderless-kit) for some time as it is easier to move LEDs to different pins while configs stabilize. +It is also recommended to use the screw terminal boards listed in the [Solderless kit](#solderless-kit) for some time as +it is easier to move LEDs to different pins while configs stabilize. ## Common Materials + This is a small list of common materials needed irregardless of Solder vs Non-Solder construction + * A gunpla kit * [Drill bits](https://www.gundamplanet.com/db-03-tungsten-steel-drill-bit-set.html) * A 3/16th when resistor is needed * Various hobby tools - * Hobby knife, tweezers, wirecutters, etc for cutting gunpla, wires etc. + * Hobby knife, tweezers, wirecutters, etc for cutting gunpla, wires etc. ## Solder Kit (Preferred Method) -The following is recommended if you know how to solder. + +The following is recommended if you know how to solder. + * Soldering iron, lead-free solder, etc * [Raspbery Pi Pico W](https://thepihut.com/products/raspberry-pi-pico-w?variant=41952994754755) * [Pioc or Z LEDs in the appropriate color](https://evandesigns.com/products/chip-nano-pico-leds?variant=40800157204528) - * In ```3 volt DC``` option -* 15 ohm Resistor 1/2w (0.5Watt) ±1% + * In ```3 volt DC``` option +* 15 ohm Resistor 1/2w (0.5Watt) ±1% * The Raspberry Pi Pico board outputs a 3.3 volts but the 3 volt LED's need a resistor for it. * Evandesigns offers a ```5-12 volt DC``` variant that has a resistor presoldered. Optional (But Recommended parts) + * [Shrink tube for resistor](https://evandesigns.com/products/shrink-tube?variant=6763932680240) * ```1/16th``` variant * This allows you to connect the LED wire to the resistor and secure the soldered joints * Electrical tape is also an option, but not as clean. * Heat gun to shrink the tube or possible hair dryer - * Various options exist across multiple pricepoints + * Various options exist across multiple pricepoints * [Additional wire](https://evandesigns.com/products/magnet-wire-twisted-50-ft-spool) * Larger kits may need additional wire spliced in to extend the LED wiring ## Solderless kit + This is very similar to the above but has some modifications for those that cannot or do not wish to solder wiring. + * [Raspberry Pi Pico WH](https://thepihut.com/products/raspberry-pi-pico-w?variant=41952994787523) * This has headers pre installed for an additional charge, but lets you plug in the Pico board into a common terminal. * [Pico Or Z LEDs in the appropriate color](https://evandesigns.com/products/chip-nano-pico-leds?variant=32158377967664) * ```5-12 volt DC``` variant - * This essentially is the ```3 volt DC``` but has a resistor pre-soldered in. This resistance is incorrect, but will prevent LED's from burning out. + * This essentially is the ```3 volt DC``` but has a resistor pre-soldered in. This resistance is incorrect, but + will prevent LED's from burning out. * The wiring may be too short for this, but EvanDesigns may be able to custom offer longer versions. * [Screw terminal board](https://www.amazon.com/naughtystarts-Brekaout-Soldered-Compatible-Raspberry/dp/B0B1H2S57S/) - * There are various versions and makers that exist and any will do. This will let you wire in the LEDs to the Pico board and secure them by screwing down contacts. + * There are various versions and makers that exist and any will do. This will let you wire in the LEDs to the Pico + board and secure them by screwing down contacts. ## Developer kit -If you intend to write custom light shows or contribute to the project, having a dedicated test kit to debug effects, server operations, etc can be cumbersome. So far it's recommended to use [this](https://thepihut.com/products/screw-terminal-expansion-board-for-raspberry-pi-pico) screw terminal development board. It allows easy modifications to wiring and has built in LED's to help debug without connecting to an existing kit. - +If you intend to write custom light shows or contribute to the project, having a dedicated test kit to debug effects, +server operations, etc can be cumbersome. So far it's recommended to use [this](https://thepihut.com/products/screw-terminal-expansion-board-for-raspberry-pi-pico) +screw terminal development board. It allows easy modifications to wiring and has built in LED's to help debug without +connecting to an existing kit. diff --git a/docs/overview.md b/docs/overview.md index f56aa29..1c4f292 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,5 +1,8 @@ # Project Overview + This file goes over the overall project ## Model Support -Right now this project supports Nu Gundam and all other kits. For any kit that is not Nu Gundam, GenericGundam can be used. \ No newline at end of file + +Right now this project supports Nu Gundam and all other kits. For any kit that is not Nu Gundam, GenericGundam can be +used.