PKONE protocol reference

The complete host protocol for PKONE EX2, Switch and Lightshow, updated from the 18 June 2021 specification and aligned with the current repaired firmware.

Wire format and transport

• Frames are printable ASCII, begin with P, and end with uppercase E. Do not append a newline.
• Numeric fields are fixed-width, zero-padded decimal unless a field explicitly says hexadecimal.
• USB serial uses 115200 baud. Classic CAN uses standard 11-bit frames at 250 kbit/s.
• The board connected to the host by USB provides the serial link to the CAN chain. Board addresses come from the DIP switches; restart a board after changing its address.
• EX2 and Switch addresses are 0–7. Lightshow addresses are 0–3. Every device on one CAN chain must have a unique address.
• Send one request at a time and wait for its reply. Acknowledgements do not contain transaction IDs and several replies may arrive together.

Controller and board discovery

Discovery capability tokens

F

Firmware version; the last digit is the minor version, so F28 means 2.8.

H

Hardware revision; the last digit is the minor version in current builds.

PY / PN

48 V power present / absent when the board can report it.

I40

Forty switch inputs.

C00 / C02

Two physical coil connectors disabled / enabled by firmware.

MIX

One Lightshow firmware supports both RGB and RGBW, selected per group with PLT.

Watchdog and safety

Switches and optos

Coils

Hardware rules

A hardware rule connects a local switch directly to one coil for low-latency action. Each coil stores one rule. Creating a new rule for that coil replaces the old one; rule settings are separate from PCC.

b / nn

Board address 0–7 and coil 01–10.

mode

Rule mode 1–6.

sw1 / sw2

Input 01–35. Use 00 for an unused second input. Modes 5 and 6 require an EOS input in sw2.

inv1 / inv2

0 normal, 1 invert that input for the rule.

delay

000–999 ms before activation; used by mode 2.

pulse / pwr / hold

000–250 ms, 00–99% pulse power, 00–99% hold power.

recycle

000–500 ms.

PHRE acknowledges a saved rule. PHDE acknowledges deletion. Example flipper rule without EOS: PHR10140700000001009930000E. Example single-wound EOS rule: PHR00460400500000309912000E.

Servos

Lighting

Standard and addressable lighting commands are documented in full on Lightshow commands, including RGB, RGBW, batch updates, mixed group type selection, and all 20 built-in effects.

Direct USB firmware entry (new)

Errors

Lightshow commands

The full lighting protocol: 40 standard on/off outputs, eight groups of up to 64 addressable pixels, per-group RGB/RGBW selection, and 20 animations that run on the board.

Shared fields

b

Lightshow address 0–3.

g

Logical pixel group 1–8.

nn

Standard light 01–40.

pp

Pixel 01–64.

v

0 off, 1 on.

RRR GGG BBB WWW

Three-digit channel values, 000–255. RGB commands omit WWW.

tttt

Time in 10 ms units, 0000–4096 (0–40.96 seconds).

Standard on/off outputs

RGB pixel commands

RGBW pixel commands

Built-in board effects: PFX (new)

Effects are rendered by Lightshow itself, so they continue smoothly without repeated browser or CAN traffic. One effect can run independently on each group. A later pixel/group command for that group cancels its effect.

effect

00–20. Effect 00 stops and clears the selected group.

speed

010–999 ms between animation frames. Smaller values run faster.

brightness

000–255 global output scaling.

direction

0 forward, 1 reverse.

primary / secondary

Two RGBW colours, each encoded as four three-digit channels. RGB groups accept the same command and ignore the white channel electrically.

reply

PFXE when accepted.

Example: address 3, group 1, Rainbow Flow, 30 ms, full brightness, forward:

All built-in effect IDs

Board identity and discovery

A DIP-switch address says where a board is today. The STM32 serial says which physical board it is for its lifetime.

Discovery

The reply identifies address 3 as Lightshow firmware 2.2, hardware H112, mixed RGB/RGBW capable.

Permanent identity

PKONE Connect stores this as LS-003C00363439470F39343637. Moving the DIP switches changes the CAN address while preserving this saved board profile.

EX2 wiring map

EX2 supports direct USB and CAN-chain operation. This annotated map identifies power, coils, switches, optos, servos, status LEDs and communications.

View EX2 mechanical drawing (PDF)

Specifications

Switch wiring map

