franka-deskapi 1.0.1

Franka Desk API client library

Franka Desk API

一个由集智联机器人（苏州）有限公司（ Plug and Play Robotics (Suzhou) Co., Ltd.）基于 Franka Desk API 开发的 Python 工具，提供Franka机器人Desk界面的部分功能，如关节、重启、解锁抱闸、切换模式、激活FCI等，便于用户在终端中直接管理Franka机器人的运行状态。

中文版 | English Version

CN | EN

安装

从 PyPI 安装（推荐）

安装

从 PyPI 安装（推荐）

pip install franka-deskapi

安装完成后，您将获得两个命令行工具：

• franka-deskapi-config: 配置管理工具
• franka-deskapi: 交互式机器人控制工具

命令行工具使用

交互式机器人控制工具

安装后，您可以直接使用 franka-deskapi 命令启动交互式机器人控制界面：

# 启动交互式控制界面
franka-deskapi-cn  

在运行 franka-deskapi-cn 时，您可以在后面增加 --robot=fci 等内容指定要连接的机器人。

这个工具提供了一个用户友好的菜单界面，支持以下功能：

• S - 启动流程：解锁刹车 → 执行模式 → 激活FCI
• P - 编程模式：设置为编程模式
• E - 执行模式：设置为执行模式
• U - 解锁刹车：解锁关节刹车
• L - 锁定刹车：锁定关节刹车
• A - 激活FCI：激活FCI
• D - 取消激活FCI：取消激活FCI
• R - 重启机器人：重启机器人
• X - 关机机器人：关机机器人
• B - 打包姿势：移动到打包姿势
• C - 检查状态：检查机器人连接状态
• T - 获取控制权限：获取控制权限
• F - 释放控制权限：释放控制权限
• M - 启动监控：启动持续状态监控
• N - 停止监控：停止持续状态监控
• Z - 重新连接：重新连接机器人
• Q - 退出程序：退出程序

配置管理

初始化用户配置

安装包后，首先需要初始化用户配置文件：

# 方法1: 使用命令行工具
franka-desk-api-config init_config

# 方法2: 使用Python模块
python -m deskapi init_config

# 方法3: 在Python代码中初始化
from deskapi import init_config
init_config()

配置文件将自动复制到 ~/.frankadeskapi/ 目录，方便用户修改。

配置文件位置

• 默认配置: 包内配置文件 (deskapi/desk_api_cfg/)
• 用户配置: ~/.frankadeskapi/ (优先使用)

管理配置

# 列出所有可用的机器人配置
franka-desk-api-config list_robots

# 显示配置目录
franka-desk-api-config show_config_dir

自定义配置目录

可以通过环境变量或参数指定自定义配置目录：

# 使用环境变量
export FRANKA_DESK_API_CONFIG_DIR=/path/to/your/configs

# 使用命令行参数
python your_script.py --config-dir /path/to/your/configs

## 快速开始

### 基本连接测试

