🐍Python API

How to use python scripts to have fun with Nybble😼 or Bittle🐶

Preparation

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

2. Install pyserial library (version 3.5)

Connect the serial port

Generally, when using a USB adapter to connect to the robot, there is only one serial port number:

USB serial port number

When using the Bluetooth module, there are two serial port numbers:

Bluetooth serial port number

Open Terminal (such as Anaconda Prompt), enter the path where the script is located (***\serialMaster), you can use the following command to run the script, the script will automatically identify the serial port number at the very beginning, and complete the connection.

Run the script

Method 1: Run the ardSerial.py

***\serialMaster>python3 ardSerial.py kbalance

Parameters: kbalance is a serial command representing the robot's skill.

Of course, you can also run this script without any parameters:

***\serialMaster>python3 ardSerial.py

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:

__main__ - INFO - port[0] is COM11
__main__ - INFO - port[1] is COM5
__main__ - INFO - port[2] is COM10
Waiting for the robot to booting up
Waiting for the robot to booting up
['b', '\n* Start *\nBittle\nReady!\np\n']
Adding COM5
['b', '\n* Start *\nBittle\nReady!\np\n']
Adding COM11
__main__ - INFO - Connect to usb serial port:
__main__ - INFO - COM5
__main__ - INFO - COM11

When the script formally starts running, the following prompt information is printed out:

You can type 'quit' or 'q' to exit.

Next, you can enter serial commands in Terminal to control the robot to do various interesting actions 😃 e.g.

Kbalance        # Command to control the robot to stand normally
m 0 -30 0 30    # Command to control the robot head to swing left and right

Method 2: Run the custom scheduler, example.py

***\serialMaster>python3 example.py

The list testSchedule in example.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:

['kbalance', 2]

• 'kbalance' 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 in the form of ASCII strings.

Using the 'M' control command, the index number of joint servo and rotation angle values are stored in the form of a byte string, that is, 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 certain 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: 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 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 at one time, and these joint servo rotation commands are executed SEQUENTIALLY, not at the same time. The joint angles are treated as ASCII characters, so they can be entered directly by humans.

The meaning of this example is: the joint servo with index number 0 is first rotated to the 45-degree position, then rotated 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 at one time, and these joint servo rotation commands are executed AT THE SAME TIME. The joint angles are treated as ASCII characters, so they can be entered directly by humans.

The meaning of this example is the joint servos with index numbers 8, 9 are rotated to the -15, -20 degree positions at the same time. 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, 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 in the form of 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 in the form of 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 the music melody is played. 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: 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 realtime

• 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

For the description of other serial port commands, please refer to Serial Commands.

Please help Nybble and Bittle find their sparks. Wish you have fun! 😍