europi

Rory Allen 2024 Apache License Version 2.0

Before using any of this library, follow the instructions in programming_instructions.md to set up your module.

The EuroPi library is a single file named europi.py. It should be imported into any custom program by using from europi import * to give you full access to the functions within, which are outlined below. Inputs and outputs are used as objects, which each have methods to allow them to be used. These methods are used by using the name of the object, for example ‘cv3’ followed by a ‘.’ and then the method name, and finally a pair of brackets containing any parameters that the method requires.

For example:

cv3.voltage(4.5)

Will set the CV output 3 to a voltage of 4.5V.

class europi.AnalogueInput(pin, min_voltage=0, max_voltage=12.0)

A class for handling the reading of analogue control voltage.

The analogue input allows you to ‘read’ CV from anywhere between 0 and 12V.

It is protected for the entire Eurorack range, so don’t worry about plugging in a bipolar source, it will simply be clipped to 0-12V.

The functions all take an optional parameter of samples, which will oversample the ADC and then take an average, which will take more time per reading, but will give you a statistically more accurate result. The default is 32, provides a balance of performance vs accuracy, but if you want to process at the maximum speed you can use as little as 1, and the processor won’t bog down until you get way up into the thousands if you wan’t incredibly accurate (but quite slow) readings.

The percent function takes an optional parameter deadzone. However this parameter is ignored and just present to be compatible with the percent function of the AnalogueReader and Knob classes

choice(values, samples=None, deadzone=None)

Return a value from a list chosen by the current voltage value.

percent(samples=None, deadzone=None)

Current voltage as a relative percentage of the component’s range.

range(steps=100, samples=None, deadzone=None)

Return a value (upper bound excluded) chosen by the current voltage value.

set_deadzone(deadzone)

Override the default deadzone with the given value.

set_samples(samples)

Override the default number of sample reads with the given value.

class europi.AnalogueReader(pin, samples=32, deadzone=0.0)

A base class for common analogue read methods.

This class in inherited by classes like Knob and AnalogueInput and does not need to be used by user scripts.

choice(values, samples=None, deadzone=None)

Return a value from a list chosen by the current voltage value.

percent(samples=None, deadzone=None)

Return the percentage of the component’s current relative range.

range(steps=100, samples=None, deadzone=None)

Return a value (upper bound excluded) chosen by the current voltage value.

set_deadzone(deadzone)

Override the default deadzone with the given value.

set_samples(samples)

Override the default number of sample reads with the given value.

class europi.Button(pin, debounce_delay=200)

A class for handling push button behavior.

Button instances have a method last_pressed() (similar to DigitalInput.last_triggered()) which can be used by your script to help perform some action or behavior relative to when the button was last pressed (or input trigger received). For example, if you want to call a function to display a message that a button was pressed, you could add the following code to your main script loop:

# Inside the main loop...
if b1.last_pressed() > 0 and ticks_diff(ticks_ms(), b1.last_pressed()) < 2000:
    # Call this during the 2000 ms duration after button press.
    display_button_pressed()

Note, if a button has not yet been pressed, the last_pressed() default return value is 0, so you may want to add the check if b1.last_pressed() > 0 before you check the elapsed duration to ensure the button has been pressed. This is also useful when checking if the digital input has been triggered with the DigitalInput.last_triggered() method.

handler(func)

Define the callback function to call when rising edge detected.

handler_falling(func)

Define the callback function to call when falling edge detected.

last_pressed()

Return the ticks_ms of the last button press

If the button has not yet been pressed, the default return value is 0.

value()

The current binary value, HIGH (1) or LOW (0).

class europi.DigitalInput(pin, debounce_delay=0)

A class for handling reading of the digital input.

The Digital Input jack can detect a HIGH signal when recieving voltage > 0.8v and will be LOW when below.

To use the handler method, you simply define whatever you want to happen when a button or the digital input is triggered, and then use x.handler(new_function). Do not include the brackets for the function, and replace the ‘x’ in the example with the name of your input, either b1, b2, or din.

Here is another example how you can write digital input handlers to react to a clock source and match its trigger duration.:

@din.handler
def gate_on():
    # Trigger outputs with a probability set by knobs.
    cv1.value(random() > k1.percent())
    cv2.value(random() > k2.percent())

@din.handler_falling
def gate_off():
    # Turn off all triggers on falling clock trigger to match clock.
    cv1.off()
    cv2.off()

When writing a handler, try to keep the code as minimal as possible. Ideally handlers should be used to change state and allow your main loop to change behavior based on the altered state. See tips from the MicroPython documentation for more details.

handler(func)

