Skip to content

Api Documentation ‐ Hub

Jump to bottom
carl wheezer with dreads edited this page Sep 24, 2025 · 2 revisions

Hub Module Wiki Page

This wiki page provides documentation for the Hub module and its sub-modules.

Hub Module

The Hub module provides functions for interacting with the hub device, including retrieving device information, controlling power, and monitoring temperature.

Requiring the Module

To use the Hub module, you can require it in your script:

local Hub = require("src.modules.hub")

Functions

Hub:device_uuid()

This function retrieves the unique identifier of the hub device.

Returns:

  • string: The device UUID.

Hub:hardware_id()

This function retrieves the hardware identifier of the hub.

Returns:

  • string: The hardware ID.

Hub:power_off()

This function initiates the power-off sequence for the hub.

Returns:

  • int: An integer indicating the success or status of the power-off operation (specific values would depend on implementation).

Hub:temperature()

This function retrieves the current temperature of the hub. The temperature is measured in decidegrees Celsius (e.g., a return value of 250 means 25.0 degrees Celsius).

Returns:

  • int: The hub temperature in decidegrees Celsius.

Sub-Modules

Sub-modules of the Hub module will be documented in this section as they are supplied. They can be required using the following pattern:

local SubModule = require("src.modules.hub.SubModuleName")

light_matrix Module

The light_matrix module provides functions and constants for controlling the 5x5 light matrix display on the hub.

Requiring the Module

To use the light_matrix module, you can require it in your script:

local light_matrix = require("src.modules.hub.light_matrix")

Image Constants

The light_matrix module provides a variety of built-in image constants that can be displayed on the light matrix.

Constant Value Description
IMAGE_HEART 1 A heart symbol.
IMAGE_HEART_SMALL 2 A small heart symbol.
IMAGE_HAPPY 3 A happy face.
IMAGE_SMILE 4 A smiling face.
IMAGE_SAD 5 A sad face.
IMAGE_CONFUSED 6 A confused face.
IMAGE_ANGRY 7 An angry face.
IMAGE_ASLEEP 8 An asleep face.
IMAGE_SURPRISED 9 A surprised face.
IMAGE_SILLY 10 A silly face.
IMAGE_FABULOUS 11 A fabulous face.
IMAGE_MEH 12 An indifferent face.
IMAGE_YES 13 A checkmark or 'yes' symbol.
IMAGE_NO 14 An 'x' or 'no' symbol.
IMAGE_CLOCK12 15 Clock showing 12 o'clock.
IMAGE_CLOCK1 16 Clock showing 1 o'clock.
IMAGE_CLOCK2 17 Clock showing 2 o'clock.
IMAGE_CLOCK3 18 Clock showing 3 o'clock.
IMAGE_CLOCK4 19 Clock showing 4 o'clock.
IMAGE_CLOCK5 20 Clock showing 5 o'clock.
IMAGE_CLOCK6 21 Clock showing 6 o'clock.
IMAGE_CLOCK7 22 Clock showing 7 o'clock.
IMAGE_CLOCK8 23 Clock showing 8 o'clock.
IMAGE_CLOCK9 24 Clock showing 9 o'clock.
IMAGE_CLOCK10 25 Clock showing 10 o'clock.
IMAGE_CLOCK11 26 Clock showing 11 o'clock.
IMAGE_ARROW_N 27 North arrow.
IMAGE_ARROW_NE 28 North-east arrow.
IMAGE_ARROW_E 29 East arrow.
IMAGE_ARROW_SE 30 South-east arrow.
IMAGE_ARROW_S 31 South arrow.
IMAGE_ARROW_SW 32 South-west arrow.
IMAGE_ARROW_W 33 West arrow.
IMAGE_ARROW_NW 34 North-west arrow.
IMAGE_GO_RIGHT 35 Right arrow.
IMAGE_GO_LEFT 36 Left arrow.
IMAGE_GO_UP 37 Up arrow.
IMAGE_GO_DOWN 38 Down arrow.
IMAGE_TRIANGLE 39 A triangle.
IMAGE_TRIANGLE_LEFT 40 A left-pointing triangle.
IMAGE_CHESSBOARD 41 A small chessboard pattern.
IMAGE_DIAMOND 42 A diamond shape.
IMAGE_DIAMOND_SMALL 43 A small diamond shape.
IMAGE_SQUARE 44 A square shape.
IMAGE_SQUARE_SMALL 45 A small square shape.
IMAGE_RABBIT 46 A rabbit silhouette.
IMAGE_COW 47 A cow silhouette.
IMAGE_MUSIC_CROTCHET 48 A crotchet (quarter note).
IMAGE_MUSIC_QUAVER 49 A quaver (eighth note).
IMAGE_MUSIC_QUAVERS 50 Two quavers (eighth notes).
IMAGE_PITCHFORK 51 A pitchfork symbol.
IMAGE_XMAS 52 A Christmas tree or star.
IMAGE_PACMAN 53 Pac-Man.
IMAGE_TARGET 54 A target symbol.
IMAGE_TSHIRT 55 A T-shirt.
IMAGE_ROLLERSKATE 56 A roller skate.
IMAGE_DUCK 57 A duck silhouette.
IMAGE_HOUSE 58 A house.
IMAGE_TORTOISE 59 A tortoise silhouette.
IMAGE_BUTTERFLY 60 A butterfly silhouette.
IMAGE_STICKFIGURE 61 A stick figure.
IMAGE_GHOST 62 A ghost.
IMAGE_SWORD 63 A sword.
IMAGE_GIRAFFE 64 A giraffe silhouette.
IMAGE_SKULL 65 A skull.
IMAGE_UMBRELLA 66 An umbrella.
IMAGE_SNAKE 67 ;) A snake.

