mirror of
https://github.com/Hopiu/rpi-rgb-led-matrix.git
synced 2026-03-16 22:10:27 +00:00
o Update documentation.
This commit is contained in:
Henner Zeller
parent
4bf0bf2811
commit
16b63b92c5
5 changed files with 318 additions and 161 deletions
284
README.md
284
README.md
|
|
@ -18,6 +18,16 @@ The LED-matrix library is (c) Henner Zeller <h.zeller@acm.org>, licensed with
|
|||
source and all your modifications available to the receiver of such product so
|
||||
that they have the freedom to adapt and improve).
|
||||
|
||||
Note to Old Time Users: Several changes in defines and flags
|
||||
------------------------------------------------------------
|
||||
If you have checked out this library before, you might find that some
|
||||
files are re-organized in different directories (e.g. there is now a separation
|
||||
for library examples and utilities), and that the flags to binaries are now
|
||||
long and unified. Also, for the most part, you don't need to tweak paramters
|
||||
in `lib/Makefile` anymore as they are now exposed via command line flags.
|
||||
|
||||
Choosing a different pinout, e.g. for the Adafruit HAT is also a little different.
|
||||
|
||||
Overview
|
||||
--------
|
||||
The 32x32 or 16x32 RGB LED matrix panels can be scored at [Sparkfun][sparkfun],
|
||||
|
|
@ -71,20 +81,33 @@ Let's do it
|
|||
------------
|
||||
This documentation is split into parts that help you through the process
|
||||
|
||||
1. [Wire up the matrix to your Pi](./wiring.md). This document describes what
|
||||
goes where. You might also be interested in [breakout boards](./adapter)
|
||||
for that. If you have an [Adafruit HAT], necessary steps are
|
||||
[described below](#if-you-have-an-adafruit-hat)
|
||||
2. Run a demo. You find that in the
|
||||
[examples-api-use/](./examples-api-use#running-some-demos) directory.
|
||||
3. Use the utilities. The [utils](./utils) directory has some ready-made
|
||||
useful utilities to show image or text.
|
||||
* <a href="wiring.md"><img src="img/wire-up-icon.png"></a>
|
||||
[Wire up the matrix to your Pi](./wiring.md). This document describes what
|
||||
goes where. You might also be interested in [breakout boards](./adapter)
|
||||
for that. If you have an [Adafruit HAT], necessary steps are
|
||||
[described below](#if-you-have-an-adafruit-hat)
|
||||
* Run a demo. You find that in the
|
||||
[examples-api-use/](./examples-api-use#running-some-demos) directory:
|
||||
```
|
||||
make -C examples-api-use
|
||||
sudo examples-api-use/demo -D0
|
||||
```
|
||||
* Use the utilities. The [utils](./utils) directory has some ready-made
|
||||
useful utilities to show image or text. [Go there](./utils) to see how to
|
||||
compile and run these.
|
||||
|
||||
### Utilities
|
||||
|
||||
There are a couple of ready utilities to show images, text and video in
|
||||
the [utils directory](./utils). Read the [README](./utils/README.md) there
|
||||
for instructions how to compile
|
||||
The [utils directory](./utils) is meant for ready utilities to show images,
|
||||
animated gifs, text and video. Read the [README](./utils/README.md) there
|
||||
for instructions how to compile.
|
||||
|
||||
There are external projects that use this library and provide higher level
|
||||
network protocols, such as the
|
||||
[FlaschenTaschen implementation](https://github.com/hzeller/flaschen-taschen)
|
||||
(VLC can send videos to it natively) or the
|
||||
[PixelPusher implementation](https://github.com/hzeller/rpi-matrix-pixelpusher)
|
||||
(common in light art installations).
|
||||
|
||||
### API
|
||||
|
||||
|
|
@ -97,22 +120,163 @@ The library comes as an API that you can use for your own utilities and use-case
|
|||
[C API](./include/led-matrix-c.h).
|
||||
* In the [python](./python) subdirectory, you find a Python API including a
|
||||
couple of [examples](./python/samples) to get started.
|
||||
* There are a couple of external bindings, such as this [Nodejs binding]
|
||||
by Maxime Journaux.
|
||||
|
||||
Chaining panels
|
||||
---------------
|
||||
### Changing parameters via command-line flags
|
||||
|
||||
We might only have a limited amount of GPIOs on the Raspberry Pi, but luckily,
|
||||
the RGB matrices can be chained. The display panels have an input connector,
|
||||
and also have an output port, that you can connect to the next display in a
|
||||
daisy-chain manner. There is the flag `--led-chain` in the demo program to give number
|
||||
of displays that are chained.
|
||||
You end up with a very wide display (chain * 32 pixels).
|
||||
For the programs in this distribution and also automatically in your own
|
||||
programs using this library, there are a lot of parameters provided as command
|
||||
line flags, so that you don't have to re-compile your programs to tweak them.
|
||||
Some might need to be changed for your particular kind of panel.
|
||||
|
||||
The [wiring.md](./wiring.md#chaining-parallel-chains-and-coordinate-system)
|
||||
document explains the details.
|
||||
Here is a little run-down of what these command-line flags do and when you'd
|
||||
like to change them.
|
||||
|
||||
```
|
||||
# These are the most important
|
||||
--led-rows=<rows> : Panel rows. 8, 16, 32 or 64. (Default: 32).
|
||||
--led-chain=<chained> : Number of daisy-chained panels. (Default: 1).
|
||||
--led-parallel=<parallel> : For A/B+ models or RPi2,3b: parallel chains. range=1..3 (Default: 1).
|
||||
```
|
||||
|
||||
These are the most important ones: here you choose how many panels you have
|
||||
connected and how many rows are in each panel. Panels can be chained (each panel
|
||||
has an input and output connector, see the
|
||||
[wiring documentation](wiring.md#chains)) -- the `--led-chain` flag tells the
|
||||
library how many panels are chained together. The newer Raspberry Pi's allow
|
||||
to connect multiple chains in parallel, the `--led-parallel` flag tells it how
|
||||
many there are.
|
||||
|
||||
This illustrates what each of these parameters mean:
|
||||
|
||||
<a href="wiring.md#chaining-parallel-chains-and-coordinate-system"><img src="img/coordinates.png"></a>
|
||||
<a href="adapter/"><img src="img/three-parallel-panels-soic.jpg" width="300px"></a>
|
||||
|
||||
```
|
||||
--led-brightness=<percent>: Brightness in percent (Default: 100).
|
||||
```
|
||||
|
||||
Self explanatory.
|
||||
|
||||
|
||||
```
|
||||
--led-pwm-bits=<1..11> : PWM bits (Default: 11).
|
||||
```
|
||||
|
||||
The LEDs can only be switched on or off, so the shaded brightness perception
|
||||
is achieved via PWM (Pulse Width Modulation). In order to get a good 8 Bit
|
||||
per color resolution (24Bit RGB), the 11 bits default per color are good
|
||||
(why ? Because our eyes are actually perceiving brightness logarithmically, so
|
||||
we need a lot more physical resolution to get 24Bit sRGB).
|
||||
|
||||
With this flag, you can change how many bits it should use for this; lowering it
|
||||
means the lower bits (=more subtle color nuances) are omitted.
|
||||
Typically you might be mostly interested in the extremes: 1 Bit for situations
|
||||
that only require 8 colors (e.g. for high contrast text displays) or 11 Bit
|
||||
for everything else (e.g. showing images or videos). Why would you bother at all ?
|
||||
Lower number of bits use slightly less CPU and result in a higher refresh rate.
|
||||
|
||||
```
|
||||
--led-show-refresh : Show refresh rate.
|
||||
```
|
||||
|
||||
This shows the current refresh rate of the LED panel, the time to refresh
|
||||
a full picture. Typically, you want this number to be pretty high, because the
|
||||
human eye is pretty sensitive to flicker. Depending on the settings, the
|
||||
refresh rate with this library are typically in the hundreds of Hertz but
|
||||
can drop low with very long chains. Humans have different levels of perceiving
|
||||
flicker - some are fine with 100Hz refresh, others need 250Hz.
|
||||
So if you are curious, this gives you the number (shown on the terminal).
|
||||
|
||||
The refresh rate depends on a lot of factors, from `--led-rows` and `--led-chain`
|
||||
to `--led-pwm-bits` and `--led-pwm-lsb-nanoseconds`. If you are tweaking these
|
||||
parameters, showing the refresh rate can be a useful tool.
|
||||
|
||||
```
|
||||
--led-scan-mode=<0..1> : 0 = progressive; 1 = interlaced (Default: 0).
|
||||
```
|
||||
|
||||
This switches from progressive scan and interlaced scan. The latter might
|
||||
look be a little nicer when you have a very low refresh rate.
|
||||
|
||||
```
|
||||
--led-pwm-lsb-nanoseconds : PWM Nanoseconds for LSB (Default: 130)
|
||||
```
|
||||
|
||||
This allows to change the base time-unit for the on-time in the lowest
|
||||
significant bit in nanoseconds.
|
||||
Lower values will allow higher frame-rate, but will also negatively impact
|
||||
qualty in some panels (less accurate color or more ghosting).
|
||||
|
||||
Good values for full-color display (PWM=11) are somewhere between 100 and 300.
|
||||
|
||||
If you you use reduced bit color (e.g. PWM=1) and have sharp contrast
|
||||
applications, then higher values might be good to minimize ghosting.
|
||||
|
||||
How to decide ? Just leave the default if things are fine. But some panels have
|
||||
trouble with sharp contrasts and short pulses that results
|
||||
in ghosting. It is particularly apparent in situations such as bright text
|
||||
on black background. In these cases increase the value until you don't see
|
||||
this ghosting anymore.
|
||||
|
||||
The following example shows how this might look like:
|
||||
|
||||
Ghosting with low --led-pwm-lsb-nanoseconds | No ghosting after tweaking
|
||||
---------------------------------------------|------------------------------
|
||||
 |
|
||||
|
||||
If you tweak this value, watch the framerate (`--led-show-refresh`) while playing
|
||||
with this number.
|
||||
|
||||
```
|
||||
--led-slowdown-gpio=<0..2>: Slowdown GPIO. Needed for faster Pis and/or slower panels (Default: 1).
|
||||
```
|
||||
|
||||
The Raspberry Pi 2 and 3 are putting out data too fast for almost all LED panels
|
||||
I have seen. In this case, you want to slow down writing to GPIO. Zero for this
|
||||
parameter means 'no slowdown'.
|
||||
|
||||
The default 1 (one) typically works fine, but often you have to even go further
|
||||
by setting it to 2 (two). If you have a Raspberry Pi with a slower processor
|
||||
(Model A, A+, B+, Zero), then a value of 0 (zero) might work and is desirable.
|
||||
|
||||
```
|
||||
--led-no-hardware-pulse : Don't use hardware pin-pulse generation.
|
||||
```
|
||||
|
||||
This library uses a hardware subsystem that also is used by the sound. You can't
|
||||
use them together. If your panel does not work, this might be a good start
|
||||
to debug if it has something to do with the sound subsystem (see Troubleshooting
|
||||
section). This is really only recommended for debugging; typically you actually
|
||||
want the hardware pulses as it results in a much more stable picture.
|
||||
|
||||
```
|
||||
--led-no-drop-privs : Don't drop privileges from 'root' after initializing the hardware.
|
||||
```
|
||||
|
||||
You need to start programs as root as it needs to access some low-level hardware
|
||||
at initialization time. After that, it is typically not desirable to stay in this
|
||||
role, so the library then drops the privileges.
|
||||
|
||||
This flag allows to switch off this behavior, so that you stay root.
|
||||
Not recommended unless you have a specific reason for it.
|
||||
|
||||
```
|
||||
--led-daemon : Make the process run in the background as daemon.
|
||||
```
|
||||
|
||||
If this is set, the program puts itself into the background (running
|
||||
as 'daemon').
|
||||
You might want this if started from an init script at boot-time.
|
||||
|
||||
```
|
||||
--led-inverse : Switch if your matrix has inverse colors on.
|
||||
--led-swap-green-blue : Switch if your matrix has green/blue swapped on.
|
||||
```
|
||||
|
||||
These are if you have a different kind of LED panel in which the logic of the
|
||||
color bits is reversed (`--led-inverse`) or where the green and blue colors
|
||||
are swapped (`--led-swap-green-blue`). You know it when you see it.
|
||||
|
||||
Troubleshooting
|
||||
---------------
|
||||
|
|
@ -130,8 +294,12 @@ distribution.
|
|||
|
||||
### Bad interaction with Sound
|
||||
If sound is enabled on your Pi, this will not work together with the LED matrix,
|
||||
as both need the same internal hardware sub-system. So if you run `lsmod` and
|
||||
see any modules show up with `snd` in their name, this could be causing trouble.
|
||||
as both need the same internal hardware sub-system (a first test to see if you
|
||||
are affected is to run the progrem with `--led-no-hardware-pulse` and see if
|
||||
things work fine then).
|
||||
|
||||
If you run `lsmod` and see any modules show up with `snd` in their name,
|
||||
this could be causing trouble.
|
||||
|
||||
In that case, you should create a kernel module blacklist file like the
|
||||
following on your system and update your initramfs:
|
||||
|
|
@ -179,58 +347,13 @@ If you encounter this, try these things
|
|||
For GPIO slow-down, add the flag `--led-slowdown-gpio=2` to the invocation of
|
||||
the binary.
|
||||
|
||||
The default value is 1, if you still have problems, try the value 2. If you
|
||||
know that your display is fast enough, use 0 (zero).
|
||||
|
||||
Then `make` again.
|
||||
|
||||
### Ghosting
|
||||
Some panels have trouble with sharp contrasts and short pulses that results
|
||||
in ghosting. It is particularly apparent with very sharp contrasts, such as
|
||||
bright text on black background. This can be improved by tweaking the
|
||||
`--led-pwm-lsb-nanoseconds` parameter.
|
||||
|
||||
The following example is a little exaggerated:
|
||||
|
||||
Ghosting with low --led-pwm-lsb-nanoseconds | No ghosting after tweaking
|
||||
---------------------------------------------|------------------------------
|
||||
 |
|
||||
|
||||
### Inverted Colors ?
|
||||
|
||||
There are some displays out there that use inverse logic for the colors. You
|
||||
notice that your image looks like a 'negative'. The parameter to tweak is
|
||||
`--led-inverse`.
|
||||
|
||||
### Check configuration via command line flags.
|
||||
|
||||
There are lots of parameters exposed as command line flags.
|
||||
```
|
||||
# These are the most important
|
||||
--led-rows=<rows> : Panel rows. 8, 16, 32 or 64. (Default: 32).
|
||||
--led-chain=<chained> : Number of daisy-chained panels. (Default: 1).
|
||||
--led-parallel=<parallel> : For A/B+ models or RPi2,3b: parallel chains. range=1..3 (Default: 1).
|
||||
|
||||
# These are for tweaking
|
||||
--led-pwm-bits=<1..11> : PWM bits (Default: 11).
|
||||
--led-brightness=<percent>: Brightness in percent (Default: 100).
|
||||
--led-scan-mode=<0..1> : 0 = progressive; 1 = interlaced (Default: 0).
|
||||
--led-show-refresh : Show refresh rate.
|
||||
--led-inverse : Switch if your matrix has inverse colors on.
|
||||
--led-swap-green-blue : Switch if your matrix has green/blue swapped on.
|
||||
--led-pwm-lsb-nanoseconds : PWM Nanoseconds for LSB (Default: 130)
|
||||
--led-no-hardware-pulse : Don't use hardware pin-pulse generation.
|
||||
--led-slowdown-gpio=<0..2>: Slowdown GPIO. Needed for faster Pis and/or slower panels (Default: 1).
|
||||
--led-daemon : Make the process run in the background as daemon.
|
||||
--led-no-drop-privs : Don't drop privileges from 'root' after initializing the hardware.
|
||||
```
|
||||
|
||||
If you have an Adafruit HAT
|
||||
---------------------------
|
||||
|
||||
Generally, if you want to connect RGB panels via an adapter instead of
|
||||
hand-wiring, I suggest to build one of the adapters whose open-hardware
|
||||
files you find in the [adapter/](./adapter) subdirectory.
|
||||
files you find in the [adapter/](./adapter) subdirectory. It is a fun solder
|
||||
exercise with large surface mount components.
|
||||
|
||||
However, Adafruit [offers an adapter][adafruit-hat] which is already ready-made,
|
||||
but it only allows for a single chain. If the
|
||||
|
|
@ -239,9 +362,10 @@ ready-made vs. single-chain tradeoff is worthwhile, then you might go for that
|
|||
|
||||
### Switch the Pinout
|
||||
|
||||
The Adafruit HAT uses a modified pinout, so they forked this library and
|
||||
modified the pinout there. However, that fork is _ancient_, so I strongly
|
||||
suggest to use this original library instead.
|
||||
The Adafruit HAT uses this library but a modified pinout to support other
|
||||
features on the HAT. So they forked this library and modified the pinout there.
|
||||
However, that fork is _ancient_, so I strongly suggest to use this original
|
||||
library instead - which in the meantime also has a way to switch to their pinout.
|
||||
|
||||
In this library here, you can choose the Adafruit HAT pinout by editing
|
||||
`lib/Makefile` and change `HARDWARE_DESC?=regular` to `HARDWARE_DESC=adafruit-hat`.
|
||||
|
|
@ -266,7 +390,8 @@ Then, uncomment the following line in the Makefile and recompile.
|
|||
#DEFINES+=-DADAFRUIT_RGBMATRIX_HAT_PWM
|
||||
```
|
||||
|
||||
Reboot the Pi and you now should have less visible flicker.
|
||||
Reboot the Pi and you now should have less visible flicker. This essentially
|
||||
gives you the hardware pulses feature.
|
||||
|
||||
### 64x64 with E-line on Adafruit HAT
|
||||
There is another hardware mod needed for 1:32 multiplexing 64x64
|
||||
|
|
@ -303,7 +428,7 @@ thus the constant CPU use on an RPi is roughly 30-40% of one core.
|
|||
Keep that in mind if you plan to run other things on this computer (This
|
||||
is less noticable on Raspberry Pi, Version 2 or 3 that has more cores).
|
||||
|
||||
Also, the output quality is suceptible to other heavy tasks running on that
|
||||
Also, the output quality is susceptible to other heavy tasks running on that
|
||||
computer - there might be changes in the overall brigthness when this affects
|
||||
the referesh rate.
|
||||
|
||||
|
|
@ -320,10 +445,10 @@ utilize it then. Still, I'd typically recommend it.
|
|||
|
||||
Limitations
|
||||
-----------
|
||||
If you are using the RGB_CLASSIC_PINOUT, or Adafruit Hat in the default
|
||||
configuration, then we can't make use of the PWM hardware (which only outputs
|
||||
If you are using the Adafruit Hat in the default configuration, then we
|
||||
can't make use of the PWM hardware (which only outputs
|
||||
to a particular pin), so you'll see random brightness glitches. I strongly
|
||||
suggest to change the pinout.
|
||||
suggest to do the aforementioned hardware mod.
|
||||
|
||||
The system needs constant CPU to update the display. Using the DMA controller
|
||||
was considered but after extensive experiments
|
||||
|
|
@ -347,3 +472,4 @@ things, like this installation by Dirk in Scharbeutz, Germany:
|
|||
[adafruit-hat]: https://www.adafruit.com/products/2345
|
||||
[raspbian-lite]: https://downloads.raspberrypi.org/raspbian_lite_latest
|
||||
[Adafruit HAT]: https://www.adafruit.com/products/2345
|
||||
[Nodejs binding]: https://github.com/zeitungen/node-rpi-rgb-led-matrix
|
||||
|
|
|
|||
|
|
@ -1,11 +1,15 @@
|
|||
Running some demos
|
||||
------------------
|
||||
The demo-main.cc has some testing demos. Via command line flags, you can choose
|
||||
the display type you have (16x32 or 32x32), and how many you have chained.
|
||||
Let's start by running some demos, then we can dive into code. The
|
||||
[demo-main.cc](demo-main.cc) has some testing demos. Via command line flags,
|
||||
you can choose the display type you have (16x32 or 32x32), and how many you
|
||||
have chained and paralleled. For detailed description of these flags see the
|
||||
[main README section](../README.md#changing-parameters-via-command-line-flags)
|
||||
about it.
|
||||
|
||||
```
|
||||
$ make
|
||||
$ ./demo
|
||||
$ sudo ./demo
|
||||
usage: ./demo <options> -D <demo-nr> [optional parameter]
|
||||
Options:
|
||||
-D <demo-nr> : Always needs to be set
|
||||
|
|
@ -44,10 +48,11 @@ Scrolls the runtext for 10 seconds
|
|||
```
|
||||
|
||||
To run the actual demos, you need to run this as root so that the
|
||||
GPIO pins can be accessed.
|
||||
GPIO pins can be accessed; as soon as that established, the program will drop
|
||||
the privileges.
|
||||
|
||||
The most interesting one is probably the demo '1' which requires a ppm (type
|
||||
raw) with a height of 32 pixel - it is infinitely scrolled over the screen; for
|
||||
Here is how demo '1' looks. It requires a ppm (type raw) with a height of
|
||||
32 pixel - it is infinitely scrolled over the screen; for
|
||||
convenience, there is a little runtext.ppm example included:
|
||||
|
||||
$ sudo ./demo -D 1 runtext.ppm
|
||||
|
|
@ -55,31 +60,77 @@ convenience, there is a little runtext.ppm example included:
|
|||
Here is a video of how it looks
|
||||
[![Runtext][run-vid]](http://youtu.be/OJvEWyvO4ro)
|
||||
|
||||
There are also two examples [minimal-example.cc](./minimal-example.cc) and
|
||||
[text-example.cc](./text-example.cc) that show use of the API.
|
||||
|
||||
The text example allows for some interactive output of text (using a bitmap-font
|
||||
found in the `fonts/` directory). Even though it is just an example, it can
|
||||
be useful in its own right. For instance, you can connect to its input with a
|
||||
pipe and simply feed text from a shell-script or other program that wants to
|
||||
output something. Let's display the time in blue:
|
||||
|
||||
(while :; do date +%T ; sleep 0.2 ; done) | sudo ./text-example -f ../fonts/8x13B.bdf -y8 -c2 -C0,0,255
|
||||
|
||||
You could connect this via a pipe to any process that just outputs new
|
||||
information on standard-output every now and then. The screen is filled with
|
||||
text until it overflows which then clears it. Or sending an empty line explicitly
|
||||
clears the screen (if you want to display an empty line, just send a space).
|
||||
|
||||
![Time][time]
|
||||
|
||||
Using the API
|
||||
-------------
|
||||
While there is the demo program, the matrix code can be used independently as
|
||||
a library. The includes are in `include/`, the library to link is built
|
||||
in `lib/`. So if you are proficient in C++, then use it in your code.
|
||||
While there is the demo program and the [utilities](../utils), this code can
|
||||
be used independently as a library to be used in your own programs.
|
||||
The includes are in `include/`, the library to link is built
|
||||
in `lib/`. This is a C++ also with C bindings. There is also a
|
||||
[Python](../python) binding.
|
||||
|
||||
Getting started
|
||||
---------------
|
||||
The relevant part to start with is to look at
|
||||
[led-matrix.h](../include/led-matrix.h).
|
||||
|
||||
You can would typically use the `CreateMatrixFromFlags()` factory to
|
||||
create an RGBMatrix and then go from there.
|
||||
|
||||
```C++
|
||||
#include "led-matrix.h"
|
||||
|
||||
using rgb_matrix::RGBMatrix;
|
||||
|
||||
int main(int argc, char **argv) {
|
||||
// Set some defaults
|
||||
RGBMatrix::Options my_defaults;
|
||||
my_defaults.chain_length = 3;
|
||||
my_defaults.show_refresh_rate = true;
|
||||
rgb_matrix::RuntimeOptions runtime_defaults;
|
||||
runtime_defaults.drop_privileges = 1;
|
||||
RGBMatrix *matrix = rgb_matrix::CreateMatrixFromFlags(&argc, &argv,
|
||||
&my_defaults,
|
||||
&runtime_defaults);
|
||||
if (matrix == NULL) {
|
||||
PrintMatrixFlags(stderr, my_defaults, runtime_defaults);
|
||||
return 1;
|
||||
}
|
||||
|
||||
// Do your own command line handling with the remaining options.
|
||||
|
||||
// .. now use matrix
|
||||
|
||||
delete matrix; // Make sure to delete it in the end.
|
||||
}
|
||||
```
|
||||
|
||||
The `RGBMatrix` is essentially a canvas, it provides some basic functionality
|
||||
such as `SetPixel()`, `Fill()` or `Clear()`. If you want to do more, you
|
||||
might be interested in functions provided in the
|
||||
[graphics.h](../include/graphics.h) header.
|
||||
|
||||
If you have animations, you might be interested in double-buffering. There is
|
||||
a way to create new canvases with `CreateFrameCanvas()`, and then use
|
||||
`SwapOnVSync()` to change the content atomically. See API documentation for
|
||||
details.
|
||||
|
||||
Start with the [minimal-example.cc](./minimal-example.cc) to start.
|
||||
|
||||
If you are interested in drawing text and the font drawing functions in
|
||||
graphics.h, have a look at the [text example](./text-example.cc):
|
||||
|
||||
```
|
||||
sudo ./text-example -f ../fonts/8x13.bdf
|
||||
hello
|
||||
```
|
||||
|
||||
<img src="../img/text-no-ghosting.jpg" height="100px">
|
||||
|
||||
Integrating in your own application
|
||||
-----------------------------------
|
||||
Until this library shows up in your favorite Linux distribution, you can just
|
||||
include the library via github; it is pretty easy to be up-to-date.
|
||||
|
||||
Due to the wonders of github, it is pretty easy to be up-to-date.
|
||||
I suggest to add this code as a sub-module in your git repository. That way
|
||||
you can use that particular version and easily update it if there are changes:
|
||||
|
||||
|
|
|
|||
|
|
@ -240,6 +240,10 @@ RGBMatrix *CreateMatrixFromFlags(int *argc, char ***argv,
|
|||
const bool allow_daemon = !(ropt->daemon < 0);
|
||||
result->SetGPIO(&io, allow_daemon);
|
||||
|
||||
// TODO(hzeller): if we disallow daemon, then we might also disallow
|
||||
// drop privileges: we can't drop privileges until we have created the
|
||||
// realtime thread that usually requires root to be established.
|
||||
// Double check and document.
|
||||
if (ropt->drop_privileges > 0) {
|
||||
drop_privs("daemon", "daemon");
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,17 +1,24 @@
|
|||
Utilities
|
||||
=========
|
||||
|
||||
This contains useful utilities that might be directly useful without having
|
||||
to write any code.
|
||||
|
||||
### Image Viewer ###
|
||||
|
||||
The image viewer reads all kinds of image formats, including animated gifs.
|
||||
It is not compiled by default, as you need to install the GraphicsMagick
|
||||
dependencies first:
|
||||
To compile, you first need to install the GraphicsMagick dependencies first:
|
||||
|
||||
sudo apt-get update
|
||||
sudo apt-get install libgraphicsmagick++-dev libwebp-dev
|
||||
make led-image-viewer
|
||||
```
|
||||
sudo apt-get update
|
||||
sudo apt-get install libgraphicsmagick++-dev libwebp-dev -y
|
||||
make led-image-viewer
|
||||
```
|
||||
|
||||
Then, you can run it with any common image format, including animated gifs:
|
||||
|
||||
sudo ./led-image-viewer myimage.gif
|
||||
|
||||
It also supports the standard options to specify the connected
|
||||
displays (e.g. `--led-rows`, `--led-chain`, `--led-parallel` but also many more tweak
|
||||
flags).
|
||||
displays (e.g. `--led-rows`, `--led-chain`, `--led-parallel` but also
|
||||
[many more tweak flags](../README.md#changing-parameters-via-command-line-flags).
|
||||
|
|
|
|||
61
wiring.md
61
wiring.md
|
|
@ -35,7 +35,7 @@ side of the connector:
|
|||
|
||||
The RPi only has 3.3V logic output level, but many displays operated at 5V
|
||||
interprets these logic levels fine, just make sure to run a short
|
||||
cable to the board (if you see problems, see [troubleshouting paragraph](#troubleshooting)).
|
||||
cable to the board.
|
||||
If you do run into glitches or erratic pixels, consider some line-buffering,
|
||||
e.g. using the [active adapter PCB](./adapter/).
|
||||
Since we only need output pins on the RPi, we don't need to worry about level
|
||||
|
|
@ -97,62 +97,31 @@ Connection | Pin | Pin | Connection
|
|||
In the [adapter/](./adapter) directory, there are some boards that make
|
||||
the wiring task simpler.
|
||||
|
||||
Chaining, parallel chains and coordinate system
|
||||
------------------------------------------------
|
||||
<a href="adapter/"><img src="img/three-parallel-panels-soic.jpg" width="300px"></a>
|
||||
|
||||
Displays panels have an input connector, but also have an output port, that
|
||||
you can connect to the next display in a daisy-chain manner. There is the
|
||||
flag `-c` in the demo program to give number of displays that are chained.
|
||||
You end up with a very wide
|
||||
display (chain * 32 pixels). Longer chains affect the refresh rate negatively,
|
||||
so if you want to stay above 100Hz with full color, don't chain more than
|
||||
12 panels.
|
||||
If you use a PWM depth of 1 bit (`-p`), the chain can be much longer.
|
||||
### Chains
|
||||
|
||||
The original Raspberry Pis with 26 GPIO pins just had enough connector pins
|
||||
to drive one chain of LED panels. Newer Raspberry Pis have 40 GPIO pins that
|
||||
allows to add two additional chains of panels in parallel - the nice thing is,
|
||||
that this doesn't require more CPU and allows you to keep your refresh-rate high,
|
||||
because you can shorten your chains.
|
||||
|
||||
So with that, we have a couple of parameters to keep track of. The **rows** are
|
||||
the number of LED rows on a particular module; typically these are 16 for a 16x32
|
||||
display or 32 for 32x32 displays.
|
||||
|
||||
Then there is the **chain length**, which is the number of panels that are
|
||||
daisy chained together.
|
||||
|
||||
Finally, there is a parameter how many **parallel** chains we have connected to
|
||||
the Pi -- limited to 1 on old Raspberry Pis, up to three on newer Raspberry Pis.
|
||||
|
||||
For a single Panel, the chain and parallel parameters are both just one: a single
|
||||
chain (with no else in parallel) with a chain length of 1.
|
||||
|
||||
The `RGBMatrix` class constructor has parameters for number of rows,
|
||||
chain-length and number of parallel. For the demo programs and the image view,
|
||||
there are command line options for that: `-r` gives rows,
|
||||
`-c` the chain-length and `-P` the number of parallel chains.
|
||||
|
||||
The coordinate system starts at (0,0) at the top of the first parallel chain,
|
||||
furthest away from the Pi. The following picture gives an overview of various
|
||||
parameters and the coordinate system.
|
||||
You connect the Pi to the first element in the chain of panels. Each panel has
|
||||
an output connector, that you then can connect to the next panel. Thus you can
|
||||
create a larger panel. Here a schematic view, below in the 'Power' section, you
|
||||
can see a real-live panel with three chains of 5 panels each seen from the back.
|
||||
|
||||
![Coordinate overview][coordinates]
|
||||
|
||||
<a href="adapter/"><img src="img/three-parallel-panels-soic.jpg" width="300px"></a>
|
||||
|
||||
A word about power
|
||||
------------------
|
||||
|
||||
These displays suck a lot of current. At 5V, when all LEDs are on (full white),
|
||||
my LED panel draws about 3.4A. That means, you need a beefy power supply to
|
||||
drive these panels; a 2A USB charger or similar is not enough for a
|
||||
32x32 panel; it might be for a 16x32.
|
||||
my 32x32 LED panel draws about 3.4A. For an outdoor panel that is very bright,
|
||||
that can be twice as much.
|
||||
That means, you need a beefy power supply to drive these panels; a 2A USB
|
||||
charger or similar is not enough for a 32x32 panel; it might be for a 16x32.
|
||||
|
||||
If you connect multiple boards together, you needs a power supply that can
|
||||
keep up with 3.5A / panel. Good are old PC power supplies that often
|
||||
provide > 20A on the 5V rail. Also you can get dedicated 5V high current
|
||||
switching power supplies for these kind of applications (check eBay).
|
||||
provide > 20A on the 5V rail. Or you can get a dedicated 5V high current
|
||||
switching power supply for these kind of applications (check eBay).
|
||||
|
||||
The current draw is pretty spiky. Due to the PWM of the LEDs, there are very
|
||||
short peaks of a couple of 100ns to about 1ms of full current draw.
|
||||
|
|
@ -162,7 +131,7 @@ as they should. A low ESR capacitor close to the input is good in these cases.
|
|||
|
||||
On some displays, the quality of the output quickly gets erratic
|
||||
when voltage drops below 4.5V. Some even need a little bit higher voltage around
|
||||
5.5V to work reliably.
|
||||
5.5V to work reliably. Also, tweak with the `--led-slowdown-gpio` flag.
|
||||
|
||||
When you connect these boards to a power source, the following are good
|
||||
guidelines:
|
||||
|
|
@ -200,7 +169,7 @@ guidelines:
|
|||
We want to get the energy out of the voltage drop of 50mV; so with
|
||||
W = 1/2*C*U², we can calculate the capacitance needed:
|
||||
C = 2 * 1.6mJoule / ((5V)² - (5V - 50mV)²) = ~6400µF.
|
||||
So, **2 x 3300µF** low-ESR capacitors in parallel directly
|
||||
So, 2 x 3300µF low-ESR capacitors in parallel directly
|
||||
at the board are a good choice (two, because lower parallel ESR; also
|
||||
fits easier under board).
|
||||
(In reality, we need of course less, as the highest ripple comes with
|
||||
|
|
|
|||
Loading…
Reference in a new issue