As Easy As Click, Click, Code!

As easy as click, click, code!

v A motivational learning system Programming Reference Document 45284 Contents Interface Overview...... 1 The Fable PC Interface – Blockly...... 1 The Fable PC Interface – Python...... 2 Simple-View Blocks...... 3 Logic...... 3 Actions...... 4 Loops...... 5 Colors...... 6 Senses...... 7 Camera...... 8 Data...... 9 Math...... 10 Full-View Blocks...... 11 Logic...... 11 Actions...... 12 Loops...... 13 Colors...... 14 Functions...... 15 Senses...... 16 Camera...... 17 Data...... 18 Variables...... 19 Lists...... 20 Math...... 21 Python API...... 22 Joint Module...... 22 Face App...... 23 Sounds and Lights...... 23 Camera...... 24 Setup and Termination...... 24 Module Handling...... 25 Time and Wait...... 25 Testing Communication...... 25 Print, Plot, and Data Logs...... 25 Support Contact...... 26 Contact...... 26

45284 INTERFACE OVERVIEW

The Fable PC Interface – Blockly Users can program their robots by using the Fable software. The interface supports both block-1 and text-based2 programming. The software supports three complexity levels: Simple: Block-based programming for beginner or younger children. A limited number of blocks makes the interface easily accessible. Full: Block-based programming for more experienced or older students. Blocks support more advanced features such as math, functions, logic, and variables. Python®: Text-based programming using the Python programming language.

Block categories Run/stop code Project folders Open settings Start video stream Status bar Open documentation Python equivalent code Change to Python mode Plotting area

1 Based on Google Blockly

2 Based on Python 1 INTERFACE OVERVIEW

The Fable PC Interface – Python The Fable robots can be programmed in the Python language. Any block program will automatically be translated into Python code, which can then be modified and extended by the user.

Run/stop code Project folders Open settings Start video stream Python output area Open documentation Status bar Change to Blockly mode

2 SIMPLE-VIEW BLOCKS

Logic

If a value is true, then run the statements. Click the gear icon to add an else statement.

Returns true or false depending on the input parameters and the operator selection.

• And – Returns true if both inputs are true. • Or – Returns true if at least one input is true.

A Boolean variable that returns either a true or false value.

3 SIMPLE-VIEW BLOCKS

Actions

Changes the light color on a joint module or dongle; will not change the communication channel.

Plays back a standard audio sound on the computer.

Sets the angle that Servo X or Y on the joint module should move to in degrees from -90 to 90.

Sets the emotion of the robot’s face app on the smartphone.

Makes the face module vibrate.

4 SIMPLE-VIEW BLOCKS

Loops

Pauses the program for a number of seconds.

While a value is true, then run the statements.

5 SIMPLE-VIEW BLOCKS

Colors

Chooses a color from the palette.

6 SIMPLE-VIEW BLOCKS

Senses

Returns time in seconds since the program started.

Returns sound level of microphone on the computer; if the microphone is off, it must be turned on first.

Returns current angle of Servo X or Y on the joint module in degrees from -90 to 90.

Returns true if key is pressed down on the keyboard; otherwise returns false.

Returns current acceleration in direction X, Y, or Z of the smartphone with the face app.

7 SIMPLE-VIEW BLOCKS

Camera

Saves a picture from the camera in the "Fable pictures\" folder on the desktop.

Returns true if the selected color is found in the image of the camera.

Returns x- or y-coordinate of the color center found in the image of the camera.

Returns true if the camera detects motion. Amount number is the minimum percentage of motion in the image required to trigger a detection.

8 SIMPLE-VIEW BLOCKS

Data

Adds a data point to a time series plot that will be shown in the interface.

Adds data to a log file that is created on the desktop; can be opened in Microsoft Excel.

9 SIMPLE-VIEW BLOCKS

Math

A number.

Returns the numeric result of the computation (+, -, x, %, ^).

An angle defined by a number.

10 FULL-VIEW BLOCKS