The Switch board expands playfield inputs and carries two protected 48 V coil channels. Use this map for board orientation, power flow, input banks and CAN placement.

View Switch mechanical drawing (PDF)

Specifications

Lightshow wiring map

Lightshow combines general on/off lighting with eight addressable RGB or RGBW groups. The map shows output banks, pixel connectors, power, CAN, USB and termination.

View Lightshow mechanical drawing (PDF)

Specifications

Connector and terminal reference

Match each coloured location marker on the board maps to the corresponding housing, terminal family and wire range in this reference.

Connector or terminal	Part number	Use
Molex KK 396 / 3.96 mm
2-circuit friction-ramp housing	09-50-8021	5 V, 12 V and 48 V input
4-circuit friction-ramp housing	09-50-8041	Coil input
6-circuit friction-ramp housing	09-50-8061	Coil input
Crimp terminal, 18–24 AWG	08-50-0106	Series 41695 housings · crimp tool 638279500
Molex KK 254 / 2.54 mm · Series 2695
3-circuit friction-ramp housing	22-01-2037	Servos and LEDs
4-circuit friction-ramp housing	22-01-2047	Opto
6-circuit friction-ramp housing	22-01-2067	Opto
8-circuit friction-ramp housing	22-01-2087	LEDs
10-circuit friction-ramp housing	22-01-2107	Switches and LEDs
Crimp terminal, 22–30 AWG	08-55-0102	Series 2695 housings · crimp tool 638118200
Molex Mini-Fit Jr. / 4.20 mm · Series 5557
4-circuit dual-row receptacle housing	39-01-2040	5 V and 12 V input/output · PKONE Power PCB
6-circuit dual-row receptacle housing	39-01-2060	48 V input/output · PKONE Power PCB
Female crimp terminal, 18–24 AWG	39-00-0039	Series 5557 housings · crimp tool 638190901

How PKONE Connect fits together

The hosted application stores projects and guides the workflow. Hardware communication stays on your computer.

What requires the helper?

Normal Workbench connection, input monitoring, coil/servo tests and Lightshow controls use Web Serial and do not require the helper. The helper is required by the hosted Programmer because firmware tools must run locally.

Install the local helper

Install the helper once on each computer that will program PKONE boards. Packages are available for macOS, Windows and Linux.

Before you start

• On macOS and Linux, Python 3.11 or newer, including the venv module. The Windows installer includes Python.
• Chrome, Microsoft Edge or Firefox.
• Download and install STM32CubeProgrammer from STMicroelectronics. On Linux, put STM32_Programmer_CLI on PATH.
• A USB data cable connected directly to the board being programmed.

macOS

1. Download and open the signed PKONE Connect Helper installer.
2. Complete the standard macOS installation.
   The Apple-notarized installer places PKONE Connect Helper in Applications and starts its local service.
3. Open PKONE Connect Helper from Applications.
   The background helper also starts automatically when you sign in.

Windows

1. Download and open the PKONE Connect Helper installer.
2. Choose the installation folder and select Install.
   Python and the required serial libraries are included.
3. Open PKONE Connect Helper from Start or the Desktop.
   The background helper also starts automatically when you sign in.

Linux

1. Download and extract the Linux helper ZIP.
2. Open a terminal in the extracted PKONE Connect Helper folder.
   Run ./install-pkone-helper.sh. The installer supports Debian/Ubuntu, Fedora, Arch and openSUSE families and installs missing system packages when required.
3. Sign out and back in if serial-group access was added.
   This is required once before accessing a PKONE board over USB.
4. Open PKONE Connect Helper from the application menu.
   A user service starts the helper automatically when you sign in. Run ~/.local/share/pkone-connect-helper/uninstall-pkone-helper.sh to remove it later.

On every platform, opening PKONE Connect Helper shows http://localhost:8876/helper. Create an eight-character pairing code in PKONE Connect and enter it on that page. The helper sends a desktop notification when firmware programming starts, completes, or fails. Linux notifications require the desktop's notify-send service.

Manual installation

Get and use a pairing code

Pairing authorises one running local helper to accept firmware jobs from your signed-in PKONE Connect session.

1. Start the helper and open http://localhost:8876/helper. It should say Waiting for pairing.
2. Sign in to PKONE Connect and open Programmer from the left menu.
3. Under Local hardware helper, click Create pairing code.
4. Copy the eight-character code into the local helper page and click Pair with hosted Workbench.
5. Return to Programmer. The status should change to Connected and ready.

