UCUq API#

API for the Python UCUq library (see the dedicated section for the installation).

Functions#

  • ucuq.sleep(delay): the microcontroller waits for <delay> seconds before executing the next instruction;
  • ucuq.sleepStart(): starts a timer (to be used in conjunction with sleepWait(…));
  • ucuq.sleepWait(<delay>): the microcontroller waits for <delay> seconds to elapse since the last sleepStart() was called before executing the next instruction.

Classes#

ucuq.GPIO#

Handling of an output corresponding to a microcontroller pin.

  • ucuq.GPIO(<pin>) (constructor): returns an object that manages the pin identified by <pin>;
  • GPIO.high(): sets the pin to high;
  • GPIO.low(): sets the pin to low.

ucuq.WS2812#

Handling of WS2812 LEDs.

  • ucuq.WS2812(<count>,<pin>) (constructor): returns an object that manages <count> WS2812 LEDs connected to pin <pin>;
  • WS2812.setValue(<index>, <value>): sets the LED at index <index> (starting at 0) in the buffer to color <value> (a list or tuple in the format R,V,B ranging from 0 to 255);
  • WS2812.fill(<value>): sets all LEDs in the buffer to the color <value>;
  • WS2812.write(): sends the contents of the buffer to the LEDs.

ucuq.I2C#

Handling of the I2C protocol.

  • ucuq.I2C(<sda>,<scl>) (constructor): returns an object that manages a component connected to the microcontroller pins identified by <sda> and <scl> and that supports the I2C protocol.

ucuq.SoftI2C#

Same as the ucuq.I2C class, but software-based, allowing <sda> and <scl> to be any GPIO pin on the microcontroller.

ucuq.HT16K33#

Handling of an HT16K33 component.

  • ucuq.HT16K33(<i2c>) (constructor): returns an object that manages an HT16K33 component via <i2c>, which must be an instance of I2C or SoftI2C;
  • HT16K33.setBlinkRate(<rate>): sets <rate> to the number of times per second that the display blinks (allowed values: 0, 0.5, 1, and 2);
  • HT16K33.setBrightness(<brightness>): sets <brightness> as the display’s brightness level (from 0 to 15);
  • HT16K33.clear(): clears the display buffer;
  • HT16K33.draw(<pattern>): writes <pattern>, which must be a sequence of hexadecimal characters, each representing 4 horizontal pixels, to the display buffer;
  • HT16K33.plot (<x>,<y>,<ink>): turns on the pixel at position <x>, <y> in the display buffer if <ink> is 1, or turns it off if <ink> is 0;
  • HT16K33.show(): sends the contents of the buffer to the display.

ucuq.PWM#

Handling of a PWM output.

  • ucuq.PWM(<pin>,<freq>,*,ns=<ns>,u16=<u16>) (constructor): returns an object that generates a signal with a frequency of <freq> Hz, with a pulse width of <ns> nanoseconds or a duty cycle of <u16> / 65536, on a PWM output identified by <pin> (<ns> and <u16> cannot be set simultaneously);
  • PWM.setU16(<u16>): generates a signal with a pulse width of a ratio of <u16> / 65536;
  • PWM.setNS(<ns>): generates a signal with a pulse width of <ns> nanoseconds;
  • PWM.setFreq(<freq>): generates a signal with a frequency of <freq> Hertz.

ucuq.HD44780_I2C#

