Metadata-Version: 2.4
Name: roarm_sdk
Version: 0.1.1
Summary: waveshare roarm sdk.
Home-page: https://github.com/waveshareteam/waveshare_roarm_sdk.git
Author: waveshareteam
Author-email: 2849678712@qq.com
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyserial
Requires-Dist: requests
Requires-Dist: simplejson
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Waveshare Roarm SDK

![Python 2.7](https://img.shields.io/badge/Python-v2.7%5E-green?logo=python)
![Python 3](https://img.shields.io/badge/Python-v3%5E-green?logo=python)

This is a python API for serial or http communication with waveshare roarm and controlling it.

| Series | Models | Image |
|--------|--------|-------|
| RoArm-M2 | [**RoArm-M2-S**](https://www.waveshare.com/roarm-m2-s.htm), [**RoArm-M2-Pro**](https://www.waveshare.com/roarm-m2-s.htm) | <a href="https://www.waveshare.com/roarm-m2-s.htm"><img src="./images/roarm_m2.png" alt="RoArm-M2" width="300" height="200"/></a> |
| RoArm-M2 | [**RoArm-M2-GA**](https://www.waveshare.com/roarm-m2-ga.htm) | <a href="https://www.waveshare.com/roarm-m2-ga.htm"><img src="./images/roarm_m2_ga.jpg" alt="RoArm-M2-GA" width="300" height="200"/></a> |
| RoArm-M3 | [**RoArm-M3-S**](https://www.waveshare.com/roarm-m3.htm), [**RoArm-M3-Pro**](https://www.waveshare.com/roarm-m3.htm) | <a href="https://www.waveshare.com/roarm-m3.htm"><img src="./images/roarm_m3.png" alt="RoArm-M3" width="300" height="200"/></a> |

Model mapping:

- **RoArm-M2-S / RoArm-M2-Pro**: `roarm_type="roarm_m2"`, `gripper_type="angular_direct"` (default)
- **RoArm-M2-GA**: `roarm_type="roarm_m2"`, `gripper_type="angular_gear"`
- **RoArm-M3-S / RoArm-M3-Pro**: `roarm_type="roarm_m3"` (single gripper type; `gripper_type` usually omitted)

## Installation
### Pip install

```bash
pip install roarm-sdk==0.1.1
```

### Source code

```bash
git clone https://github.com/waveshareteam/waveshare_roarm_sdk.git <your-path>
cd <your-path>/waveshare_roarm_sdk
# Install
[sudo] python2 setup.py install
# or
[sudo] python3 setup.py install
```

## Usage:

```python
from roarm_sdk.roarm import roarm

# for roarm_m2 Serial communication example
roarm = roarm(roarm_type="roarm_m2", port="/dev/ttyUSB0", baudrate=115200)

# for roarm_m3 Serial communication example
#roarm = roarm(roarm_type="roarm_m3", port="/dev/ttyUSB0", baudrate=115200)

# Optional: gripper type and debug
# gripper_type: "angular_direct" (default, invert gripper) or "angular_gear" (pass-through)
# debug: False (default, no print) or True (print TX/RX data)
# RoArm-M2-GA example:
#roarm = roarm(roarm_type="roarm_m2", port="/dev/ttyUSB0", baudrate=115200, gripper_type="angular_gear", debug=True)
```

Constructor notes:

- **gripper_type** – `"angular_direct"` (default) or `"angular_gear"`. Default keeps legacy invert behavior; `angular_gear` sends/reads gripper values without invert. Omit it for backward compatibility.
- **RoArm-M2-GA** – use `roarm_type="roarm_m2"` with `gripper_type="angular_gear"`.
- **debug** – `False` (default) or `True`. When `True`, print serial/HTTP payload data.
- **host** – HTTP mode is **control-only** (send commands). Use serial for feedback reads and drag teach.

The [`demo`](./demo) directory stores some test case files.

You can find out which interfaces roarm_sdk provides in [`./doc/README.md`](./doc/README.md).

![jaywcjlove/sb](https://jaywcjlove.github.io/sb/lang/chinese.svg)   ![jaywcjlove/sb](https://jaywcjlove.github.io/sb/lang/english.svg)

[roarm_m2 api 说明](./doc/roarm_m2_zh.md) | [roarm_m2 api Description](./doc/roarm_m2_en.md)

[roarm_m3 api 说明](./doc/roarm_m3_zh.md) | [roarm_m3 api Description](./doc/roarm_m3_en.md)# roarm_sdk

**This is python api for Waveshare roarm product**

We support Python2, Python3.5 or later.

[roarm_m2 api 说明](./roarm_m2_zh.md) | [roarm_m2 api Description](./roarm_m2_en.md)

[roarm_m3 api 说明](./roarm_m3_zh.md) | [roarm_m3 api Description](./roarm_m3_en.md)

<details>
<summary>Catalogue:</summary>

<!-- vim-markdown-toc GFM -->

- [roarm_sdk](#roarm_sdk)
    - [roarm](#roarm)
        - [Constructor](#constructor)
        - [echo_set(cmd)](#echo_setcmd)
        - [middle_set()](#middle_set)
        - [move_init()](#move_init)
        - [led_ctrl(led)](#led_ctrlled)
        - [breath_led(duration,steps)](#breath_ledduration-steps)
        - [torque_set(cmd)](#torque_setcmd)
        - [dynamic_adaptation_set(mode,torques)](#dynamic_adaptationset-mode-torques)
        - [feedback_get()](#feedbackget)
        - [joint_radian_ctrl(joint,radian,speed,acc)](#joint_radian_ctrljointradianspeedacc)
        - [joints_radian_ctrl(radians,speed,acc)](#joints_radian_ctrlradianspeedacc)
        - [joints_radian_get()](#joints_radian_get)
        - [joint_angle_ctrl(joint,angle,speed,acc)](#joint_angle_ctrljointanglespeedacc)
        - [joints_angle_ctrl(angles,speed,acc)](#joints_angle_ctrlanglespeedacc)
        - [joints_angle_get()](#joints_angle_get)
        - [gripper_mode_set(mode)](#gripper_mode_setmode)
        - [gripper_radian_ctrl(radian,speed,acc)](#gripper_radian_ctrlradianspeedacc)
        - [gripper_angle_ctrl(angle,speed,acc)](#gripper_angle_ctrlanglespeedacc)
        - [gripper_radian_get()](#gripper_radian_get)
        - [gripper_angle_get()](#gripper_angle_get)
        - [pose_ctrl(pose)](#pose_ctrlpose)
        - [pose_get()](#pose_get)
        - [drag_teach_start(filename)](#drag_teachstartfilename)
        - [drag_teach_replay(filename)](#drag_teachreplayfilename)
        - [wifi_on_boot(wifi_cmd)](#wifi_on_bootwifi_cmd)
        - [ap_set(ssid,password)](#ap_setssidpassword)
        - [sta_set(ssid,password)](#sta_setssidpassword)
        - [apsta_set(ap_ssid,ap_password,sta_ssid,sta_password)](#apstasetap_ssidap_passwordstassidsta_password)
        <!-- - [wifi_info_get()](#wifi_info_get) -->
        - [wifi_config_creat_by_status()](#wifi_config_creat_by_status)
        - [wifi_config_creat_by_input(ap_ssid,ap_password,sta_ssid,sta_password)](#wifi_config_creat_by_inputap_ssidap_passwordstassidsta_password)
        - [wifi_stop()](#wifi_stop)
        - [disconnect()](#disconnect)

<!-- vim-markdown-toc -->
</details>

# roarm

### Constructor

Create a `roarm` instance.

```python
roarm = roarm(
    roarm_type="roarm_m2",   # or "roarm_m3"
    port="/dev/ttyUSB0",
    baudrate=115200,
    # host="192.168.4.1",    # use host for HTTP instead of serial
    gripper_type="angular_direct",  # or "angular_gear"
    debug=False,
)
```

* **Parameters**

  * **roarm_type** – `"roarm_m2"` or `"roarm_m3"`
  * **port** / **baudrate** – serial port settings; or use **host** for HTTP (control send only; feedback / drag teach need serial)
  * **gripper_type** – `"angular_direct"` (default) or `"angular_gear"` (mainly for RoArm-M2-GA; RoArm-M3 has one gripper and usually omits this)
    * `"angular_direct"`: invert gripper angle/radian (legacy behavior; RoArm-M2-S / M2-Pro)
    * `"angular_gear"`: pass through without invert (RoArm-M2-GA); joint radians can still use `0` closed / `1.57` open
  * **debug** – `False` (default, no print) or `True` (print TX/RX data)

### echo_set(cmd)

Set echo 
    0 : disable echo
    1  : enable echo
* **Parameters**

  * **cmd** –  : [0,1], type : int

### middle_set()

Set current position to neutral calibration

### move_init()

Move roarm to home position

### led_ctrl(led)

Ctrl led brightness
* **Parameters**

  * **led** –  : [0,255], type : int

        0: darkest
        255: brightest

### breath_led(duration,steps)

Set breath_led
* **Parameters**

  * **duration** –  : breath duration, type : float

  * **steps** –  : breath steps, type : int

### torque_set(cmd)

Set the torque of the robot
* **Parameters**

  * **cmd** –  : [0,1], type : int

        0: disable torque
        1: enable torque

### dynamic_adaptation_set(mode,torques)

Set the dynamic adaptation of the robot
* **Parameters**

  * **mode** –  : [0,1], type : int

        0: disable dynamic adaptation
        1: enable dynamic adaptation

  * **torques** –  : [0,1000], type : list

### feedback_get()

Get the feedback of the robot
* **Returns**

  * **list** –  : a list of roarm feedback, type : List[float]

### joint_radian_ctrl(joint,radian,speed,acc)

Control the joint radian of the robot
* **Parameters**

  * **joint** –  : id, type : int

  * **radian** –  : value, type : float

  * **speed** –  : [1,4096], type : int

  * **acc** –  : [1,254], type : int  

### joints_radian_ctrl(radians,speed,acc)

Control the joints radian of the robot
* **Parameters**

  * **radians** –  : a list of radian, type : List[float]

  * **speed** –  : [1,4096], type : int

  * **acc** –  : [1,254], type : int  

### joints_radian_get()

Get the joints radian of the robot
* **Returns**

  * **list** –  : a list of all radians, type : List[float]

### joint_angle_ctrl(joint,angle,speed,acc)

Control the joint angle of the robot
* **Parameters**

  * **joint** –  : id, type : int

  * **angle** –  : value, type : float

  * **speed** –  : [1,4096], type : int

  * **acc** –  : [1,254], type : int  

### joints_angle_ctrl(angles,speed,acc)

Control the joints angle of the robot
* **Parameters**

  * **angles** –  : a list of angle, type : List[float]

  * **speed** –  : [1,4096], type : int

  * **acc** –  : [1,254], type : int  

### joints_angle_get()

Get the joints angle of the robot
* **Returns**

  * **list** –  : a list of all angles, type : List[float]

### drag_teach_start(filename)

Start the drag teach of the robot
* **Parameters**

  * **filename** –  : filename, type : str

### drag_teach_replay(filename)

Replay the drag teach of the robot
* **Parameters**

  * **filename** –  : filename, type : str
  
### gripper_mode_set(mode)

Set the gripper mode of the robot
* **Parameters**

  * **mode** –  : [0,1], type : int

        0: gripper
        1: wrist

### gripper_radian_ctrl(radian,speed,acc)

Control the gripper radian of the robot
* **Parameters**

  * **radian** –  : value, type : float

  * **speed** –  : [1,4096], type : int

  * **acc** –  : [1,254], type : int  

### gripper_angle_ctrl(angle,speed,acc)

Control the gripper angle of the robot
* **Parameters**

  * **angle** –  : value, type : float

  * **speed** –  : [1,4096], type : int

  * **acc** –  : [1,254], type : int

### gripper_radian_get()

Get the gripper radian of the robot
* **Returns**

  * **float** –  : gripper radian, type : float

### gripper_angle_get()

Get the gripper angle of the robot
* **Returns**

  * **float** –  : gripper angle, type : float

### pose_ctrl(pose)

Control the pose of the robot
* **Parameters**

  * **pose** –  : a list of coords value, type : List[float]

### pose_get()

Get the pose of the robot
* **Returns**

  * **list** –  : a list of coords value, type : List[float]

### wifi_on_boot(wifi_cmd)

Set the wifi on boot of the robot
* **Parameters**

  * **wifi_cmd** –  : [0,3], type : int

        0 : WIFI close
        1 : AP model
        2 : STA model
        3 : AP + STA model

### ap_set(ssid,password)

Set the ap of the robot
* **Parameters**

  * **ssid** –  : ssid, type : str

  * **password** –  : password, type : str

### sta_set(ssid,password)

Set the sta of the robot
* **Parameters**

  * **ssid** –  : ssid, type : str

  * **password** –  : password, type : str

### apsta_set(ap_ssid,ap_password,sta_ssid,sta_password)

Set the apsta of the robot
* **Parameters**

  * **ap_ssid** –  : ap ssid, type : str

  * **ap_password** –  : ap password, type : str

  * **sta_ssid** –  : sta ssid, type : str

  * **sta_password** –  : sta password, type : str

### wifi_config_creat_by_status()

Creat the wifi config by status of the robot

### wifi_config_creat_by_input(ap_ssid,ap_password,sta_ssid,sta_password)

Creat the wifi config by input of the robot

### wifi_stop()

Stop the wifi of the robot

### disconnect()

Disconnect the roarm

# Example

More demo can go to [here](../demo).