If no code appears

• Reload Programmer and sign in again if the session expired.
• Confirm the helper page is open on the same computer.
• Create a fresh code; codes expire after ten minutes and can only be claimed once.
• If the page says Helper offline, restart the helper and create a new code.

Connect hardware for the first time

Start with EX2 connected by USB, output power removed, and every CAN board assigned a unique DIP address.

Step 1

Connect EX2 to the computer

Remove 48 V output power. Set EX2 to a unique address, connect its USB-B port directly to the computer, and leave outputs disarmed. USB supplies logic power for the first connection.

• USB-B connects EX2 to PKONE Connect.
• P1 is CAN in and P2 is CAN out.
• Do not connect a coil supply until input discovery is complete.

CAN wiring and termination →

48 V INP2 · CAN OUTP1 · CAN INUSB

Step 2

Add a Switch board

Give the Switch board a different DIP address, provide its correct logic supply, and connect it to the preceding board with an RJ45 CAT cable.

• P1 receives CAN from the previous board.
• P2 continues CAN to the next board.
• Keep 48 V coil power disconnected during initial input testing.

CAN wiring and termination →

48 V INP2 · CAN OUTP1 · CAN INUSB

Step 3

Add a Lightshow board

Connect EX2, Switch and Lightshow in one CAN line. EX2 connects to the computer by USB, EX2 and Switch receive 48 V, and Lightshow receives a regulated 5 V supply sized for the connected lighting load.

• Connect each P2 CAN OUT to the next board’s P1 CAN IN.
• General lighting uses the 40 on/off outputs.
• J1–J8 drive RGB or RGBW pixel strings.
• Pixel power and data must share a common ground.

CAN wiring and termination →

EX2First board

48 V INUSB → computerP2 · CAN OUT →

Termination fitted

RJ45 CAN→

SwitchMiddle board

48 V IN← P1 · CAN INP2 · CAN OUT →

No termination

RJ45 CAN→

LightshowLast board

5 V IN← P1 · CAN IN

Termination fitted

Step 4

Build one terminated CAN chain

Connect up to eight boards in one line. Fit a termination jumper to the two physical ends only; remove it from every board in the middle.

ComputerPKONE Connect

USB

Termination fittedEX2Address 0

CAN

No terminationSwitchAddress 1

CAN

Termination fittedLightshowAddress 2

Step 5

Discover and verify every board

Open Workbench, click Connect USB, and approve the PKONE serial device. Wait for discovery, then confirm the board type, firmware, hardware, address and permanent serial number for every device.

1Connect USB

2Wait for discovery

3Verify every identity

4Test inputs while disarmed

How to use PKONE Connect

Build the machine as one project: arrange the playfield, assign physical connectors, plan the CAN chain, test the hardware, install firmware and export the finished MPF files.

Step 1

Select or create a project

The Dashboard is the starting point for every machine. Select an existing project, create a blank project, or import a backup. The active-project card shows the design totals, while Build readiness links directly to anything that still needs attention.

• Use New project for a new machine.
• Use Import backup to restore a previous PKONE Connect export.
• Select a project card before editing any machine pages.

Step 2

Lay out the playfield

Open Playfield to place switches, optos, coils, lights and mechanisms over the playfield artwork. The Parts panel adds devices, Layers selects existing devices, and the inspector edits the selected part.

• Upload or replace the background art, then adjust Art alpha.
• Use Focus to dim groups that are not being edited.
• Name every part clearly; these names become useful throughout rules and MPF export.

Step 3

Assign every physical connection

Machine I/O connects each virtual playfield part to a board and connector. Register the expected boards first, then select one unused compatible connector for every coil, switch, opto, light and servo.

• Work through the grouped cards two columns at a time.
• A connector already assigned elsewhere cannot be selected twice.
• Resolve the red Needs attention total before export.

Step 4

Plan the CAN chain

Setup records the boards in their real cable order. Add up to eight boards, give every board a unique address and fit termination only to the first and last boards in the physical chain.

• Add EX2, Switch and Lightshow in the order they will be cabled.
• Match each planned board to its permanent serial number after discovery.
• Save Setup and clear every review warning before powering the complete machine.

Step 5

Connect and test safely