```python
from deskapi import create_franka_api_from_args

# 创建 API 实例
franka_api, args = create_franka_api_from_args("测试 Franka 机器人连接")

with franka_api:
    # 获取系统状态
    status = franka_api.get_system_status()
    print("系统状态:", status)
    
    # 获取系统状态信息
    state = franka_api.get_system_state()
    print("系统信息:", state)

重要功能说明

强制获取控制权限

关键特性：使用 force=True 参数强制获取控制权限

在某些情况下，机器人可能已被其他用户或进程控制。此时可以使用 force=True 参数强制获取控制权限：

from deskapi import create_franka_api_from_args

franka_api, args = create_franka_api_from_args("强制控制机器人")

with franka_api:
    # 强制获取控制权限（即使机器人已被其他用户控制）
    franka_api.take_control(force=True)
    
    # 执行需要控制权限的操作
    franka_api.unlock_brakes()
    franka_api.set_mode_execution()
    
    # 操作完成后释放控制
    franka_api.release_control()

⚠️ 安全警告：

• force=True 会强制中断其他用户的控制会话
• 仅在紧急情况或确定需要强制控制时使用
• 在生产环境中谨慎使用此功能

命令行参数

库支持通过命令行参数配置机器人连接：

# 基本用法
python your_script.py --robot robot1

# 指定配置文件
python your_script.py --config /path/to/custom_config.yaml --robot robot2

# 查看帮助
python your_script.py --help

配置文件示例

创建 cfg.yaml 文件：

default_robot: robot1

robots:
  robot1:
    host: "192.168.0.100"
    user: "franka"
    password: "franka123"
  
  robot2:
    host: "192.168.0.101" 
    user: "franka"
    password: "franka123"

API 方法参考

控制相关方法

• take_control(force=False) - 获取控制权限
• release_control() - 释放控制权限
• has_control() - 检查是否拥有控制权限

模式设置方法

• set_mode_execution() - 设置为执行模式
• set_mode_programming() - 设置为编程模式

运动控制方法

• unlock_brakes() - 解锁刹车
• lock_brakes() - 锁定刹车
• move_to_pack_pose() - 移动到打包姿势

系统管理方法

• shutdown() - 关闭机器人
• reboot() - 重启机器人
• enable_fci() - 启用 FCI

公司信息

• 公司: 集智联机器人（苏州）有限公司（ Plug and Play Robotics (Suzhou) Co., Ltd.）
• 网站: https://www.pnprobotics.com
• 邮箱: [e-mail]

许可证

本项目基于 MPL-2.0 许可证。详见 LICENSE 文件。

贡献

欢迎提交 Issue 和 Pull Request！请确保代码符合项目的代码风格和质量标准。

---

Franka 和 Franka Panda 是 Franka Emika GmbH 的注册商标。本项目是独立的第三方实现。

Franka Desk API

A Python tool developed by Plug and Play Robotics (Suzhou) Co., Ltd. based on Franka Desk API, providing some functions of Franka robot Desk interface, such as joint control, reboot, brake release, mode switching, FCI activation, etc., allowing users to directly manage the running status of Franka robots in the terminal.

中文版 | English Version

CN | EN

Installation

Install from PyPI (Recommended)

pip install franka-deskapi

After installation, you will get two command-line tools:

• franka-deskapi-config: Configuration management tool
• franka-deskapi: Interactive robot control tool

Command Line Tools Usage

Interactive Robot Control Tool

After installation, you can directly use the franka-deskapi command to start the interactive robot control interface:

# Start interactive control interface
franka-deskapi-en

When running franka-deskapi-en, you can add --robot=fci to specify the robot to connect to.

This tool provides a user-friendly menu interface with the following functions:

• S - Startup Sequence: Unlock brakes → Execution mode → Activate FCI
• P - Programming Mode: Set to programming mode
• E - Execution Mode: Set to execution mode
• U - Unlock Brakes: Unlock joint brakes
• L - Lock Brakes: Lock joint brakes
• A - Activate FCI: Activate FCI
• D - Deactivate FCI: Deactivate FCI
• R - Reboot Robot: Reboot the robot
• X - Shutdown Robot: Shutdown the robot
• B - Pack Pose: Move to pack pose
• C - Check Status: Check robot connection status
• T - Take Control: Take control of the robot
• F - Release Control: Release control of the robot
• M - Start Monitoring: Start continuous status monitoring
• N - Stop Monitoring: Stop continuous status monitoring
• Z - Reconnect: Reconnect to the robot
• Q - Quit Program: Exit the program

Configuration Management

Initialize User Configuration

After installing the package, you need to initialize the user configuration files first:

# Method 1: Using command line tool
franka-desk-api-config init_config

# Method 2: Using Python module
python -m deskapi init_config

# Method 3: Initialize in Python code
from deskapi import init_config
init_config()

The configuration files will be automatically copied to the ~/.frankadeskapi/ directory for easy user modification.

Configuration File Locations

• Default Configuration: In-package configuration files (deskapi/desk_api_cfg/)
• User Configuration: ~/.frankadeskapi/ (Priority usage)

Manage Configuration

# List all available robot configurations
franka-desk-api-config list_robots

# Show configuration directory
franka-desk-api-config show_config_dir

Custom Configuration Directory

You can specify a custom configuration directory through environment variables or parameters:

# Using environment variable
export FRANKA_DESK_API_CONFIG_DIR=/path/to/your/configs

# Using command line parameter
python your_script.py --config-dir /path/to/your/configs

Quick Start

Basic Connection Test

from deskapi import create_franka_api_from_args

# Create API instance
franka_api, args = create_franka_api_from_args("Test Franka Robot Connection")

with franka_api:
    # Get system status
    status = franka_api.get_system_status()
    print("System Status:", status)
    
    # Get system state information
    state = franka_api.get_system_state()
    print("System Information:", state)

Important Features

Force Take Control

Key Feature: Use force=True parameter to force take control

In some cases, the robot may already be controlled by other users or processes. In this situation, you can use the force=True parameter to forcefully take control:

from deskapi import create_franka_api_from_args

franka_api, args = create_franka_api_from_args("Force Control Robot")

with franka_api:
    # Force take control (even if the robot is already controlled by other users)
    franka_api.take_control(force=True)
    
    # Execute operations that require control
    franka_api.unlock_brakes()
    franka_api.set_mode_execution()
    
    # Release control after operations are completed
    franka_api.release_control()

⚠️ Security Warning:

• force=True will forcibly interrupt other users' control sessions
• Only use in emergency situations or when you are sure you need to force control
• Use this feature with caution in production environments

Command Line Arguments

The library supports configuring robot connections through command line arguments:

# Basic usage
python your_script.py --robot robot1

# Specify configuration file
python your_script.py --config /path/to/custom_config.yaml --robot robot2

# View help
python your_script.py --help

Configuration File Example

Create a cfg.yaml file:

default_robot: robot1

robots:
  robot1:
    host: "192.168.0.100"
    user: "franka"
    password: "franka123"
  
  robot2:
    host: "192.168.0.101" 
    user: "franka"
    password: "franka123"

API Method Reference

Control Related Methods

• take_control(force=False) - Take control of the robot
• release_control() - Release control of the robot
• has_control() - Check if you have control of the robot

Mode Setting Methods

• set_mode_execution() - Set to execution mode
• set_mode_programming() - Set to programming mode

Motion Control Methods

• unlock_brakes() - Unlock joint brakes
• lock_brakes() - Lock joint brakes
• move_to_pack_pose() - Move to pack pose

System Management Methods

• shutdown() - Shutdown the robot
• reboot() - Reboot the robot
• enable_fci() - Enable FCI

Company Information

• Company: Plug and Play Robotics (Suzhou) Co., Ltd.
• Website: https://www.pnprobotics.com
• Email: [e-mail]

License

This project is licensed under the MPL-2.0 License. See the LICENSE file for details.

Contributing

Issues and Pull Requests are welcome! Please ensure that the code conforms to the project's code style and quality standards.

---

Franka and Franka Panda are registered trademarks of Franka Emika GmbH. This project is an independent third-party implementation.