8/1/24, 11:40 PM Quickstart - ZYMKEY4 |

Quickstart - ZYMKEY4
ZYMKEY4 is the fourth generation of the Zymbit security module designed specifically to work with Raspberry Pi. It connects to the GPIO
header of the SBC and uses the I2C bus and GPIO4 as a WAKE_PIN to communicate with the SBC CPU via an encrypted channel.

 Notice

Raspberry PI OS Bookworm updated the kernel to version 6.6.y in March 2024. The kernel no longer overrides an upstream
kernel decision to force the base number of the main GPIO controller to be global GPIO 0. If the WAKE_PIN number is not set,
the ZYMKEY will not bind. You will see 5 flashes per second continuously.For RPI4, RPI5, and CM4 platforms, you will need to
set the WAKE_PIN in the following manner:

Determine the numbering for GPIO4 by examining /sys/kernel/debug/gpio for the number associated with GPIO4, then set an
environment variable in the Zymbit environment variable file:

sudo su
wake_pin=`grep GPIO4 /sys/kernel/debug/gpio | sed -r 's/[^0-9]*([0-9]*).*/\1/'`
echo "wake_pin=$wake_pin" # sanity check value is set
echo "ZK_GPIO_WAKE_PIN=$wake_pin" > /var/lib/zymbit/zkenv.conf
systemctl restart zkifc

As of 6.6.20, the numbering is: RPI4=516 RPI5=575 CM4=516

In this Getting Started guide we describe how to install your ZYMKEY4 to a Raspberry Pi running Raspberry PI OS or Ubuntu. The
installation process is the same for both of these Linux distributions.

The ZYMKEY4 occupies 10 pins on the GPIO header. It can also be used with other GPIO devices attached, or other I2C devices attached.
The correct address range and use of IO pins will be described in this guide as well.

https://docs.zymbit.com/getting-started/zymkey4/quickstart/ 1/7
8/1/24, 11:40 PM Quickstart - ZYMKEY4 |

ZYMKEY4 Hardware ZYMKEY4 Pinout

The top and bottom of the ZYMKEY4 hardware showing the

location of the GPIO header and other connectors.

The pinout of the header of the ZYMKEY4. ZYMKEY4 requires

exclusive access to GPIO4 , which can be remapped to
another GPIO pin. It also share the I2C bus with the default
address of 0x30 .

Summary of Setup Steps

Installing the hardware
Install the battery on the ZYMKEY4, and connect it to the host single-board computer (SBC).
Establish an I2C connection
Enable the I2C bus on the host device in order to be able to communicate with the ZYMKEY4.
Install the client software
These utilities provided by Zymbit are necessary to interact with the hardware module.
Test the installation
Your ZYMKEY4 is now temporarily bound to your SBC and ready for use in developer mode.

Installing the hardware

Battery Installation

 Warning

Battery installation is not required for the ZYMKEY4 to function, but it is highly recommended if your device is vulnerable to
physical access!

To maintain the real-time clock (RTC) and tamper detection features in the event of power loss, install a high quality 3V CR1025 coincell
battery (not included) in the ZYMKEY4’s battery slot with +ve facing upward. Recommend CR1025 from Panasonic or Renata

https://docs.zymbit.com/getting-started/zymkey4/quickstart/ 2/7
8/1/24, 11:40 PM Quickstart - ZYMKEY4 |

Hardware Installation

 Danger

Installing your hardware correctly is important to avoid destroying your SBC or ZYMKEY4. Be sure to follow the instructions
below carefully. In particular:

Pay close attention to the images below to ensure the SBC’s GPIO pins are properly aligned with the ZYMKEY4’s header.
Ensure that your Raspberry Pi is powered down before proceeding.
Ensure that the coincell battery (if installed) is installed with the positive side (marked with + ) facing upward.

Before installing
Power off your Raspberry Pi to ensure that neither the SBC or the ZYMKEY4 are damaged.

Attach hardware
Hold the ZYMKEY4 with the LED and battery holder facing upward. Then, carefully align the ZYMKEY4’s connector with the first 10 GPIO
pins of the Raspberry Pi.

https://docs.zymbit.com/getting-started/zymkey4/quickstart/ 3/7
8/1/24, 11:40 PM Quickstart - ZYMKEY4 |

Press down firmly on the ZYMKEY4 to connect it to the GPIO pins of the Raspberry Pi. The ZYMKEY4 should fit relatively snug and
maintain a tight interference fit around the pins.

