avinya module

class avinya.Avinya

Bases: object

Avinya is a ESP32 based robotics board that can be controlled using Python and Scratch.

connectGamepad(gamepadIP: str)

Connects to the CodeSkool mobile gamepad app. You can download the app from the Google Play Store: https://play.google.com/store/apps/details?id=cc.codeskool.gamepad. You need to connect the gamepad app to the same WiFi network as the robot. You will get the connection IP address, when you start the gamepad app.

Parameters:

gamepadIP (str) – The IP address of the gamepad app, which hosts the websocket based server. You need to provide just the IP address, and not the port number or the protocol.

Return type:

None

connectWifi(ssid: str, password: str)

Connects to a wifi network. If the connection is established or already exists, it will return True. If the connection cannot be established, it will return False. The function will wait for 10 seconds for the connection to be established. If the connection is not established within 10 seconds, it will return False.

Parameters:

  • ssid (str) – The SSID of the wifi network

  • password (str) – The password of the wifi network

Returns:

result – True if the connection is established, False otherwise

Return type:

bool

disconnectGamepad()

Disconnects from the CodeSkool mobile gamepad app.

Return type:

None

followLine()

Makes the robot follow a black line using the front line following sensors. The robot will stop when it reaches a black horizontal line, i.e. when all the sensors detects a black line. If one of the line following sensors on the edge detects a black line, the robot will turn in the direction of the sensor that detected the black line, to keep the line in the middle of the robot.

Return type:

None

getDistance(id: int)

Returns the distance from the object calculated using the ultrasonic sensor in mm.

Parameters:

id (int) – The id or index of the ultrasonic sensor. The index value can be either 0 or 1.

Returns:

distance – The distance of the object from the ultrasonic sensor in mm.

Return type:

int

getGamepadKey()

Gets the key pressed on the gamepad. Whenever you press a key on the gamepad, it will return the code of the key. When you release the key, it will return another code with a ‘1’ appended to the key code, instead of ‘0’. For example, if you press the ‘North’ key, it will return ‘N0’, and when you release the key, it will return ‘N1’.

You can also use the following constants to check for the pressed or released key codes:

TRIANGLE_PRESSED = “T0”

TRIANGLE_RELEASED = “T1”

CIRCLE_PRESSED = “C0”

CIRCLE_RELEASED = “C1”

CROSS_PRESSED = “X0”

CROSS_RELEASED = “X1”

SQUARE_PRESSED = “Q0”

SQUARE_RELEASED = “Q1”

NORTH_PRESSED = “N0”

NORTH_RELEASED = “N1”

SOUTH_PRESSED = “S0”

SOUTH_RELEASED = “S1”

EAST_PRESSED = “E0”

EAST_RELEASED = “E1”

WEST_PRESSED = “W0”

WEST_RELEASED = “W1”

SELECT_PRESSED = “L0”

SELECT_RELEASED = “L1”

START_PRESSED = “R0”

START_RELEASED = “R1”

Returns:

key – The key pressed on the gamepad.

Return type:

str

getIRSensorValue(id: int)

Returns the IR sensor analog reading.

Parameters:

id (int) – The id or index of the IR sensor. The id can be either LEFT = 0 or RIGHT = 1. The analog reading of the IR sensor is a value between 0 and 4095. The left IR sensor is connected to the 34 pin of the ESP32. The right IR sensor is connected to the 35 pin of the ESP32.

Returns:

value – The analog reading of the IR sensor.

Return type:

int

getMotorSpeed(motor: int)

Gets the speed of the motor.

Parameters:

motor (int) – The id of the motor whose speed is to be set. The id can be either MOTOR_LEFT = 0, MOTOR_RIGHT = 1.

Returns:

speed – The speed of the motor. The speed is returned as a percentage value between 0 and 100%. This value is derived from the duty cycle of the MCPWM signal and is mapped from 0 to 1023 to 0 to 100.

Return type:

int

