Python Setup

Ensure you have MATRIX CORE installed, before moving on.

Creating A Python Project

This setup will go through how to install all the necessary python packages needed to program with MATRIX CORE.

First, use the commands below to create a folder, inside in the home directory ~/ of your MATRIX device(Raspberry Pi). This will be where you'll put your python scripts.

cd ~/
mkdir python-matrix-core-app
cd python-matrix-core-app

Installing Python Packages

While inside your project directory, use the following commands to install all the necessary Python packages needed to interact with MATRIX CORE.

wget "" -O Pipfile
wget "" -O Pipfile.lock
wget "" -O requirements.txt 
wget "" -O 
sudo apt-get install build-essential python-dev

Python 2 Packages

Required packages for Python 2 can be installed by using the following command.
pip install -r requirements.txt

Python 3 Packages

Instead of pip, Python 3 packages will require pip3 which can be installed with the command below.
sudo apt-get install python3-pip
You can now install the required packages for Python 3.
pip3 install -r requirements.txt

Check If Everything Works


To ensure your installation has succeeded, create a file named and paste the code below.

## Set Initial Variables ##
import os # Miscellaneous operating system interface
import zmq # Asynchronous messaging framework
import time # Time access and conversions
from random import randint # Random numbers
import sys # System-specific parameters and functions
from matrix_io.proto.malos.v1 import driver_pb2 # MATRIX Protocol Buffer driver library
from matrix_io.proto.malos.v1 import io_pb2 # MATRIX Protocol Buffer sensor library
from multiprocessing import Process, Manager, Value # Allow for multiple processes at once
from zmq.eventloop import ioloop, zmqstream# Asynchronous events through ZMQ
matrix_ip = '' # Local device ip
everloop_port = 20021 # Driver Base port
led_count = 0 # Amount of LEDs on MATRIX device
# Handy function for connecting to the Error port 
from utils import register_error_callback

def config_socket(ledCount):  
    # Define zmq socket
    context = zmq.Context()
    # Create a Pusher socket
    socket = context.socket(zmq.PUSH)
    # Connect Pusher to configuration socket
    socket.connect('tcp://{0}:{1}'.format(matrix_ip, everloop_port))

    # Loop forever
    while True:
        # Create a new driver config
        driver_config_proto = driver_pb2.DriverConfig()
        # Create an empty Everloop image
        image = []
        # For each device LED
        for led in range(ledCount):
            # Set individual LED value
            ledValue = io_pb2.LedValue()
   = randint(0, 50)
   = randint(0, 200)
   = randint(0, 255)
            ledValue.white = 0
        # Store the Everloop image in driver configuration

        # Send driver configuration through ZMQ socket
        #Wait before restarting loop

def ping_socket():
    # Define zmq socket
    context = zmq.Context()
    # Create a Pusher socket
    ping_socket = context.socket(zmq.PUSH)
    # Connect to the socket
    ping_socket.connect('tcp://{0}:{1}'.format(matrix_ip, everloop_port+1))
    # Ping with empty string to let the drive know we're still listening

def everloop_error_callback(error):
    # Log error

def update_socket():
    # Define zmq socket
    context = zmq.Context()
    # Create a Subscriber socket
    socket = context.socket(zmq.SUB)
    # Connect to the Data Update port
    socket.connect('tcp://{0}:{1}'.format(matrix_ip, everloop_port+3))
    # Connect Subscriber to Error port
    socket.setsockopt(zmq.SUBSCRIBE, b'')
    # Create the stream to listen to data from port
    stream = zmqstream.ZMQStream(socket)

    # Function to update LED count and close connection to the Data Update Port
    def updateLedCount(data):
        # Extract data and pass into led_count global variable
        global led_count
        led_count = io_pb2.LedValue().FromString(data[0]).green
        # Log LEDs
        print('{0} LEDs counted'.format(led_count))
        # If LED count obtained
        if led_count > 0:
            # Close Data Update Port connection
            print('LED count obtained. Disconnecting from data publisher {0}'.format(everloop_port+3))
    # Call updateLedCount() once data is received

    # Log and begin event loop for ZMQ connection to Data Update Port
    print('Connected to data publisher with port {0}'.format(everloop_port+3))

if __name__ == '__main__':
    # Initiate asynchronous events
    # Start Error Port connection
    Process(target=register_error_callback, args=(everloop_error_callback, matrix_ip, everloop_port)).start()    

    # Ping the Keep-alive Port once
    # Start Data Update Port connection & close after response
    # Send Base Port configuration
    # Avoid logging Everloop errors on user quiting
    except KeyboardInterrupt:
        print(' quit')


Once you have the code copied, use one of the following commands to run a simple hello world app.

Python 2


Python 3



Next Steps

Now that everything is properly installed, learn more about the Everloop and other Driver Protocols MATRIX Core has to offer, or view the available Python examples.