Logic

If a value is true, then run the statements. Click the gear icon to add an else statement.

Returns true or false depending on the input parameters and the operator selection.

• And – Returns true if both inputs are true. • Or – Returns true if at least one input is true.

Returns true if the input is false. Returns false if the input is true.

A Boolean variable that returns either a true or false value.

Checks the test condition and if the condition is true, returns the if true value; otherwise returns the if false value.

11 FULL-VIEW BLOCKS

Actions

Changes the light color on a joint module or dongle; will not change the communication channel.

Plays back a standard audio sound on the computer.

Sets the angle that Servo X or Y on the joint module should move to in degrees from -90 to 90.

Sets the angle that Servo X or Y on Sets the direction the joint module should move to of the eyes on with a specified speed. Angle is in the face app. degrees from -90 to 90, and speed is a percent from 0% to 100%.

Ensures subsequent movements of the servos on the joint module will have the selected accuracy. At a high accuracy, the servo angles will have a smaller error, but at a high load, they can become unstable and vibrate. Sets the emotion of the robot’s face app on the smartphone.

Sets colors for elements found in the face app.

Makes the face module vibrate.

12 FULL-VIEW BLOCKS

Loops

Pauses the program for a number of seconds.

Repeats a statement a number of times.

While a value is true, then run the statements.

Repeats the statements a designated number of times by the variable i taking on the values from the start number to the end number, counting by the specified interval.

Sets the variable i to each item in a list and runs the statements.

Breaks out of the containing loop.

13 FULL-VIEW BLOCKS

Colors

Chooses a color from the palette.

Tells the program to select a random color.

Sets colors to a percentage of each.

Blends colors to a designated percentage.

14 FULL-VIEW BLOCKS

Functions

Creates a function with no output.

Creates a function with an output.

If a value is true, then return a second value.

15 FULL-VIEW BLOCKS

Senses

Selects module ID.

Returns time in seconds since the program started.

Returns sound level of microphone on the computer; if the microphone is off, it must be turned on first.

Reads a joint module’s battery level as a percent from 0% to 100%.

Returns true if key is pressed down on the keyboard; otherwise returns false.

Returns current angle of the servo on the joint module in degrees from -90 to 90.

Returns current acceleration in direction X, Y, or Z of the smartphone with the face app.

16 FULL-VIEW BLOCKS

Camera

Saves a picture from the camera in the "Fable pictures\" folder on the desktop.

Returns true if the selected color is found in the image of the camera.

Returns true if the selected color is found in the image of the camera. Nuances number defines how many nuances of the color to include (0 to 20). Size number is the minimum size of the colored object compared to the image (0% to 100%).

Returns x- or y-coordinate of the color center found in the image of the camera.

Returns x- or y-coordinate of the color center found in the image of the Returns true if the camera detects camera. Nuances motion. Amount number is the minimum number defines how percentage of motion in the image many nuances of the required to trigger a detection. color to include (0 to 20). Size number is the minimum size Returns x- or y-coordinate of of the colored object motion center. Amount number compared to the is the minimum percentage of image (0% to 100%). motion in the image required to trigger a detection.

17 FULL-VIEW BLOCKS

Data

Adds a data point to a time series plot that will be shown in the interface.

Adds data to a log file that is created on the desktop; can be opened in Microsoft Excel.

18 FULL-VIEW BLOCKS

Variables

Creates a new variable that can be used in the program. Its value is initially null and must be set before it can be used.

Sets this variable equal to the specified input.

Adds a number to the variable.

Returns the value of this variable.

19 FULL-VIEW BLOCKS

Lists

Returns a list with a length of 0 that contains no data records.

Creates a list with any number of items.

Creates a list consisting of the given value repeated the specified number of times.

Returns the length of a list.

Returns true if the list is empty.

Returns the index of the first or last occurrence of the specified item in a list. Returns 0 if the item is not found.

Returns the value of the item at the specified or a random position in a list. Potentially also removes the item.

