Skip to content

How to configure WS281XLEDs (Penny K Pinball)

Related Config File Sections:

Each PKONE Lightshow add-on board has a built-in 8-group RGB or RGBW LED controller (depending upon which firmware is loaded on the Lightshow) which can drive up to 64 RGB or RGBW LEDs per group (a total of up to 512 LEDs). This controller uses serially-controlled LEDs (where each LED element has a little serial protocol decoder chip in it), allowing you to drive dozens of LEDs from a single data wire. These LEDs are generally known as "WS2812" (or similar). You can buy them from many different companies, and they're what's sold as the "NeoPixel" brand of products from Adafruit. (They have all different shapes and sizes.)

image

Most of the settings in the Lights documentation apply to LEDs connected to PKONE Lightshow boards, however there are a few PKONE-specific things to know.

Overview video about serial LEDs:

Channel and Number Syntax

In MPF lights abstract a light source which emits arbitrary colors. However, this is not true for all real lights. Some support only white (GIs), others only a single-color (i.e. red inserts) and others support full RGB. For that reason MPF knows light numbers and channel numbers. Internally, a light consists of one or multiple channels. For instance, a single-color GI will contain a single white channel. While a RGB light will control a red, green and a blue channel. A white light behind a red insert should be a single red channel (because it cannot emit other colors through the red insert). You can configure those channels using the channels setting or use start_channel and type to define the channels. See /mechs/lights/index for details.

However, in most cases a platform supports one type of lights (per subtype) this would be overly verbose and we added the number setting for configuring lights in the common platform way. For instance a platform for GIs will configure single channel white lights or a serial LED controller will configure RGB lights with three channels.

PKONE assumes RGB or RGBW lights by default (depending upon which firmware your Lightshow board is running). For everything else (i.e. RGBW) you have to use channels.

The PKONE Lightshow supports 512 LEDs on eight groups (64 in each group).

Light Numbers

The number: setting for each LED is its board's Address ID number in the PKONE chain, a dash, the LED output group number (1-8), another dash, then finally the LED output number in the group chain (1-64) (address id-group-number). Internally, PKONE assumes three channels per LED (RGB/GRB) when running RGB firmware and four channels per LED (RGBW) when running RGBW firmware. While assigning numbers manually will work, it is recommended you use the newer chaining syntax referenced below in the Channels section.

Channels

PKONE channels use the format: address id-group-index

address id and group are the same as above and index is a an index from 0 to 191 for RGB firmware and 0 to 255 for RGBW firmware. The channel syntax makes it easy to mix LEDs of various types in the same group chain (as long as they are WS281X compatible). The easiest, and recommended, method of numbering is to chain the LEDs in your configuration file and have MPF calculate the internal channel numbers for you (please note the type setting is required when using start_channel/previous settings):

lights:
  led_0:
    start_channel: 0-1-0
    subtype: led
    type: rgb    # will use red: 0-1-0, green: 0-1-1, blue: 0-1-2
  led_1:
    previous: led_0
    subtype: led
    type: rgbw   # will use red: 0-1-3, green: 0-1-4, blue: 0-1-5, white: 0-1-6
  led_2:
    previous: led_1
    subtype: led
    type: rgbw   # will use red: 0-1-7, green: 0-1-8, blue: 0-1-9, white: 0-1-10

This method of chaining your LEDs works exactly the same way whether your Lightshow board is running RGB or RGBW firmware.

See WS2811 and WS2812 LEDs in Pinball for additional details.

Color Correction

If you are using RGB LEDs, they might not be perfectly white when you turn them on. They might be pinkish or blueish instead depending on the brand of the LED. To a certain extend this is normal/expected and you can compensate for it by configuring color_correction profiles in light_settings.

subtype:

Single value, type: string. Defaults to empty.

This value is used to distinguish between simple LEDs and WS281X RGB LEDs in the PKONE hardware system. This value must be set to led or left empty when setting up WS281X RGB/RGBW LEDs.

What if it did not work?

Have a look at our PKONE troubleshooting guide.

Something missing or wrong? You can fix it!

This website is edited by people like you! Is something wrong or missing? Is something out of date, or can you explain it better?

Please help us! You can fix it yourself and be an official "open source" contributor!

It's easy! See our Beginner's guide to editing the docs.

Page navigation via the keyboard: < >

You can navigate this site via the keyboard. There are two modes:

General navigation, when search is not focused:

  • F , S , / : open search dialog
  • P , , : go to previous page
  • N , . : go to next page

While using the search function:

  • Down , Up : select next / previous result
  • Esc , Tab : close search
  • Enter : go to highlighted page in the results