Define the callback function to call when rising edge detected.

handler_falling(func)

Define the callback function to call when falling edge detected.

last_triggered()

Return the ticks_ms of the last trigger.

If the button has not yet been pressed, the default return value is 0.

value()

The current binary value, HIGH (1) or LOW (0).

class europi.DigitalReader(pin, debounce_delay=500)

A base class for common digital inputs methods.

This class in inherited by classes like Button and DigitalInput and does not need to be used by user scripts.

handler(func)

Define the callback function to call when rising edge detected.

handler_falling(func)

Define the callback function to call when falling edge detected.

value()

The current binary value, HIGH (1) or LOW (0).

class europi.Display(*args: Any, **kwargs: Any)

A class for drawing graphics and text to the OLED.

The OLED Display works by collecting all the applied commands and only updates the physical display when oled.show() is called. This allows you to perform more complicated graphics without slowing your program, or to perform the calculations for other functions, but only update the display every few steps to prevent lag.

To clear the display, simply fill the display with the colour black by using oled.fill(0)

More explanations and tips about the the display can be found in the oled_tips file oled_tips.md

centre_text(text, clear_first=True, auto_show=True)

Display one or more lines of text centred both horizontally and vertically.

@param text The text to display @param clear_first If true, the screen buffer is cleared before rendering the text @param auto_show If true, oled.show() is called after rendering the text. If false, you must call oled.show() yourself

rotate(rotate)

Flip the screen from its default orientation

@param rotate True or False, indicating whether we want to flip the screen from its default orientation

class europi.Knob(pin, deadzone=0.01)

A class for handling the reading of knob voltage and position.

Read_position has a default value of 100, meaning if you simply use kx.read_position() you will return a whole number percent style value from 0-100.

There is also the optional parameter of samples (which must come after the normal parameter), the same as the analogue input uses (the knob positions are ‘read’ via an analogue to digital converter). It has a default value of 256, but you can use higher or lower depending on if you value speed or accuracy more. If you really want to avoid ‘noise’ which would present as a flickering value despite the knob being still, then I’d suggest using higher samples (and probably a smaller number to divide the position by). The default samples value can also be set using the set_samples() method, which will then be used on all analogue read calls for that component.

An optional deadzone parameter can be used to place deadzones at both positions (all the way left and right) of the knob to make sure the full range is available on all builds. The default value is 0.01 (resulting in 1% of the travel used as deadzone on each side). There is usually no need to change this.

Additionally, the choice() method can be used to select a value from a list of values based on the knob’s position:

def clock_division(self):
    return k1.choice([1, 2, 3, 4, 5, 6, 7, 8, 16, 32])

When the knob is all the way to the left, the return value will be 1, at 12 o’clock it will return the mid point value of 5 and when fully clockwise, the last list item of 32 will be returned.

The ADCs used to read the knob position are only 12 bit, which means that any read_position value above 4096 (2^12) will not actually be any finer resolution, but will instead just go up in steps. For example using 8192 would only return values which go up in steps of 2.

choice(values, samples=None, deadzone=None)

Return a value from a list chosen by the current voltage value.

percent(samples=None, deadzone=None)

Return the knob’s position as relative percentage.

range(steps=100, samples=None, deadzone=None)

Return a value (upper bound excluded) chosen by the current voltage value.

read_position(steps=100, samples=None, deadzone=None)

Returns the position as a value between zero and provided integer.

set_deadzone(deadzone)

Override the default deadzone with the given value.

set_samples(samples)

Override the default number of sample reads with the given value.

class europi.Output(pin, min_voltage=0, max_voltage=10.0)

A class for sending digital or analogue voltage to an output jack.

The outputs are capable of providing 0-10V, which can be achieved using the cvx.voltage() method.

So that there is no chance of not having the full range, the chosen resistor values actually give you a range of about 0-10.5V, which is why calibration is important if you want to be able to output precise voltages.

off()

Set the voltage LOW at 0 volts.

on()

Set the voltage HIGH at 5 volts.

toggle()

Invert the Output’s current state.

value(value)

Sets the output to 0V or 5V based on a binary input, 0 or 1.

voltage(voltage=None)

Set the output voltage to the provided value within the range of 0 to 10.

europi.bootsplash()

Display the EuroPi version when booting.

europi.clamp(value, low, high)

Returns a value that is no lower than ‘low’ and no higher than ‘high’.

europi.reset_state()

Return device to initial state with all components off and handlers reset.

europi.turn_off_all_cvs()

Calls cv.off() for every cv in cvs. This is done commonly enough in contrib scripts that a function seems useful.