Sets or inserts an item in a list at the specified position.

20 FULL-VIEW BLOCKS

Math

A number.

Returns the numeric result of the computation (+, -, x, %, ^).

Returns the numeric result of the operation (square root, absolute, logarithm).

Returns the result of the trigonometric function (sin, cos, tan, asin, acos, atan).

Returns the numeric value of the common constant [π, e, φ, sqrt(2), sqrt(1/2)].

Checks if a number is even, odd, prime, whole, positive, negative, or divisible by a certain number.

Rounds a number up or down.

Returns the numeric result of a computation of a list (sum, average, largest, median, mode, random item, standard deviation).

Returns the remainder from the result of the division of two numbers.

Constrains a number to be between the specified inclusive limits.

Returns a random integer between the two specified inclusive limits.

Returns a random fraction between the limits of 0.0 (inclusive) and 1.0 (exclusive).

An angle defined by a number.

21 PYTHON API

The following is a quick overview of selected Python functions that can be used to program Fable robots.

Joint Module

def setPos(posX, posY, moduleID) Sets the position of a specified joint module from -90 to 90 degrees. Ex: api.setPos(45, -60, 'PCA') def setSpeed(speedX, speedY, moduleID) Sets the speed of a specified joint module from -100% to 100%. Returns an instance of the joint module with updated speed values. Ex: api.setSpeed(50, 50, 'YRA') def setTorque(torqueX, torqueY, moduleID) Sets the torque for a specified joint module. Also sets the torque limit. This value ranges from -100% to 100%. Ex: api.setTorque(50, 50, 'YRA') def setAccurate(accurateX, accurateY, moduleID) Modifies the servo controller (compliance slopes, margins, and punch) to move Servos X and Y on the specified joint module more accurately. Ex: api.setAccurate('HIGH', 'DEFAULT', 'YRA') def getPos(servoID, moduleID) Returns the position of one of the servos for a specified joint module. The encoder has a resolution of 0.29 degrees. Servos can move from -90 to 90 degrees. Ex: x = api.getPos('X', 'YRA') def getSpeed(servoID, moduleID) Returns percentage representation from -100% to 100% of speed for one of the two servos for a specified joint module. Note: This is derived from the position sensor. Ex: x = api.getSpeed('Y', 'YRA') def getTorque(servoID, moduleID) Returns percentage representation from -100% to 100% of torque used by one of the two servos for a specified joint module. Note: This is derived from current flow in the servo. Ex: x = api.getTorque('Y', 'YRA') def getMoving(servoID, moduleID) Returns true if the servo of a specified joint module moves. Ex: if api.getMoving('Y', 'YRA'): api.output('It is moving!') def getTemperature(servoID, moduleID) Returns the temperature of a specified servo for a specified joint module in degrees Celsius. Ex: api.getTemperature('Y', 'QQA') def getBattery(moduleID) Returns the battery level of a specified joint module. Returns number representation of battery level. Ex: api.getBattery('QQA')

22 PYTHON API

Face App def setFaceEmotion(emotion) Sets the emotional state in the face. Valid arguments: Neutral: 0, Happy: 1, Sad: 2, Angry: 3, Tired: 4 Ex: api.setFaceEmotion('Sad') def getFaceEmotion() Gets the emotional state of the face. Returns an integer for an emotional state; e.g. 1 for “Happy.” Ex: api.getFaceEmotion() def getFaceAcceleration(direction) Gets the acceleration of the smartphone running the face app. Valid directions are X, Y, or Z. Returns acceleration of the selected axis in SI units; e.g. `5.124` m/s^2. Ex: api.getFaceAcceleration('X')