initLineFollowingParameters(leftMotorSpeed: int, rightMotorSpeed: int, turnMotorFSpeed: int, turnMotorBSpeed: int)

Initialize the line following parameters, this function is called before using the followLine function. It sets the speed of the motors while driving the robot and keeping it on the line.

Parameters:

  • leftMotorSpeed (int) – The speed of the left motor, when the robot is on the line and to move forward

  • rightMotorSpeed (int) – The speed of the right motor, when the robot is on the line and to move forward

  • turnMotorFSpeed (int) – The speed of the motor, which needs to go into forward direction. So, when the left IR sensor detects a black line, the robot needs to turn left. For that, the left motor needs to go backward and the right motor needs to go forward. So, this will become the speed of the right motor which needs to go forward.

  • turnMotorBSpeed (int) – The speed of the motor, which needs to go into backward direction. So, when the right IR sensor detects a black line, the robot needs to turn right. For that, the left motor needs to go forward and the right motor needs to go backward. So, this will become the speed of the right motor which needs to go backward.

Return type:

None

isButtonPressed(button: int)

Returns the state of the button, whether it is pressed or not.

Parameters:

button (int) – The id of the button. The id can be either LEFT = 0 or RIGHT = 0. The LEFT and the RIGHT buttons are both connected to the same analog pin 36.

Returns:

state – The state of the button. True if the button is pressed, False otherwise.

Return type:

bool

isIRSensorActive(id: int)

Returns the state of the IR sensor, whether it is active or not. The IR sensor is active when it detects a black line.

Parameters:

id (int) – The id or index of the IR sensor. The id can be either LEFT = 0 or RIGHT = 1.

Returns:

state – The state of the IR sensor. True if the IR sensor is active, False otherwise.

Return type:

bool

isPadTouched(pin: int)

Returns True if the touch pad is touched, i.e. the value is less than the touch threshold of 300, otherwise returns False.

Parameters:

pin (int) – The pin number of the touch pad. The pin number can be either 4, 0, 2, 15, 13, 12, 14, 27, 33, 32. You may also use the constants T1 = 15, T2 = 13, T3 = 12, T4 = 14, T5 = 27 for the touch pad pins.

Returns:

isTouched – True if the touch pad is touched, i.e. the value is less than the touch threshold of 300, otherwise returns False.

Return type:

bool

moveBackward(t: int)

Moves the robot backward for a specified time.

Parameters:

t (int) – The time in seconds for which the robot should move backward.

Return type:

None

moveForward(t: int)

Moves the robot forward for a specified time. The robot moves forward by setting the direction of both the left and right motors to forward. The robot has 2 motors, one on the left and one on the right. The left motor is connected to the IN1: 2 and IN2: 17 pins of the ESP32. The right motor is connected to the IN1: 4 and IN2: 16 pins of the ESP32.

Parameters:

t (int) – The time in seconds for which the robot should move forward.

Return type:

None

playAudio(wavAudioFile: str)

Play an wave audio file. This function is non-blocking and will return immediately and continuously play the audio file. It will play the audio file at the default sample rate of 16KHz using the I2S interface on Pins:

WS_PIN = 25

SCK_PIN = 26

SD_OUT_PIN = 22

Parameters:

wavAudioFile (str) – The path to the wave audio file to play, ex: ‘/audio.wav’

Return type:

None

playAudioUntilDone(wavAudioFile: str)

Play an wave audio file until it is done. This function is blocking and will not return until the audio file is done playing. It will play the audio file at the default sample rate of 16KHz using the I2S interface on Pins:

WS_PIN = 25

SCK_PIN = 26

SD_OUT_PIN = 22

Parameters:

wavAudioFile (str) – The path to the wave audio file to play, ex: ‘/audio.wav’

Return type:

None

playMelodies(melodies: list[str], duration: int, duty=32767)

