Python API

How to use python scripts to have fun with the robots

Preparation

Install python (version≥ 3.6, such as Anaconda3-5.2.0-Windows-x86_64.exe)
Install pyserial library (version 3.5)

Connect the serial port

When using a to connect to the or USB type-C data cable to connect to the , there should be only one serial port number:

When using the Bluetooth function, there can be two serial port numbers:

Download a fresh OpenCat repository from GitHub:

Please utilize GitHub’s version control feature. Otherwise, make sure you download the WHOLE OpenCat FOLDER every time.

Open a Terminal (such as Anaconda Prompt) and enter the path where the Python API is located (***/OpenCatPythonAPI). Then, run the two example scripts in the folder(petoiRobotExample.py and ardSerialExample.py). The script will automatically identify the serial port number at the beginning and complete the connection.

ardSerial.py contains the core communication functions. robot.py is a wrapper module that provides more user-friendly functions. Our Mind+ coding blocks is a graphical UI for this library.

Run the scripts

Run the ardSerialExample.py

***\OpenCatPythonAPI>python3 ardSerialExample.py

ardSerialExample.py demonstrates how to call the functions defined in ardSerial.py（in the ***/OpenCatPythonAPI/PetoiRobot）

The list testSchedule in ardSerialExample.py is used to test various serial port commands. Run the following script code to see the execution effect of each serial port command in the list:

for task in testSchedule:
    wrapper(task)

You can also refer to the content of the testSchedule list (in ***/serialMaster/demos/hlw.py), write a list of behaviors according to your actual needs, and realize your creativity. 🤩 It was used in a Halloween puppet show.

Note: When running the scripts under the path of /serialMaster/demos, you must first use the "cd demos" command to enter the path where the scripts are located (/serialMaster/demos) and then use the python3 command to run the script (e.g., "python3 hlw.py")

Explanation of the serial port commands in the list testSchedule:

['kup', 2]

'kup' indicates the command to control Bittle to stand normally
2 indicates the postponed time after finishing the command in seconds.
m indicates the command to control the rotation of the joint servo
0 indicates the index number of joint servo
-20 indicates the rotation angle (this value is expressed relative to the reference 0 value used after calibration). The unit is in degrees.
1.5 indicates the postponed time after finishing the command in seconds. It can be a float number.

['m', [0, 45, 0, -45, 0, 45, 0, -45], 2]

['M', [0, 45, 0, -45, 0, 45, 0, -45], 2]

The meaning of this example is the same as the previous command.

Using the 'm' control command, the index number of joint servo and rotation angle values are stored as ASCII strings.

Using the 'M' control command, the index number of joint servo and rotation angle values is stored as a byte string, a byte sequence (binary form).

['d', 2]

d indicates the command to put the robot down and shut down the servos
2 indicates the postponed time after finishing the command in seconds

['c', 2]

c indicates the command to enter calibration mode
2 indicates the postponed time after finishing the command in seconds. After these motion commands are completed, the next command will be executed after a 2-second delay.

['c', [0, -9], 2]

c indicates the command to enter calibration mode
0 indicates the index number of joint servo
-9 indicates the rotation angle. The unit is in degrees.
2 indicates the postponed time after finishing the command in seconds

Using this format, you can enter the calibration mode to calibrate the angle of a specific joint servo. Note: If you want the correction value in this command to take effect, you need to enter the "s" command after executing this command.

The meaning of this example is that the joint servo with serial number 0 rotates -9 degrees. After these motion commands are completed, the next command will be executed after a 2-second delay.

['m', [0, -20], 1.5]

m indicates the command to control the rotation of the joint servo
0 indicates the index number of joint servo
-20 indicates the rotation angle (this angle refers to the origin rather than the additive). The unit is in degrees.
1.5 indicates the postponed time after finishing the command in seconds. It can be a float number.

['m', [0, 45, 0, -45, 0, 45, 0, -45], 2]

Using this format, multiple joint servo rotation commands can be issued in a list. These commands are executed sequentially, not simultaneously. The joint angles are treated as ASCII characters so humans can enter them directly.

This example means that the joint servo with index number 0 is first rotated to the 45-degree position, then to the -45-degree position, and so on. After these motion commands are completed, the following command will be executed after a 2-second delay.

['i', [ 8, -15, 9, -20], 2]

Using this format, multiple joint servo rotation commands can be issued in a list and executed AT THE SAME TIME. The joint angles are treated as ASCII characters so humans can enter them directly.

The meaning of this example is that the joint servos with index numbers 8 and 9 are rotated to the -15 and -20 degree positions simultaneously. After these motion commands are completed, the following command will be executed after a 2-second delay.

['M', [8, 50, 9, 50, 10, 50, 11, 50, 0, 0], 3]

M indicates the command to rotate multiple joint servos SEQUENTIALLY. The angles are encoded as BINARY numbers for efficiency.
8, 9, 10, 11, and 0 indicate the index numbers of joint servos
50, 50, 50, 50, 0 indicate the rotation angle (this angle refers to the origin rather than additive ). The unit is in degrees
3 indicates the postponed time after finishing the command in seconds

['I', [8, 50, 9, 50, 10, 50, 11, 50, 0, 0], 3]

The meaning of this example is the same as the previous command.

Using the 'i' control command, the index number of the joint servo and rotation angle values are stored as ASCII strings.

Using the 'I' (the uppercase of the letter 'i')control command, the index number of the joint servo and rotation angle values are stored as a byte string.

['I', [20, 0, 0, 0, 0, 0, 0, 0, 45, 45, 45, 45, 36, 36, 36, 36], 5]