Sounds and Lights def getSoundLevel(milliseconds = 50) Returns the microphone sound level in RMS; default used is 50 ms. Ex: api.getSoundLevel() def playBeep(frequency, duration, channel) Plays back a beep with a given frequency (Hz) for a given duration (s) on a specified channel (0-9). Ex: api.playBeep([255, 0, 0], 'QQA') def playSound(filename) Plays back a sound file from the installation folder: Fable\ resources\app\app\sounds Ex: api.playSound('angry.wav') def setColor(color, moduleID) Sets the light color to a specified module/dongle. The color is an RGB list of numbers scaled from 0-255. Ex: api.setColor([255, 0, 0], 'QQA')

23 PYTHON API

Camera

def takePicture() Saves a picture from the camera in the "Fable pictures\" folder on the desktop. Ex: api.takePicture() def foundSimpleColor(color) Looks in the image for a specific blob of color. Returns true if the color is found. Ex: api.foundSimpleColor([102, 255, 51]) def foundAdvancedColor(color, nuances, size) Looks in the image for a specific blob of color. Returns true if the color is found. Nuances number defines how many nuances of the color to include (0 to 20). Size number is the minimum size of the colored object compared to the whole image (percentage). Ex: api.foundAdvancedColor([153, 102, 255], 10, 30) def getSimpleColorCenter(color) Returns an (x, y) list of the position of the colored blob in the image. (0, 0) is at the center. x and y scales from -100 to 100. Ex: api.getSimpleColorCenter([255, 0, 255])[0] def getAdvancedColorCenter(color, nuances, size) Returns an (x, y) list of the position of the colored blob in the image, with a range of nuances and a minimum size. (0, 0) is at the center; x and y scales from -100 to 100. Ex: api.getAdvancedColorCenter([0, 255, 204], 10, 30)[1] def detectedMotion(threshold) Returns true if motion is found. Threshold is the minimum amount of motion in the image required to trigger a detection (percentage). Ex: api.detectedMotion(2) def getMotionCenter(threshold) Returns an (x, y) list of the motion center. (0, 0) is at the center of the image. Threshold is the minimum amount of motion in the image required to trigger a detection (percentage). Ex: api.getMotionCenter(2)[0]

Setup and Termination

def setup(defaultPort=None, blocking=False) Sets up the API and tries to connect to a dongle. If blocking=True, the program will not terminate before a dongle is connected. Ex: api.setup(blocking=True) Note: This function should be used only when programming stand-alone and not in Fable interface. def terminate() Stops the dongle and sends a command to all modules to go to their default state. Ex: api.terminate() Note: This function should be used only when programming stand-alone and not in Fable interface.

24 PYTHON API

Module Handling def discoverModules() Checks for connected modules and populates a list with their details. Returns a list of found module IDs. Ex: api.discoverModules() Note: This function should be used only when programming stand-alone and not in Fable interface. def getModuleIDs() Returns a list of all module IDs found. Ex: api.getModuleIDs()

Time and Wait def getTime() Returns time elapsed since start of the program in seconds. Ex: api.getTime() def wait(seconds) Creates a pause in the program for a given number of seconds. Ex: api.wait(0.1)

Testing Communication def getConnectionQuality(moduleID) Returns the connection quality of a specified module. Ex: api.getConnectionQuality('QQA') def checkDongleConnection() Checks dongle connection. Returns true if dongle is connected. Ex: api.checkDongleConnection()

Print, Plot, and Data Logs def output(*args) Shows data received as arguments in the output window. Ex: api.output('Hello World', 5) Note: This function should be used only when programming in the Fable interface and not stand-alone. (Use print('Hello World', 5) instead.) def plot(data, label, windowSize = 50, windowTime = 2.5) Draws a time series plot. Adds a data point to the plot that will be shown in the interface. Ex: api.plot(100, 'A') Note: This function should be used only when programming in the Fable interface, not stand-alone. def log(data, filename = 'log.csv') Writes data to a log file, which is placed on the desktop. Ex: api.log(100, filename = 'A')

25 Shop all Fable robots at Pitsco.com/Fable

Pitsco Education is the proud sole US distributor of the Fable robot. For technical support issues or questions, please contact us at: Phone: 800-835-0686 Email: [email protected] Online: www.pitsco.com/support