Play melody using the buzzer connected to DAC Pin 25. The melody is a list of notes, where each note is a string notation. The duration is the duration of each note, whether whole note, half note, etc. represented as a fraction . The duty is the duty cycle of the buzzer. The default duty cycle is 50% (32767).

Parameters:

  • melodies (list) –

    A list of notes to play, where each note is a string notation.

    An example of a melody is:

    [‘C4’, ‘C4’, ‘_’, ‘G4’, ‘G4’, ‘_’, ‘A4’, ‘A4’, ‘_’, ‘G4’]

    You can append a number to the note to change the octave, for example: [‘C4’, ‘C5’, ‘C6’]

    The ‘_’ character is used to indicate a rest.

    You can also append ‘#’ to the note to indicate a sharp, for example:

    [‘C4#’, ‘D4#’, ‘F4#’, ‘G4#’, ‘A4#’]

  • duration (int) – The duration of each note as a fraction. Whether the duration is a whole note, half note, quarter note, etc.

  • duty (int) – The duty cycle of the buzzer. The default duty cycle is 50% (32767).

Return type:

None

playTone(note: int, duration: int)

Play a tone using the buzzer connected to DAC Pin 25. The note is the frequency of the tone in Hz. The duration is the duration of each note, whether whole note, half note, etc. represented as a fraction .

Parameters:

  • note (int) – The frequency of the tone in Hz.

  • duration (int) – The duration of the tone as a fraction. Whether the duration is a whole note, half note, quarter note, etc.

Return type:

None

readAnalogInput(pin: int)

Returns the value of the analog reading at the specified input pin.

Parameters:

pin (int) – The pin number of the analog input. The pin number can be either 34, 35, 32, 33, 25, 26, 27, 14, 12, 13, 15, 2, 4, 0, 23, 22, 21, 19, 18, 5, 17, 16. You can also use the constants: A1 = 33, A2 = 32, A3 = 39

Returns:

value – The value of the analog reading at the specified input pin.

Return type:

int

readButtonState(pin: int)
Returns the state of the button, whether it is pressed or not.

It will read the input pin and return the value of the pin. When the button is pressed, the pin will be connected to ground and the value will be 0. When the button is not pressed, the pin will be connected to 3.3V and the value will be 1. The pull up resistor will pull the pin to 3.3V when the button is not pressed.

Parameters:

pin (int) – The pin number of the button.

Returns:

state – The state of the button. True if the button is pressed, False otherwise.

Return type:

bool

readDigitalInput(pin: int)

Reads the state of the specified digital input pin.

Parameters:

pin (int) – The pin number of the digital input. The pin number can be either 34, 35, 32, 33, 25, 26, 27, 14, 12, 13, 15, 2, 4, 0, 23, 22, 21, 19, 18, 5, 17, 16. You can also use the constants: D1 = 18, D2 = 19, D3 = 26

Returns:

state – The state of the specified digital input pin. The state can be either 0 or 1. 0 means LOW and 1 means HIGH.

Return type:

int

rgbClearDisplay()

Clears the RGB Neopixel display. All pixels will be turned off.

Parameters:

None –

Return type:

None

rgbClearPixel(pixel: int)

Clears a specific pixel on the RGB Neopixel display.

Parameters:

pixel (int) – The pixel number on the RGB Neopixel display. The pixel number is 0 based. The pixels index/number starts from the left and goes to the right, and then the next row.

Return type:

None

rgbDrawPattern(pattern: str)

Draws a pattern on the RGB LED NeoPixel strip, connected to the Pin 21 of the ESP32. The pattern is a string of characters, where each character represents a color. The characters can be either:

‘0’ for BLACK,

‘1’ for WHITE,

‘R’ for RED,

‘G’ for GREEN,

‘B’ for BLUE,

‘O’ for ORANGE,

‘Y’ for DARK YELLOW,

‘P’ for PINK,

‘L’ for LIME GREEN or

‘C’ for CYAN.

The pattern string should be of length 35, where each character represents a LED on the NeoPixel strip. The first character in the string represents the LED at the top left corner of the strip, and the last character in the string represents the LED at the bottom right corner of the strip.

Parameters:

pattern (str) – The pattern string to be drawn on the NeoPixel strip.

Return type:

None

rgbMatrixClearPixel(row, col)

Clears a specific pixel on the RGB Neopixel display.

Parameters:

  • row (int) – The row number of the pixel. The row number is 1 based. The row number starts from 1 and ends at 5.

  • col (int) – The column number of the pixel. The column number is 1 based. The column number starts from 1 and ends at 7.

Return type:

None

rgbMatrixSetPixelWithBrightness(row, col, color, brightness)

Sets the color of a specific pixel on the RGB Neopixel display.

Parameters:

  • row (int) – The row number of the pixel. The row number is 1 based. The row number starts from 1 and ends at 5.

  • col (int) – The column number of the pixel. The column number is 1 based. The column number starts from 1 and ends at 7.

  • color (tuple) – The color of the pixel. The color is a tuple of 3 values (R, G, B) where each value is between 0 and 255.

  • brightness (int) – The brightness of the RGB Neopixel. The brightness can be any value between 0 and 100.

Return type:

None

rgbSetBrightness(brightness: int)

Sets the brightness of the RGB Neopixel display. The brightness can be any value between 0 and 100.

Parameters:

brightness (int) – The brightness of the RGB Neopixel display. The brightness can be any value between 0 and 100.

Return type:

None

rgbSetPixelColor(pixel: int, color: tuple[int, int, int])

Sets the color of a specific pixel on the RGB Neopixel display. The pixel number is 0 based. The pixels index/number starts from the left and goes to the right, and then the next row. The color is a tuple of 3 values (R, G, B) where each value is between 0 and 255.

Parameters:

  • pixel (int) – The pixel number on the RGB Neopixel display. The pixel number is 0 based. The pixels index/number starts from the left and goes to the right, and then to the next row again from left to right and so on. There are 35 pixels in total, in a 5x7 matrix, starting from the top left corner, and ending at the bottom right corner. The pixel number starts from 0 and ends at 34.

  • color (tuple) – The color of the pixel. The color is a tuple of 3 values (R, G, B) where each value is between 0 and 255.

rgbSetPixelColorWithBrightness(pixel: int, color: tuple[int, int, int], brightness: int)

Sets the color of a specific pixel on the RGB Neopixel display. The pixel number is 0 based. The pixels index/number starts from the left and goes to the right, and then the next row. The color is a tuple of 3 values (R, G, B) where each value is between 0 and 255.

Parameters:

  • pixel (int) – The pixel number on the RGB Neopixel display. The pixel number is 0 based. The pixels index/number starts from the left and goes to the right, and then to the next row again from left to right and so on. There are 35 pixels in total, in a 5x7 matrix, starting from the top left corner, and ending at the bottom right corner. The pixel number starts from 0 and ends at 34.

  • color (tuple) – The color of the pixel. The color is a tuple of 3 values (R, G, B) where each value is between 0 and 255.

  • brightness (int) – The brightness of the RGB Neopixel. The brightness can be any value between 0 and 100.

Return type:

None

rgbShowAnimation(animation: int, times: int)

Show animation on the RGB NeoPixel LED strip. Each animation frame is shown for 1 second.

Parameters:

  • animation (int) – The animation to show. It can be one of the following values: POLICE_SIREN.

  • times (int) – The number of times to show the animation.

Return type:

None

rgbShowEmotion(emotion: int)
Shows an emotion on the RGB Neopixel display.

It displays a pattern or emoji on the RGB Neopixel display, based on the emotion passed as a parameter.

Parameters:

emotion (str) – The emotion to be displayed on the RGB Neopixel display. The emotion can be either HAPPY, ANGRY, BASIC, CRYING, DISCO, GIGGLE, SUPERANGRY, LOVE, NERD, REJECT, SURPRISE, WAVE, THINKING or SIREN.

rgbShowScrollingText(text: str, color: tuple[int, int, int], speed: int)
Show scrolling text on the NeoPixel RGB strip connected to Pin 21.

The text will scroll from right to left. The color parameter is a tuple with the RGB values. It will first clear the strip and then starts the scrolling text animation.

Parameters:

  • text (str) – The text to scroll from right to left.

  • color (tuple[int, int, int]) – The color of the text. The tuple contains the RGB values. Each value must be between 0 and 255. Example: (255, 0, 0) will display the text in red. (0, 255, 0) will display the text in green. (0, 0, 255) will display the text in blue.

  • speed (int) –

    The speed of the scrolling text. The lower the value the faster the text will scroll. Some of the preset values are:

    SLOW = 1000

    MEDIUM = 600

    FAST = 300

Return type:

None

rgbShowText(text: str, color: tuple[int, int, int])

Show text first character on the NeoPixel RGB strip connected to Pin 21. This function will only display only the first character of the text. It will first clear the strip and then draw the first character of the text. The color parameter is a tuple with the RGB values.

Parameters:

  • text (str) – The text to display. Only the first character will be displayed.

  • color (tuple[int, int, int]) – The color of the text. The tuple contains the RGB values. Each value must be between 0 and 255. Example: (255, 0, 0) will display the text in red. (0, 255, 0) will display the text in green. (0, 0, 255) will display the text in blue.

Return type:

None

runMotor(motor: int, direction: int, speed: int)

Runs the motor on the robot in a specified direction at a specified speed.

Parameters:

  • motor (int) – The id or index of the motor. The id can be either MOTOR_LEFT = 0, MOTOR_RIGHT = 1 or MOTOR_BOTH = 2.

  • direction (int) – The direction in which the motor should run. The direction can be either FORWARD = 0 or BACKWARD = 1.

  • speed (int) – The speed at which the motor should run. Speed is entered as percentage value between 0 and 100, which is mapped to the MCPWM range 0 to 1023.

Return type:

None

setIRSensorThreshold(id: int, threshold: int)

Sets the threshold of the IR sensor. Threshold is the minimum analog reading/value of the IR sensor when it detects a black line. The default threshold is 2047. The threshold can be any value between 0 and 4095. If the analog reading of the IR sensor is greater than the threshold, it means that the IR sensor is active, i.e. it has detected a black line.

Parameters:

id (int) – The id or index of the IR sensor. The id can be either LEFT = 0 or RIGHT = 1.

setMotorDirection(motor: int, direction: int)

Sets the direction of the motor rotation.

Parameters:

  • motor (int) – The id of the motor whose direction is to be set. The id can be either MOTOR_LEFT = 0, MOTOR_RIGHT = 1 or MOTOR_BOTH = 2.

  • direction (int) – The direction of the motor. The direction can be either FORWARD = 0 or BACKWARD = 1.

Return type:

None

setMotorSpeed(motor: int, speed: int)

Sets the speed of the motor.

Parameters:

  • motor (int) – The id of the motor whose speed is to be set. The id can be either MOTOR_LEFT = 0, MOTOR_RIGHT = 1 or MOTOR_BOTH = 2.

  • speed (int) – The speed of the motor. The speed is represented as percentage value between 0 and 100%, which is mapped to the duty cycle of the MCPWM signal, a value between 0 and 1023.

Return type:

None

setServoAngle(pin: int, angle: int)

Sets the angle of the servo connected to the specified pin.

Parameters:

  • pin (int) –

    The pin number of the servo whose angle is to be set. There are 2 servo ports on the avinya development board. The pin numbers of these servo ports are:

    SERVO1 = 22

    SERVO2 = 23

  • angle (int) – The angle of the servo. The angle can be any value between 0 and 180.

Return type:

None

setTempo(bpm: int)
Set the tempo of the melody in beats per minute.

The default tempo is 169 BPM. The tempo is used to calculate the duration of each note in the melody.

Parameters:

bpm (int) – The tempo of the melody in beats per minute.

Return type:

None

setUltrasonicPins(id: int, trig: int, echo: int)

Sets the trigger and echo pins for the ultrasonic sensor with the specified id or index to be connected to the specified pins.

Parameters:

  • id (int) – The id or index of the ultrasonic sensor to be connected. It can be either 0 or 1.

  • trig (int) – The trigger pin of the ultrasonic sensor.

  • echo (int) – The echo pin of the ultrasonic sensor.

Return type:

None

setVolume(volume: int)

Set the volume of the speaker, for the playback of audio files. The volume can be set between 0 and 100.

Parameters:

volume (int) – The volume to set the speaker to, between 0 and 100

Return type:

None

showCopyright()

Displays the copyright notice of the library.

Parameters:

None –

Return type:

None

showVersion()

Displays the version number of the library.

Parameters:

None –

Return type:

None

speak(text: str, lang: str)

Speak the given text in the specified language using the robot’s speaker. This function is blocking and will return only once it is done speaking the text.

Parameters:

  • text (str) – The text to spoken by the robot.

  • lang (str) – The language of the text, ex: ‘en-US’. The language specifies in which language the text is spoken.

Return type:

None

stopAudio()

Stop playing an audio file that is currently playing.

Parameters:

None –

Return type:

None

stopMotor(motor: int)

Stop the motor(s) on the robot.

Parameters:

motor (int) – The id or index of the motor. The id can be either MOTOR_LEFT = 0, MOTOR_RIGHT = 1 or MOTOR_BOTH = 2.

Return type:

None

stopRobot()

Stops the robot by setting the speed of both the left and right motors to 0.

Parameters:

None –

Return type:

None

turnLeft(t: int)

Turns the robot left for a specified time. The robot turns left by setting the direction of the left motor to backward and the direction of the right motor to forward.

Parameters:

t (int) – The time in seconds for which the robot should turn left.

Return type:

None

turnRight(t: int)

Turns the robot right for a specified time. The robot turns right by setting the direction of the left motor to forward and the direction of the right motor to backward.

Parameters:

t (int) – The time in seconds for which the robot should turn right.

Return type:

None

writeAnalogOutput(pin: int, duty_cycle: int)

Writes the specified PWM duty cycle to the specified output pin.

Parameters:

  • pin (int) – The pin number of the analog output. The pin number can be either 25, 26, 27, 14, 12, 13, 15, 2, 4, 0, 23, 22, 21, 19, 18, 5, 17, 16.

  • duty_cycle (int) – The PWM duty cycle to be written to the specified output pin. The duty cycle can be any value between 0 and 1023.

Return type:

None

writeDigitalOutput(pin: int, state: int)

Writes the specified state HIGH or LOW to the specified output pin, which corresponds to 1 or 0 respectively.

Parameters:

  • pin (int) – The pin number of the digital output. The pin number can be either 34, 35, 32, 33, 25, 26, 27, 14, 12, 13, 15, 2, 4, 0, 23, 22, 21, 19, 18, 5, 17, 16. You can also use the constants: D1 = 18, D2 = 19, D3 = 26

  • state (int) – The state to be written to the specified output pin. The state can be either 0 or 1. You can also use the constants: LOW = 0, HIGH = 1

Return type:

None

avinya.startScratchMode()

Restarts the ESP32 board in Scratch mode, with Avinya Robotics Car Scratch Firmware. The robot will start listening for Scratch commands on the websocket port 80 and on the robot’s IP address at /car url path. You can check the Avinya Scratch extension at: https://ide.codeskool.cc/ You need to connect the CodeSkool Scratch app to the same WiFi network as the robot. In the Scratch app, you need to provide the IP address of the robot, so that it can connect to the robot.

Parameters:

None –

Return type:

None