Handling of an LCD display based on the HD44780 controller and controlled via the I2C protocol.

  • ucuq.HD44780_I2C(<columns>,<lines>,<i2c>) (constructor): returns an object that, via <i2c>, which must be an instance of I2C or SoftI2C, manages an HD44780 controller connected to an LCD display with <lines> lines and <columns> columns;
  • HD44780_I2C.moveTo(x,y): puts the cursor at column <x> and row <y>;
  • HD44780_I2C.putString(<string>): displays the character string <string>;
  • HD44780_I2C.clear(): clears the display;
  • HD44780_I2C.hideCursor(): hides the cursor;
  • HD44780_I2C.showCursor(): displays the cursor;
  • HD44780_I2C.blinkCursorOff(): turns off the cursor blinking;
  • HD44780_I2C.blinkCursorOn(): turns on the cursor blinking;
  • HD44780_I2C.backlightOff(): turns off the backlight;
  • HD44780_I2C.backlightOn(): turns on the backlight;
  • HD44780_I2C.ttyWrite(<text>, <delay>=.2, <hideCursorOnEnd>=True): writes <text>, character by character, with a delay of <delay> seconds between each character, and hides the cursor after the last character is displayed if <hideCursorOnEnd> is set to True;
  • HD44780_I2C.createChar(<location>, <charmap>): sets the customizable character at position <location> (an integer from 0 to 7) using <charmap>, which is an array of 8 integers (one per line, from top to bottom) where the 5 least significant bits define the color of the corresponding pixel;
  • HD44780_I2C.uploadUpwardGaugeChars(): sets the customizable characters so that a vertical gauge can be displayed from bottom to top;
  • HD44780_I2C.putUpwardGauges(<position>, <gauges>): displays the vertical gauges <gauges> from bottom to top at position <position>; requires a prior call to HD44780_I2C.uploadUpwardGaugeChars();
  • HD44780_I2C.uploadDownwardGaugeChars(): defines the customizable characters so that a vertical gauge can be displayed from top to bottom;
  • HD44780_I2C.putDownwardGauges(<position>, <gauges>): displays the list of vertical gauges <gauges> from top to bottom at position <position>; requires a prior call to HD44780_I2C.uploadDownwardGaugeChars();
  • HD44780_I2C.uploadForwardGaugeChars(): defines the customizable characters so that a horizontal gauge can be displayed from left to right;
  • HD44780_I2C.getForwardGauge(<gauge>): returns a string corresponding to a left-to-right horizontal gauge with a value of <gauge>; requires a prior call to HD44780_I2C.uploadForwardGaugeChars();
  • HD44780_I2C.uploadBackwardGaugeChars(): sets the customizable characters so that a right-to-left horizontal gauge can be displayed;
  • HD44780_I2C.getBackwardGauge(<gauge>, <max>): returns a string corresponding to a right-to-left horizontal gauge with a value of gauge and max as the maximum value; requires a prior call to HD44780_I2C.uploadBackwardGaugeChars();
  • HD44780_I2C.uploadVPeakChars(): defines customizable characters to display a vertical peak level;
  • HD44780_I2C.putUpwardPeaks(<position>, <peaks>): displays a list of vertical peak levels <peaks> from bottom to top at position <position>; requires a prior call to HD44780_I2C.uploadVPeakChars();
  • HD44780_I2C.putDownwardPeaks(<position>, <peaks>): displays a list of vertical peak levels <peaks> from top to bottom at position <position>; requires a prior call to HD44780_I2C.uploadVPeakChars();
  • HD44780_I2C.uploadHPeakChars(): defines the customizable characters used to display a horizontal peak level;
  • HD44780_I2C.getForwardPeak(<peak>, <max>): returns a string corresponding to the horizontal peak level <peak> from left to right with a maximum value of <max>; requires a prior call to HD44780_I2C.uploadHPeakChars();
  • HD44780_I2C.getBackwardPeak(<peak>, <max>): returns a string corresponding to the horizontal peak level <peak> from right to left, with <max> as the maximum value; requires a prior call to HD44780_I2C.uploadHPeakChars().

ucuq.SSD1306_I2C#

Handling of an OLED display via the I2C protocol.

  • ucuq.SSD1306_I2C(<width>,<height>,<i2c>): returns an object that controls an OLED display with dimensions <width> by <height> via <i2c>, which must be an instance of I2C or SoftI2C;
  • SSD1306_I2C.ellipse(x, y, rx, ry, col, fill=False, quad=15): draws an ellipse centered at <x>, <y>, with radius <rx>, <ry>, and color <col>, filled if fill is True, and only in the quadrants where the bits in <quad> are set to 1;
  • SSD1306_I2C.fill(<col>): fills the buffer with the color <col>;
  • SSD1306_I2C.line(x1, y1, x2, y2, col): draws a line of color <col> from position <x1>, <y1> to position <x2>, <y2>;
  • SSD1306_I2C.pixel (<x>,<y>,<col>): sets the pixel at position <x>, <y> in the buffer to the color <col>;
  • SSD1306_I2C.scroll(<dx>,<dy>): moves the pattern in the buffer by <dx>, <dy> pixels;
  • SSD1306_I2C.rect(<x>,<y>,<w>,<h>,fill=<fill>): places a rectangle with width <w> and height <h> at position <x>, <y> in the buffer and fills it if <fill> is True (default value);
  • SSD1306_I2C.text(<text>,<x>,<y>): places the string <text> in the buffer at position <x>, <y>;
  • SSD1306_I2C.draw(<pattern>, <width>, <ox>=0, <oy>=0, <mul>=1): places the contents of <pattern> (a string consisting of hexadecimal digits, each representing the color of 4 horizontal pixels) with a width of width (a positive integer that is a multiple of 4) pixels, at position <ox>, <oy> (positive integers) with a multiplier of <mul> (a positive integer).
  • SSD1306_I2C.show(): sends the contents of the buffer to the display.

ucuq.SH1106_I2C#

Same as ucuq.SSD1306_I2C, but for the SH1106 display model.

ucuq.Buzzer#

Handling of a passive buzzer.

  • ucuq.Buzzer(pwm): (constructor) returns an object that manages a passive buzzer via <pwm>, which must be an instance of PWM;
  • Buzzer.on(freq): emits a sound at a frequency of <freq> Hertz;
  • Buzzer.play(note): emits a sound at the frequency corresponding to the MIDI note <note>;
  • Buzzer.off(): mutes the sound;
  • Buzzer.ratio(<ratio>): (a floating-point number between 0 and 1, inclusive) becomes the ratio between the high and low levels of the square-wave signal driving the buzzer (with a value of 0.5, the signal is a square wave); returns the previous ratio;
  • Buzzer.ratio() returns the buzzer’s ratio.
Backward UCUq installation Using the Wokwi simulator - UCUq Forward