Getting Started

This section will help you quickly master the basic structure and usage of the Python API.

1. Set Up the Development Environment

Before you begin development, ensure your Python environment meets the following requirements:

• Operating System: Ubuntu 22 or later.
• Python: Version 3.10.

2. Install the alphabot Module

After setting up the Python development environment, you can install the alphabot module using the pip tool.

1. Open a terminal and navigate to the python directory of the extracted SDK package.

   cd python

2. Install the alphabot module via pip.

   pip install .

3. Understand the Module Structure

You can browse the .pyi interface files in the alphabot directory to understand the interface module organization.

The alphabot module provides several ready-to-use classes, which can be imported via from alphabot import <class_name>.

Class Name	Description	Module
ArmFactory	Creates a robotic arm instance	alphabot.arm
ArmFactoryParam	Describes robotic arm parameters
ArmInterface	Main interface for robotic arm control
ArmForceSensor	Force sensor data
ArmRealtimeState	Real-time state of the robotic arm
GripperState	Gripper state
JointState	Joint state
PeripheralReadWriteParams	Configures Modbus communication parameters
ChassisFactory	Creates a chassis instance	alphabot.chassis
ChassisInterface	Main interface for chassis control
ChassisBattery	Chassis battery information
ChassisPoint32	Footprint point position
ChassisPose2D	2D pose of the chassis
ChassisPoseSpeed	Chassis pose and velocity
ChassisState	Chassis state
ChassisStatusCode	Chassis status codes
ChassisTransformStamped	Data related to static transforms
ChassisTwist	Chassis twist
ChassisOperationState	Chassis operation state
NavState	Chassis navigation information
RobotBit	Chassis bit information
HeadFactory	Creates a head instance	alphabot.head
HeadInterface	Main interface for head control
AbcHeadState	Head joint state
TorsoFactoryPose4D	Creates a torso instance	alphabot.torso
TorsoInterfacePose4D	Main interface for torso control
AbcTorsoState	Torso joint state
SensorFactory	Creates sensors and depth cameras	alphabot.sensor
SyncDataPackage	Synchronized sensor data package
SyncMode	Synchronization mode
SyncPolicy	Synchronization policy
RGBData	RGB image data
RGBDData	RGB + Depth image data
DepthCamera	Depth camera
DepthSensorParam	Depth sensor parameters
EStopMonitor	Emergency stop button monitor	alphabot.estop
EStopMConfig	Monitor configuration
ESState	Emergency stop button state
ArmKinematics	Robotic arm kinematics	alphabot.algo
ArmType	Robotic arm type
TorsoKinematics	Torso kinematics
admittance_control_law	Admittance control law
AbcErrorCode	Error codes	alphabot.core
AbcTorsoPose4D	Torso pose
ArmCurrentStatus	Current robotic arm status code
Euler	Euler angles
Pose	3D pose
Position	3D position
Quaternion	Quaternion
SensorStatus	Sensor status
SensorType	Sensor type

4. Refer to Example Programs

Refer to the example programs under the examples directory to learn how to call core interfaces.

For example, the sample code in Python\examples\arm\arm_factory_example.py is shown below.

import sys
import os
from alphabot import ArmFactory, ArmFactoryParam


def main():
    """Main function"""
    # Parameter validation
    if len(sys.argv) < 2:
        print(f"Usage: {sys.argv[0]} <configuration_file_path>")
        print(f"Example: {sys.argv[0]} config/left_arm.json")
        return 1

    config_path = sys.argv[1]

    print("===== ArmFactory Sample Program =====")

    try:
        print("\n----- Method 1: Creating a Robotic Arm Using Parameters -----")
        # Configure robotic arm parameters
        param = ArmFactoryParam({
            "arm_type": "realman",
            "arm_name": "right_arm",
            "ip": "192.168.1.18",
            "port": "8080",
            "udp_ip": "192.168.1.102",
            "udp_port": "8089",
            "udp_cycle": "5"
        })

        # Create a robotic arm instance form arm parameters
        arm1 = ArmFactory.create_arm(param)
        if not arm1:
            print("Failed to create robotic arm instance")
            return 1

        print(f"Successfully created robotic arm: {arm1}")

        print("\n----- Method 2: Creating a Robotic Arm Using Configuration File -----")
        # Create a robotic arm instance from configuration file
        arm2 = ArmFactory.create_arm_from_config(config_path)
        if not arm2:
            print("Failed to create robotic arm instance from configuration file")
            return 1

        print(f"Successfully created robotic arm from configuration file: {arm2}")

        return 0

    except Exception as e:
        print(f"Exception occurred: {e}")
        return 1


if __name__ == "__main__":
    sys.exit(main())

Through the above example program, you can quickly learn how to create an instance of the robotic arm interface and connect to the robotic arm. Other example programs follow similar structures and calling conventions. Please refer to more example programs for further learning.

5. Run the Program

The following uses Python\examples\arm\arm_factory_example.py as an example to explain the execution process.

1. Open a terminal and navigate to the directory where the example program is located.

   cd python/examples/arm

2. Execute the python command to run the program. This example requires passing the robotic arm configuration file path as a parameter.

   python arm_factory_example.py ../config/left_arm.json

The execution steps for other example programs are similar; follow the steps above.

Through this section, you have learned the basic structure and usage of the Python interface. We recommend further exploring other example programs and developing with reference to the Python API documentation.