Workbench connects to real hardware through Web Serial, or to the built-in Virtual chain when hardware is unavailable. Discovery restores known board settings and keeps outputs disarmed.

• Leave the rate at 115200 and select Connect USB.
• Test switches and optos while outputs remain disarmed.
• Arm outputs only for an intentional coil, servo or lighting test.
• Use Stop all or press Escape if anything is unexpected.

Step 6

Install approved firmware

Programmer installs verified EX2, Switch and Lightshow firmware through a direct USB connection. The local helper and STM32CubeProgrammer must be installed and running before the board list becomes available.

• Disconnect output loads or safely power them down.
• Connect one board directly by USB and select its type, port, address and verified image.
• Enter the displayed confirmation phrase, then choose Program & verify.

Step 7

Review and export the MPF project

MPF Project checks that required switches, coils, shots and rules have valid PKONE mappings. Fix each named issue, review the generated configuration, then download the completed MPF project.

• Auto assign PKONE hardware can create a starting allocation.
• Open Machine I/O for missing physical mappings.
• Review Rules when a shot or rule dependency is incomplete.

Using Workbench

Workbench discovers the chain, restores saved board settings and provides guarded tests for the capability selected on the left.

Normal session

1. Click Connect USB.
2. Select a board in Connected boards.
3. Check the address, firmware, hardware, power and serial cards.
4. Choose a test section. The connection map highlights the related connectors.
5. Arm outputs only for an intentional output test.
6. Use Stop all or press Escape if anything is unexpected.

Bench log

TX is a command sent by PKONE Connect. RX is the controller or board reply. Descriptions in brackets explain the raw frame. Errors appear in red with a recovery step.

Test switches and optos

EX2 exposes 30 switch inputs and five optos. Switch exposes 40 inputs.

1. Select the board and open Switches & optos.
2. Click Read all inputs for a baseline snapshot.
3. Operate one physical switch and confirm its tile changes state and count.
4. Open the tile to give the connector a useful label or invert its displayed polarity.
5. Repeat for each connector and save the board profile.

Input 30 on EX2 may appear active when unconnected if the hardware input is floating or uses the opposite polarity. Confirm the connector with a meter and use display inversion only after checking the physical wiring.

Test without physical boards

The virtual chain models EX2 3.2 with Switch and Lightshow 3.0 so Workbench and MPF can exercise PKONE discovery, inputs, outputs, watchdogs and recovery before the bench hardware is ready.

Use it in Workbench

1. Open Workbench and click Virtual chain.
2. Confirm EX2 address 0 is firmware 3.2 and Switch address 2 and Lightshow address 3 are firmware 3.0.
3. Select an EX2 or Switch input and click Toggle virtual input.
4. Arm outputs to test EX2 coil/servo commands or Lightshow lamps, pixels and effects. Only the in-memory model changes.
5. Use the Fault test menu to verify watchdog, malformed reply, dropped reply, duplicate address and USB-disconnect recovery.

Reset and watchdog expiry return all virtual coils, servos, lamps, pixels and effects to their safe state. Switch has two physical coil connectors but firmware 3.0 reports C00, so the simulator keeps those outputs disabled.

Use it with MPF

Download and install the current helper package. Start PKONE Virtual Chain using the included macOS, Windows or Linux launcher. Developers can instead run python3 pkone_virtual_chain.py. Set the MPF PKONE port to socket://127.0.0.1:8777. The simulator prints both its MPF port and its local input-control address when ready.

pkone:
  port: socket://127.0.0.1:8777
  baud: 115200
  watchdog: 1000
  debug: true
  lightshow_groups:
    3-1: rgb

Inject a switch event into MPF

curl -X POST -H 'Content-Type: application/json' \
  -d '{"address":2,"input":40,"state":true}' \
  http://127.0.0.1:8778/input

Open http://127.0.0.1:8778/status to inspect virtual input, coil, servo and lighting state. The simulator listens on this computer only.

Test coils and servos

Output tests are intentionally guarded. Check the load voltage, rating, wiring and clear mechanism before arming.

Coil pulse

1. Select EX2 and Coils.
2. Choose the coil connector and begin with a short duration and low power.
3. Arm outputs, then use Fire one pulse.
4. Use hold only for a coil designed for continuous reduced-power operation.