Functions

light_matrix.clear()

This function turns off every pixel on the 5x5 Light Matrix, effectively clearing the display.

light_matrix.get_orientation()

This function returns the current orientation of the Light Matrix. The return value will correspond to an orientation constant (e.g., orientation.UP, orientation.DOWN).

Returns:

  • number: The current orientation of the Light Matrix.
light_matrix.get_pixel(x, y)

This function retrieves the brightness level of a single pixel at the specified (x, y) coordinates.

Parameters:

  • x (number): The X-coordinate of the pixel, ranging from 0 to 4.
  • y (number): The Y-coordinate of the pixel, ranging from 0 to 4.

Returns:

  • number: The intensity (brightness) of the pixel.
light_matrix.set_orientation(top)

This function changes the perceived "top" side of the Light Matrix, rotating its display.

Parameters:

  • top (number): A constant representing the desired top side of the hub (e.g., orientation.UP).
light_matrix.set_pixel(x, y, intensity)

This function sets the brightness of a single pixel at the specified (x, y) coordinates.

Parameters:

  • x (number): The X-coordinate of the pixel, ranging from 0 to 4.
  • y (number): The Y-coordinate of the pixel, ranging from 0 to 4.
  • intensity (number): The brightness level for the pixel (e.g., 0 for off, 100 for full brightness).
light_matrix.show(pixels)

This function allows you to update all 25 pixels of the Light Matrix simultaneously by providing a list of intensity values. The list should contain 25 numbers, corresponding to the pixels in a specific order (e.g., row by row).

Parameters:

  • pixels (number[]): A table (list) containing 25 numerical values, where each value represents the intensity for a corresponding pixel on the 5x5 matrix.
light_matrix.show_image(image)

This function displays one of the pre-defined images (from the IMAGE_ constants) on the Light Matrix.

Parameters:

  • image (number): The ID of the built-in image to display (e.g., light_matrix.IMAGE_HEART).
light_matrix.write(text, intensity, time_per_character)

This function displays a given string of text on the Light Matrix, showing one character at a time.

Parameters:

  • text (string): The text string to display.
  • intensity (number, optional): The brightness level for the pixels forming the text. Defaults to 100 if not provided.
  • time_per_character (number, optional): The duration in milliseconds each character is displayed before moving to the next. Defaults to 500ms if not provided.

Port Module

The Port module provides constants for mapping the physical labels of ports on the Hub to their corresponding numerical identifiers.

Requiring the Module

To use the Port module, you can require it in your script:

local Port = require("src.modules.hub.Port")

Constants

The module defines the following constants for each port:

  • Port.A (number): The Port that is labelled ‘A’ on the Hub.
  • Port.B (number): The Port that is labelled ‘B’ on the Hub.
  • Port.C (number): The Port that is labelled ‘C’ on the Hub.
  • Port.D (number): The Port that is labelled ‘D’ on the Hub.
  • Port.E (number): The Port that is labelled ‘E’ on the Hub.
  • Port.F (number): The Port that is labelled ‘F’ on the Hub.

Sound Module

The Sound module provides functionalities for generating sounds and controlling audio output from the hub. It includes constants for waveform types and functions for playing beeps and stopping sounds.

Requiring the Module

To use the Sound module, you can require it in your script:

local Sound = require("src.modules.hub.Sound")

Constants

The Sound module defines the following constants:

  • Sound.ANY (number): Represents any sound channel.
  • Sound.DEFAULT (number): Represents the default sound channel or setting.
  • Sound.WAVEFORM_SINE (number): Represents a sine waveform for sound generation.
  • Sound.WAVEFORM_SQUARE (number): Represents a square waveform for sound generation.
  • Sound.WAVEFORM_SAWTOOTH (number): Represents a sawtooth waveform for sound generation.
  • Sound.WAVEFORM_TRIANGLE (number): Represents a triangle waveform for sound generation.

Functions

Sound.beep(freq, duration, volume, attack, decay, sustain, release, transition, waveform, channel)

This function plays a beep sound from the hub's speaker. It allows for detailed control over the sound's characteristics, including frequency, duration, volume, and envelope parameters.

Parameters:

  • freq (number): The frequency of the beep in Hertz.
  • duration (number): The duration of the beep in milliseconds.
  • volume (number): The volume of the beep (e.g., 0-100).
  • attack (number|nil, optional): The attack time in milliseconds, controlling how quickly the sound reaches its peak volume.
  • decay (number|nil, optional): The decay time in milliseconds, controlling how quickly the sound falls from its peak to sustain level.
  • sustain (number|nil, optional): The sustain level (as a percentage of peak volume), representing the volume during the main body of the sound.
  • release (number|nil, optional): The release time in milliseconds, controlling how quickly the sound fades out after the note is released.
  • transition (number|nil, optional): A transition time in milliseconds for blending between sounds.
  • waveform (number|nil, optional): The type of waveform to use (e.g., Sound.WAVEFORM_SINE).
  • channel (number|nil, optional): The audio channel to play the sound on.
Sound.stop()

This function immediately stops all currently playing sounds from the hub's speaker.

Clone this wiki locally