https://docs.zymbit.com/getting-started/zymkey4/quickstart/ 4/7
8/1/24, 11:40 PM Quickstart - ZYMKEY4 |

The ZYMKEY4 occupies 10 pins on the GPIO header. If the header of the ZYMKEY4 isn’t properly aligned with the GPIO header of the
Raspberry Pi, both devices could be damaged.

Using an Alternative GPIO Pin

SECRUOSER

The default configuration uses GPIO4. This can be reconfigured to use another GPIO of your choice.
Read article 

Power on and confirm operation

After you have connected the hardware and are sure that the pins are properly aligned, power up your Raspberry Pi. You should see a
blue LED blinking rapidly and consistently (5 blinks per second). This confirms that your ZYMKEY4 is operation but unconfigured.

If the blue LED blinks erractically, or not at all, then there is an installation error and you should check the connections.

Power Quality Considerations

SECRUOSER

Power quality matters to the reliable and secure operation of your system and ZYMKEY4.
Read article 

Establish an I2C connection

For Raspian-based operating systems, you must configure the state of the I2C.

1. Log in to your Raspberry Pi and run sudo raspi-config .

2. Navigate to Interfacing Options -> I2C -> Would you like the ARM I2C interface to be enabled?

3. Select yes, and confirm this choice.

Your I2C bus is now configured and ready to talk to the ZYMKEY4. The default I2C address for the ZYMKEY4 is 0x30 .

ZYMKEY4 FAQ & TROUBLESHOOTING

SECRUOSER

How do I set an alternative I2C address?

The default I2C address for ZYMKEY4 is 0x30. If this conflicts with another device in your system, you can reconfigure the ZYMKEY4 to use another
address of your choice.
Read article 

 Notice

The default mode for the cpu scaling governor is ondemand. There have been some issues with the interaction between the
zymkey and the I2C bus, when the governor is set to ondemand. We highly recommend to switching the governor to
performance to get the most out of the zymkey.

CPU Scaling Governor

SECRUOSER

How to set cpu governor to performance.

https://docs.zymbit.com/getting-started/zymkey4/quickstart/ 5/7
8/1/24, 11:40 PM Quickstart - ZYMKEY4 |

Read article 

Install the client software

Login to your host device and follow these steps to install the ZYMKEY4’s client software.

 Notice

As of March 2023, Raspberry PI OS 32-bit images install the 64-bit kernel along with the 32-bit root filesystem. This does not
allow our installation script to work. In order to properly install on an 32-bit system, edit /boot/config.txt and add the
following line to the bottom of the file, then reboot.

arm_64bit=0

The ZYMKEY4 will require a number of packages to be installed from the Raspbian and Zymbit apt repositories. The following setup
script will be install a number of files and software packages on your system, including:

Zymbit .service files located in the /etc/systemd/system directory

pip

Ensure that curl is installed on your host:

sudo apt install curl

Download and install the necessary Zymbit services onto your device.

curl -G https://s3.amazonaws.com/zk-sw-repo/install_zk_sw.sh | sudo bash

Test the installation

When the software installation has completed, reboot your device. After the reboot has completed, the Raspberry Pi will perform an
operation that will temporarily bind the ZYMKEY4 to your SBC. Once the ZYMKEY4 is bound to the SBC, the ZYMKEY4’s blue LED should
blink slowly–once every 3 seconds–to indicate that the binding is complete.

Binding, Device ID, and Authentication

SECRUOSER

In production mode, ZYMKEY4 generates a unique Device ID by measuring certain attributes of the specific host and the ZYMKEY4 itself to
permanently associate the two.
Read article 

The quickest way to get started is to see the ZYMKEY4’s various features at work by running these test scripts that were installed with the
client software:

python3 /usr/local/share/zymkey/examples/zk_app_utils_test.py
python3 /usr/local/share/zymkey/examples/zk_crypto_test.py

The example scripts are missing in focal and bullseye distributions. You can get the example scripts from here:

Download example files

Now you’re ready to start developing with ZYMKEY4 and Raspberry Pi. When it’s time to deploy your project, read our guide on enabling
Production Mode:

Enabling Production Mode - ZYMKEY4

SECRUOSER

To permanently bind the ZYMKEY4 to a host board, generates a unique Device ID by measuring certain attributes of the host and the ZYMKEY4 itself
to associate the two devices.

https://docs.zymbit.com/getting-started/zymkey4/quickstart/ 6/7
8/1/24, 11:40 PM Quickstart - ZYMKEY4 |

Read article 

https://docs.zymbit.com/getting-started/zymkey4/quickstart/ 7/7