Use EX2 firmware 3.2 or newer for held coils. It replaces the legacy slow hold cycle that could make a mechanism chatter or vibrate. Hold power is applied in 10% steps; 95–99% is treated as steady full power.

Servo

1. Connect signal, 5 V and ground in the correct order. Typical servo colours are white signal, red 5 V and black ground.
2. Select J2–J5 and set home with the mechanism in a safe position.
3. Test small moves before 0°–180° travel or repeated cycles.
4. Use Go home to return to the saved position.

Test Lightshow

Lightshow 3.0 supports RGB and RGBW strips in one firmware and provides 20 board-side effects.

Run an effect across the board

1. Select Lightshow and RGB / RGBW.
2. Choose an effect, primary and secondary colours, strip type, brightness, speed and direction.
3. Arm outputs.
4. Click Run effect. Workbench configures J1–J8 and starts the effect on the board.
5. Use Turn all off to stop the LEDs.

A successful run shows PFXE for every connector. The animation continues on Lightshow without continuous browser traffic.

Program EX2, Switch and Lightshow

The Programmer sends an approved job to the paired local helper. The helper identifies the direct USB board, enters its bootloader, programs, verifies and checks identity again.

1. Disconnect Workbench and connect USB directly to the board being updated.
2. Start and pair the local helper.
3. Open Programmer and refresh available hardware.
4. Select the board port, address and matching approved image.
5. Read the displayed board identity.
6. Confirm the update and keep power connected until verification completes.

EX2 v3 and Switch use STM32 USB DFU. Lightshow uses its CP2102 serial bridge and STM32 UART bootloader. Do not move USB or power during programming.

Troubleshooting

Start with the status shown by the local helper, then check the hosted Programmer and direct USB connection.

The helper page does not open

• Confirm the Terminal window is still running.
• Open http://127.0.0.1:8876/helper.
• If port 8876 is busy, close the old helper process and start it again.
• Re-run the installer if Python reports missing serial or certifi.

Pairing failed

• Create a new code; the old one may have expired or already been claimed.
• Check the computer clock and internet connection.
• Confirm the helper can reach https://designer.pennykpinball.com.
• Restart the helper after changing networks or waking the computer.

Programmer unavailable

• Install STM32CubeProgrammer and restart the helper.
• Close Workbench and other serial applications so the helper can open the USB port.
• Use a data-capable USB cable and connect directly instead of through an unreliable hub.

Common messages

60-day limited warranty

Penny K Pinball Ltd warrants to the original consumer purchaser that its merchandise will be free from defects in material or workmanship for 60 days from the date of purchase.

What is covered

During the 60-day warranty period, the unit will be repaired or replaced, at Penny K Pinball Ltd’s option, without charge to the purchaser when it is returned prepaid and insured with proof of the date of purchase.

What is not covered

The warranty does not apply to parts damaged during shipment or through improper handling, installation, usage or alteration. It also excludes damage caused by external factors, including excessive electrical surges, liquids, fire, acts of God or excessive externally applied forces.

Damage, wear or breakage that was not caused by defective materials or workmanship is not covered, whether it affects function or appearance.

Returning a unit

1. Include proof of the date of purchase.
2. Return the unit with postage prepaid and insured.
3. Pack the unit carefully in its original box and inside an anti-static bag. If the original box is unavailable, use a strong carton with ample protective padding and secure it well.
4. Send it to Penny K Pinball Ltd, 41A Thatcher Crescent, Crofton Downs, Wellington 6035, New Zealand.

Repairs outside warranty

A unit returned without proof of purchase, or after the 60-day warranty has expired, may be repaired. Penny K Pinball Ltd will advise the repair cost after inspecting the unit and will perform the repair after payment is received. This non-warranty repair service is available for one year from the date of purchase. The unit must be returned postage prepaid and insured.

Limitations

Penny K Pinball Ltd is not liable for loss of use of the product or other incidental or consequential costs, expenses or damages incurred by the purchaser. Any implied warranties are limited in duration to 60 days from the original date of purchase.

PKONE support

When you need help, include enough information to reproduce the problem without guessing.

Include in a support request

• EX2, Switch and Lightshow firmware versions.
• Each board’s DIP address and permanent serial.
• USB operating system and browser version.
• The exported Workbench log or commissioning report.
• A photo of the complete powered CAN chain and termination.
• The exact action taken immediately before the fault.