'I' indicates the command to control all joint servos to rotate AT THE SAME TIME (currently, the command supports 16 degrees of freedom, that is, 16 servos). The angles are encoded as BINARY numbers for efficiency.
20,0,0,0,0,0,0,0,45,45,45,45,36,36,36,36 indicate the rotation angle of each joint servo corresponding to 0-15 (this angle refers to the origin, rather than additive). The unit is in degrees.
5 indicates the postponed time after finishing the command. The unit is in seconds.

Here, 'l' is the lowercase form of the letter 'L'.

['b', [10,2], 2]

b indicates the command to control the buzzer to beep
10 indicates the music tone
2 indicates the lengths of duration, corresponding to 1/duration second
2 indicates the postponed time after completing the tone. The unit is in seconds

['b', [0, 1, 14, 8, 14, 8, 21, 8, 21, 8, 23, 8, 23, 8, 21, 4, 19, 8, 19, 8, 18, 8, 18, 8, 16, 8, 16, 8, 14, 4], 3]

b indicates the command to control the buzzer to beep
0, 14, 14, 21... indicate the music tones
1, 8, 8, 8 indicates the lengths of duration, corresponding to 1/duration second
The last '3' indicates the postponed time after playing the music melody. The unit is in seconds.

Using this format, multiple-tone commands can be issued at once, and a simple melody can be played.

The meaning of this example is to play a simple melody and delay 3 seconds after the music melody is played.

ck = [

-3, 0, 5, 1,

0, 1, 2,

45, 0, 0, 0, 0, 0, 0, 0, 45, 35, 38, 50, -30, -10, 0, -20, 6, 1, 0, 0,

-45, 0, 0, 0, 0, 0, 0, 0, 35, 45, 50, 38, -10, -30, -20, 0, 6, 1, 0, 0,

0, 0, 0, 0, 0, 0, 0, 0, 30, 30, 30, 30, 30, 30, 30, 30, 5, 0, 0, 0,

]

['K', ck, 1]

'K' indicates the skill data to send to Bittle in real-time
The skill array is sent to the robot on the go and executed locally on the robot
You may insert the skills in the skill library or InstinctX.h in this format

Run the petoiRobotExample.py

***\OpenCatPythonAPI>python3 petoiRobotExample.py

petoiRobotExample.py demonstrates how to call the functions defined in robot.py（in the ***/OpenCatPythonAPI/PetoiRobot）

Available APIs

Below are the supported function calls in the library (robot.py):

# use to print debug information
def printH(head, value)

# deactivate the Gyro
def deacGyro()

# get the current angle list of all joints
def getAngleList()
    return angleList

# get the current angle value of a joint 
def getCurAng(index)

# creat an absolut value list
def absValList(num1, num2)

# rotate angle from relative value to absolute value
# creat an offset value list
def relativeValList(index, symbol, angle)

# rotate the joints sequentially or simultaneously
def rotateJoints(token, var, delayTime)

# play tones
def play(token, var, delayTime)

# encode the character to bytes
def encode(in_str, encoding='utf-8')
 
def printSkillFileName()

# open the serial port 
def openPort(port)

# auto connect serial ports
def autoConnect()

# send a short skill string
def sendSkillStr(skillStr, delayTime)

def loadSkill(fileName, delayTime):

# send a command string
def sendCmdStr(cmdStr, delayTime)

def sendLongCmd(token, var, delayTime)

# get the analog value of a pin
def readAnalogValue(pin)

# get the digital value of a pin
def readDigitalValue(pin)

# set the analog value of a pin
def writeAnalogValue(pin, val)
 
# set the digital value of a pin
def writeDigitalValue(pin, val)

# close the serial port
def closePort()

Here is a sample code in the petoiRobotExample.py:

#!/usr/bin/python3
#  -*- coding: UTF-8 -*-

# MindPlus
# Python
from PetoiRobot import *

autoConnect()
# The list format is [joint index, angle, joint index, angle...]
sendSkillStr('ksit',3)
sendSkillStr('kup',3)
rotateJoints('M', absValList(0, 60), 1)
# The list format is [note, duration, note, duration...]
play('B', [14,4,14,4,21,4,21,4,23,4,23,4,21,2], 1)
closePort()

When the system recognizes that there are multiple serial port numbers, the script will automatically identify all serial port numbers that have been connected to the robot (you can send serial commands to multiple robots at the same time). When the script starts running, it will print out the following prompt information:

2024-11-15 15:14:51,357 PetoiRobot.ardSerial - INFO - ardSerial date: Jun. 20, 2024
Mind+ date:  Oct 18, 2023
C:\Users\***\.config\Petoi already exists
C:\Users\***\.config\Petoi\SkillLibrary\Bittle already exists
C:\Users\***\.config\Petoi\SkillLibrary\Nybble already exists
C:\Users\***\.config\Petoi\SkillLibrary\BittleR already exists

*** Available serial ports: ***
COM3
Bittle X
B02_241105
2024-11-15 15:14:54,634 PetoiRobot.ardSerial - INFO - Connect to the serial port list:
2024-11-15 15:14:54,635 PetoiRobot.ardSerial - INFO - COM3
modelName: Bittle
*** The skill names you can call are as follows: ***
*  skillFileName
******************************
2024-11-15 15:15:05,134 PetoiRobot.ardSerial - INFO - close the serial port.

Please help the robots find their sparks. Wish you have fun! 😍

PreviousNested task queue and signal generator Next8266 MicroPython controller

Last updated 3 months ago

Was this helpful?