|
1 | 1 | # PixLeZ - Documentation |
| 2 | +## Quick Start |
| 3 | +Once you set up the server using your Raspberry Pi (please refer to the readme on the server for this) and have it running (using `python app.py`), you need to first head over to the settings-section to specify the connection. |
| 4 | +Enter the IP address of your raspi and the number of LEDs on your light strip. You only need to do this once. |
| 5 | +After that, head over to `Controller`, start the server and assign a color of your choice. Finally, you can open `effects` and select an effect of your choice by long-pressing the button. |
2 | 6 |
|
3 | | -[](https://github.com/Excyto) |
4 | | -[](https://github.com/Excyto/PixLeZ) |
5 | | -[](https://github.com/Excyto/PixLeZ/blob/master/LICENSE) |
6 | | -[](https://github.com/Excyto/PixLeZ) |
| 7 | +## Controller |
| 8 | +The controller allows you to specify various parameters for your effects. For example, many effects (besides, e.g. Rainbow) need you to specify a color. In order to avoid seeing no effects, set a color other than black using the sliders. |
| 9 | +The first three sliders red, green and blue allow you to compose your color, whereas the fourth slider controls the intensity of the color. Set it to a high level in order to make the effects darker. |
| 10 | +The number-parameter specifies how many pixles are shown, this is not used for all effects (but for example for walking pixles). |
7 | 11 |
|
8 | | -[](hhttps://github.com/Excyto/PixLeZ) |
9 | | -[](https://github.com/Excyto/PixLeZ) |
10 | | -[](https://github.com/Excyto/PixLeZ) |
| 12 | +## Custom Themes |
| 13 | +This section allows you to create your own themes and effects. |
| 14 | +tbd |
11 | 15 |
|
12 | | -## Introduction |
| 16 | +## Effects |
| 17 | +In this tab you can start various effects. Try them out to see what they look like! :) |
| 18 | +In order to select an effect, hold the button until a small icon appears. By this, you should be prevented from accidentally switching effects. |
13 | 19 |
|
14 | | -PixLeZ is a Software-Bundle for controlling the [WS2801 Pixels](https://github.com/adafruit/Adafruit_Python_WS2801/blob/master/Adafruit_WS2801/WS2801.py) with a Raspberry Pi. |
15 | | -The Bundle contains a server application, running on the Raspberry Pi and different clients for control the server. |
| 20 | +## Modes |
| 21 | +This is similar to effects, but more ambient-oriented. Here, you can also switch off the lights. |
16 | 22 |
|
17 | | -## Content |
| 23 | +## Settings |
| 24 | +In this section, you specify the IP-Address of your server and the number of LEDs your light-strip is equipped with. |
18 | 25 |
|
19 | | -- Raspberry Pi Setup (Hardware and Software) |
20 | | -- PixLeZ-Server running on the Raspberry Pi |
21 | | - - API calls via local network and the browser |
22 | | - - Effects and Modes |
23 | | - - Own Effects and Modes |
24 | | - - Example: Use the API |
25 | | -- PixLeZ-Desktop application for Windows, developed with `C#` |
26 | | -- PixLeZ-Application, a cross platform app, developed with `flutter` |
27 | | -- PixLeZ-Simulator, developed with `Python` |
28 | | -- About |
29 | | -- Links |
30 | | - |
31 | | -## Setup the Raspberry Pi |
32 | | - |
33 | | -### Hardware |
34 | | - |
35 | | -For the Hardware part, follow the descriptions bellow. |
36 | | - |
37 | | -- [Raspberry Pi Tutorial Setup (ger)](https://tutorials-raspberrypi.de/raspberry-pi-ws2801-rgb-led-streifen-anschliessen-steuern/) |
38 | | -- [Raspberry Pi Tutorial Setup (en)](https://tutorials-raspberrypi.com/how-to-control-a-raspberry-pi-ws2801-rgb-led-strip/) |
39 | | - |
40 | | -There is a picture of my personal setup. |
41 | | - |
42 | | -- TODO: Bild hier einfuegen |
43 | | - |
44 | | -### Software |
45 | | - |
46 | | -For the software part you have to install some `python` libraries with the following commands. |
47 | | - |
48 | | -```sh |
49 | | -sudo apt-get update |
50 | | -sudo apt-get install python[Version] |
51 | | -sudo apt-get install python-pip -y |
52 | | -sudo pip install RPi.GPIO |
53 | | -sudo pip install Adafruit-GPIO |
54 | | -sudo pip install adafruit-ws2801 |
55 | | -sudo pip install flask |
56 | | -``` |
57 | | - |
58 | | -## PixLeZ-Server |
59 | | - |
60 | | -> Path: `./PixLeZ_Server` |
61 | | -
|
62 | | -The base of the application is a simple flask server running with python, controlling your [WS2801 Pixels](https://github.com/adafruit/Adafruit_Python_WS2801/blob/master/Adafruit_WS2801/WS2801.py). After the configuration of your Raspberry Pi with the packages in the Software part, you need to move the `./PixLeZ_Server` directory to your Raspberry Pi. After that, you can simply run the server inside the directory using the following command. |
63 | | - |
64 | | -```sh |
65 | | -python app.py |
66 | | -``` |
67 | | - |
68 | | -The PixLeZ-Server is now accessible via the local network. For [configuration](https://flask.palletsprojects.com/en/1.1.x/api/?highlight=run#flask.Flask.run) changes modify the statement below in the file `app.py` and restart the application `app.py` after. |
69 | | - |
70 | | -```python |
71 | | -app.run(debug=True, port=8080, host="0.0.0.0") |
72 | | -``` |
73 | | - |
74 | | -### API calls |
75 | | - |
76 | | -After installing, the PixLeZ-Server provides the following API. The API is used by the applications described in the next few sections, but can also be used via a webbrowser or an other application. |
77 | | -The term `changeable during runtime` is used to describe that the attributes can be changed during the execution of an effect or mode. The change of attributes with `non changeable during runtime` will be changed after selecting a new effect or mode, or after doing an `/stop` and `/start`. |
78 | | -Each time you select an effect, the mode attribute will turn to `-1` and backwards. Furthermore after selecting an effect or mode, the program will automatically do an `/stop` and `/start`. |
79 | | - |
80 | | -```python |
81 | | -# starts the process -> only call in the beginning or after a stop |
82 | | -@app.route('/start') |
83 | | - |
84 | | -# stops the process |
85 | | -@app.route('/stop') |
86 | | - |
87 | | -# String color in HEX -> Example /set/color/FF00FF |
88 | | -# changable during runtime |
89 | | -@app.route('/set/color/<string:color>') |
90 | | - |
91 | | -# time as floating number |
92 | | -# changable during runtime |
93 | | -@app.route('/set/time/<float:post_id>') |
94 | | - |
95 | | -# timer as floating number |
96 | | -# non changable during runtime |
97 | | -@app.route('/set/timer/<float:post_id>') |
98 | | - |
99 | | -# number as integer |
100 | | -# changable during runtime |
101 | | -@app.route('/set/number/<int:post_id>') |
102 | | - |
103 | | -# mode as integer -> the mode will automatically change and the effect is set to 0 |
104 | | -# changable during runtime |
105 | | -@app.route('/select/mode/<int:post_id>') |
106 | | - |
107 | | -# effect as integer -> the effect will automatically change and the mode is set to 0 |
108 | | -# changable during runtime |
109 | | -@app.route('/select/effect/<int:post_id>') |
110 | | - |
111 | | -# returns the status of the attributes |
112 | | -@app.route('/status') |
113 | | - |
114 | | -# Set a custom Color Theme |
115 | | -# Body: List of hex-colors |
116 | | -# changable during runtime |
117 | | -@app.route('/set/pixels', methods=['POST']) |
118 | | -``` |
119 | | - |
120 | | -### Effects and Modes |
121 | | - |
122 | | -The following tables describes the different effects and modes which can be used. In the last column there are some shortcuts used to give the opportunity for manipulating the effects or modes. |
123 | | - |
124 | | -- c := Color in Hex |
125 | | -- t := time in sec |
126 | | -- tr := timer in sec |
127 | | -- n := number in x |
128 | | - |
129 | | -#### Effects |
130 | | - |
131 | | -|Index |Name |Decription |Config | |
132 | | -|---------|---------|---------|---------| |
133 | | -|-1 |Init |No Effect active| | |
134 | | -|0 |Shine |Switching all Pixels on |c| |
135 | | -|1 |Walking Pixels |Pixels walking to one side|c, t, n| |
136 | | -|2 |Walking Pixels reverse |Pixels walking to the other side|c, t, n| |
137 | | -|3 |Fill it |Insort the selected number of Pixels|c, n| |
138 | | -|4 |Get empty |And the Pixels are going away|c, tr, n| |
139 | | -|5 |Final countdown |Countdown with red Pixels|c, tr| |
140 | | -|6 |Pulsing Pixels |Pulsating Pixels everywhere|c, t| |
141 | | -|7 |Dim Off |Dim the Pixels off|c, tr| |
142 | | -|8 |Rainbow Mode |The Pixels change in the Spectrum of the Rainbow|t| |
143 | | -|9 |Rainbow Walk |Pixels walking in the Spectrum of the Rainbow|t| |
144 | | -|10 |Rainbow Puls |Pixels pulsing in the Spectrum of the Rainbow|t| |
145 | | -|11 |Cyclon Pixels |Pixels making a huge Cyclon|c, t, n| |
146 | | -|12 |Twinkle It |Pixels can twinkle|c, t| |
147 | | -|13 |Twinkle It Colorful |Pixels can twinkle in different colors|t| |
148 | | -|14 |The Sparkle Pixels |What a sparkle Pixel|c, t| |
149 | | -|15 |Snow Sparkling |Feeling like snowin|c, t| |
150 | | -|16 |Pixel Runner |They are running very fast|c, t| |
151 | | -|17 |Theater Chase Pixels |Maybe Pixels visited a Theater|c, t| |
152 | | -|18 |Bouncing Pixels |And they bounce to center and back|c, t, n| |
153 | | -|19 |tbd | | | |
154 | | - |
155 | | -#### Modes |
156 | | - |
157 | | -|Index |Name |Decription |Config | |
158 | | -|---------|---------|---------|---------| |
159 | | -|-1 |Initial |No Mode active| | |
160 | | -|0 |Shine It|Normal light Pixel mode|c| |
161 | | -|1 |Chill Mode|Chillin with the Pixels|| |
162 | | -|2 |Color Theme|Use your custom color Pixel theme|c| |
163 | | -|2 |No Effect|Nope, not today|| |
164 | | -|3 |tbd||| |
165 | | - |
166 | | -### Add your own Effects and Modes |
167 | | - |
168 | | -You are able to add your own effects and modes to the PixLeZ-Package. Feel free to share your code with me and I will extend the PixLeZ-Package with your features. |
169 | | - |
170 | | -Add your code in `Blink.py` under the last effect or mode, depending on your purpose. Just add an further `if-condition` with an unique `index`. |
171 | | -Use the [adafruit-ws2801 API](https://github.com/adafruit/Adafruit_Python_WS2801/blob/master/Adafruit_WS2801/WS2801.py) to expand the code. |
172 | | - |
173 | | -```python |
174 | | -if self.effect == [unique effect Number]: |
175 | | - # insert your code here |
176 | | -if self.mode == [unique mode Numer]: |
177 | | - # insert your code here |
178 | | -``` |
179 | | - |
180 | | -After adding, you are able to call the effects and modes with an simple flask API call or an application. |
181 | | - |
182 | | -You are not able to select your added effects and modes with the PixLeZ-Application. For this purpose expand the further code by your own or send me your effects and modes and i will expand it. |
183 | | - |
184 | | -### Example: Use the API |
185 | | - |
186 | | -How to start an effect and manipulate it. If u use an application do the same steps but without the API calls. |
187 | | - |
188 | | -1. Select a color or color theme with `/set/color/<string:color>` or `/set/pixels` |
189 | | -1. Select your effect with `/select/effect/1` |
190 | | -1. Use `/start` to start the application |
191 | | -1. You can manipulate the effect with setting different attributes during runtime. As example `/set/color/AA0011` or `/set/time/0.001` |
192 | | -1. Select an other effect during runtime with `/select/effect/16` |
193 | | - |
194 | | -## PixLeZ-Desktop |
195 | | - |
196 | | -> Path: `./PixLeZ_Desktop` |
197 | | -
|
198 | | -PixLeZ-Desktop is developed for easy controlling the pixels via windows desktop. It is developed in `C#` with Visual Studio. The main use of this programm is to debug and test the application. |
199 | | - |
200 | | -Use PixLeZ-Application developed with `flutter` instead of PixLeZ_Desktop for a better user experience. |
201 | | - |
202 | | -## PixLeZ-Application |
203 | | - |
204 | | -> Path: `./PixLeZ_Application` |
205 | | -
|
206 | | -The PixLeZ-Application is the main part of the project. The application provides a lot of possibilities for configuration the Pixels. |
207 | | - |
208 | | -The PixLeZ-Application is made with `flutter`. Flutters advantage is in running code on every platform. For more information check the [Flutter](https://flutter.dev/) webpage. |
209 | | - |
210 | | -You have two options to run the PixLeZ-Application |
211 | | - |
212 | | -1. Set up a [Flutter environment](https://flutter.dev/docs/get-started/install) and compile it on your specific platform (Web, Android, IOS, Mac, Win,...) |
213 | | -2. Download the predefined installation packages and install it on the specific platform |
214 | | - |
215 | | -## PixLeZ-Simulator |
216 | | - |
217 | | -> Path: `./PixLeZ_Simulator` |
218 | | -
|
219 | | -The PixLeZ-Simulator is developed for simulating, debuging and testing your program without using hardware. It is using the same [API](https://github.com/adafruit/Adafruit_Python_WS2801/blob/master/Adafruit_WS2801/WS2801.py) for manipulating the pixels, so it is possible to copy and paste the code between the simulator and the hardware without changing too much. |
220 | | - |
221 | | -For more Information please check the Simulator `Readme.md` in `./PixLeZ_Simulator/Readme.md`. |
222 | | - |
223 | | -## About |
224 | | - |
225 | | -PixLeZ is created by Tobias Schreiweis in 2020. |
226 | | - |
227 | | -It started as a private project with the main focus to improve my python skills with the Raspberry Pi and learning new programing languages like dart with the framework flutter. After some request from other peoples getting the application I decided to publish it on GitHub. |
228 | | - |
229 | | -You are welcome to extend the PixLeZ-Bundle or send me your ideas and I would be glad about adding your code and ideas to this repository. |
230 | | - |
231 | | -If I can be of assistance, please do not hesitate to contact me. |
232 | | - |
233 | | -[](https://github.com/Excyto) |
234 | | - |
235 | | -## Links |
236 | | - |
237 | | -- [Raspberry Pi Tutorial Setup (ger)](https://tutorials-raspberrypi.de/raspberry-pi-ws2801-rgb-led-streifen-anschliessen-steuern/) |
238 | | -- [Raspberry Pi Tutorial Setup (en)](https://tutorials-raspberrypi.com/how-to-control-a-raspberry-pi-ws2801-rgb-led-strip/) |
239 | | -- [Adafruit_WS2801 Library GitHub](https://github.com/adafruit/Adafruit_Python_WS2801/blob/master/Adafruit_WS2801/WS2801.py) |
240 | | -- [Inspiration of some Arduino LED effects](https://www.tweaking4all.com/hardware/arduino/adruino-led-strip-effects/) |
241 | | -- [Flask Framework](https://flask.palletsprojects.com/en/1.1.x/) |
242 | | -- [Tkinter Framework](https://realpython.com/python-gui-tkinter/) |
243 | | -- [Flutter](https://flutter.dev/) |
| 26 | +## Additional help |
| 27 | +If you have any questions or need additional help, feel free to create an [issue](https://github.com/Excyto/PixLeZ/issues) or contact one of the contributors. We will be happy to help you! |
0 commit comments