en:server_docs:robot_info:robot_robot_info

Get Robot Information

Overview

  • This API is used to get robot information;

Authorization

Data Dimension Authorization Enterprise-level Authorization This API requires enterprise-level authorization. Both enterprise-level and agent-level authorization accounts can call this API. Please refer to Authorization Methods.
Interface Dimension Authorization Default Authorization This API is granted by default, so you don't need to apply for interface dimension authorization separately for your authorization account. Please refer to Authorization Methods.

Request

Request Entry Point

Region Entry Point
China Region https://openapi.orionstar.com
Europe Region https://global-openapi.orionstar.com
USA Region https://us-openapi.orionstar.com
Japan Region https://jp-openapi.orionstar.com

Request Protocol

HTTP URL Path /v1/robot/robot_info
HTTP Method GET

Common Request Headers

Parameter Type Required Description
Authorization string Yes
  • Access token
  • Format: Bearer access_token
  • Example: Bearer T.WcnhSdYj-kwVBpP27LRQrw.OBt95zE4TH-OPzIX6OkEWPo4rbR6s.ori-67facfd90b2744220a5eae850e51
  • Please refer to: Authentication Methods

Request URL Parameters

Parameter Type Required Description
robot_sn string Yes Robot SN
is_report_status int No Whether to get the current status information reported by the robot (such as current battery level, current task, and current location), default is not to get.
0: No
1: Yes
is_report_task_event int No Whether to get the task event information reported by the robot, default is not to get. It works only when the report_task_type parameter is combined. Only the task events reported in the last 24 hours can be obtained.
0: No
1: Yes
report_task_type string No

The task types of the robot's reported task events that need to be obtained, separated by commas. It is only effective when the parameter is_report_task_event=1. Supported task types are as follows:

  • meals_deliver_task-deliver
    • Meal delivery task to the table
  • meals_deliver_task-return
    • Meal delivery return task

Request cURL Example

# Please replace the entry point with yours according to your region
curl --location 'https://global-openapi.orionstar.com/v1/robot/robot_info?robot_sn=test_sn' \
     --header 'Authorization: Bearer YOUR-ACCESS-TOKEN'

Response

Common Response Body

Parameter Type Description
code int Error code. 0 means success, non-zero means failure, Please refer to Error Codes.
msg string Error description. When there is a failure, a specific error description will be provided.
req_id string Log tracking ID. When encountering problems that require assistance from OrionStar, please provide this tracking ID value.
data object Business data object, see below for details Response Body Data Object.

Response Body Data Object

Parameter Type Description
corp object The corp enterprise information object to which the robot belongs. Please refer to corp - Enterprise Information Object.
robot object robot robot information object. Please refer to robot - Robot Information Object.
robot_report_status object The object is the current status information reported by the robot, which is returned only when the request parameter is_report_status=1. Please refer to robot_report_status - Robot Current Status Information.
robot_task_list array An array of robot's current task event information objects, where each element in the array is a robot_task robot task event information object, and only the task events reported in the last 24 hours can be obtained. It is returned only when is_report_task_event=1 and report_task_type passes the correct task type. Please refer to robot_task - Robot Task Event Information.

corp - Enterprise Information Object

Parameter Type Description
ov_corpid string Enterprise ID
corp_name string Enterprise name
create_time string Creation time, integer timestamp in seconds.
update_time string Last modification time, integer timestamp in seconds.

robot - Robot Information Object

Parameter Type Description
ov_corpid string enterprise ID
robot_uuid string Robot UUID
robot_sn string Robot SN
robot_name string Robot name
robot_version string Robot ROM version, for example: V9.7.2024041200.1234US
robot_model string Robot model, for example: OS-R-DR01S
bind_time string Last time the robot was bound to the current enterprise. Integer timestamp in seconds. For example: 1711966681.
expires_time string Expiry time of the lease, valid only for leased robots. Integer timestamp in seconds. For example: 1711966681.
online_status string Robot online status. Online status is determined based on the heartbeats sent by the robot, with updates having approximately a 15-second delay.
0: Offline
1: Online.

robot_report_status - Robot Current Status Information

Parameter Type Description
battery object Robot current battery information
battery.battery_rate string Current battery remaining percentage
battery.is_charging string Whether it is in charging state.
0: No
1: Yes
task_info object Robot current task information object
task_info.task_name string The name of the task currently being executed by the robot, for example: delivering meals
task_info.last_task_name string The name of the last task executed by the robot, for example: waiting for meal delivery
task_info.task_key string The task key of the task currently being executed by the robot, for example: 6YCB6aSQ5Lit. Please refer to Robot Task Name and Task Key Correspondence.
task_info.last_task_key string The task key of the last task executed by the robot, for example: 562J5b6F6YCB6aSQ. Please refer to Robot Task Name and Task Key Correspondence.
location object Robot current location information object
location.state string Robot positioning state.
ready: positioning succeeded
get_lost: positioning failed
location.pos_name string The default language name of the robot's current location
location.pos_all_name object Multi-language name information object of the robot's current location
location.pos_all_name.en_CN string The current location of the robot, Chinese. It is valid only when the robot has reported the Chinese current location. If not reported, it is an empty string.
location.pos_all_name.en_US string The current location of the robot, English. It is valid only when the robot has reported the English current location. If not reported, it is an empty string.
location.emergency string Whether it is in emergency stop state.
0: No
1: Yes

robot_task - Robot Task Event Information

Parameter Type Description
task_id string Task ID.
task_type string

Task type. Defined as follows:

  • meals_deliver_task-deliver
    • Meal delivery to table task
event_type string

The last reported event type of this task. Different task types have different event types, defined as follows:

  • Common event types (please note that te is followed by 2 underscores _):
    • te__start
      • Task start event
    • te__end
      • Task end event
  • Other task event types (please note that te is followed by 1 underscore _):
    • Meal delivery task task_type = meals_deliver_task-deliver
      • te_arrived
        • Arrived at table event
task_time string Creation time of the task, integer timestamp in seconds.
start_time string Start time of the task, integer timestamp in seconds.
update_time string Last reported time of the task, integer timestamp in seconds.
task_data object

Task data. Different task types have different task data, and the data structure is defined as follows:

  • Meal delivery task task_type = meals_deliver_task-deliver
{
    "pos_name" : "A01" // Destination point name
}
event_list array

All event lists reported for this task. Please note that this list comes from robot reports, and because the robot may report incomplete events (such as unstable network), the events it contains cannot be guaranteed to be complete. The structure is as follows: 

[
    {
        "event_type": "te__start", // Event type
        "first_time": "1641881442", // First reported time of this real event
        "last_time": "1641881442" // Last reported time of this event
    },
    {
        "event_type": "te_arrived",
        "first_time": "1641881443",
        "last_time": "1641881443"
    },
    {
        "event_type": "te__end",
        "first_time": "1641881444",
        "last_time": "1641881444"
    },
    // ... Omitted other task events
]
event_list[].event_type string Event type.
event_list[].first_time string First reported time of this real event, integer timestamp in seconds.
event_list[].last_time string Last reported time of this event, integer timestamp in seconds.

Response Body Example

{
    "code": 0,
    "msg": "",
    "data": {
        "corp": {
            "ov_corpid": "orion.ovs.entprise.12345678",
            "corp_name": "test_name",
            "create_time": "1711966681",
            "update_time": "1711966681"
        },
        "robot": {
            "ov_corpid": "orion.ovs.entprise.12345678",
            "robot_uuid": "test_uuid",
            "robot_sn": "test_sn",
            "robot_name": "test_name",
            "robot_version": "V9.7.2024041200.1234US",
            "robot_model": "OS-R-DR01S",
            "bind_time": "1711966681",
            "online_status": "1"
        },
        "robot_report_status": {
            "battery": {
                "battery_rate": "85",
                "is_charging": "0",
                "update_time": "1712046236"
            },
            "task_info": {
                "task_key": "6YCB6aSQ5Lit",
                "last_task_key": "562J5b6F6YCB6aSQ",
                "update_time": "1712046236"
            },
            "location": {
                "state": "ready",
                "pos_name": "A01",
                "pos_all_name": {
                    "en_CN": "A01",
                    "en_US": "A01"
                },
                "emergency": "0",
                "update_time": "1712046236"
            }
        },
        "robot_task_list": [
            {
                "task_id": "test_task_id",
                "task_type": "meals_deliver_task-deliver",
                "event_type": "te__end",
                "task_time": "1712046163",
                "start_time": "1712046163",
                "update_time": "1712046237",
                "task_data": {
                    "pos_name": "A01"
                },
                "event_list": [
                    {
                        "event_type": "te__start",
                        "first_time": "1712046163",
                        "last_time": "1712046163"
                    },
                    {
                        "event_type": "te_arrived",
                        "first_time": "1712046236",
                        "last_time": "1712046236"
                    },
                    {
                        "event_type": "te__end",
                        "first_time": "1712046237",
                        "last_time": "1712046237"
                    }
                ]
            }
        ]
    }
}

Robot Task Name and Task Key Correspondence

Focus on the following states for the meal delivery mode

Task Key Description
6YCB6aSQ5Lit Delivery in progress
562J5b6F6YCB6aSQ Waiting for delivery
5oCl5YGc Emergency stop

Commonly used status table for the Lucki robot

Task Key Description
5LyR55yg Sleep
5YWF55S15Lit Charging
5Y2H57qn Upgrading
5Zue55uY5Lit Returning
5Zue55uY562J5b6F Waiting for return
5Zyw5Zu-566h55CG Map management
5beh6Iiq Cruising
5oCl5YGc Emergency stop
5o-95a6i Picking up passengers
5qGM6Z2i Desktop
5qyi6L-O Welcome
5raI5p2A Disinfection
55S16YeP5L2O Low battery
562J5b6F6YCB6aSQ Waiting for delivery
6K6-572u5Lit Settings
6YCB6aSQ5Lit Delivery in progress
6YeN5a6a5L2N Relocating
6Ziy55uX5oql6K2m Anti-theft alarm
6aKG5L2N5Lit Lead position

Defined robot states

Task Key Description
56m66Zey Idle
5LyR55yg Sleep
5qyi6L-O Welcome
5beh6YC7 Patrol
5a-86Iiq Navigation
5byV6aKG Lead
5o6l5b6F Reception
6Ieq55Sx6Zeu562U Free Q&A
5Y675YWF55S1 Going to charge
6Zeu6Lev5byV6aKG Asking for directions
6Lez6Iie Dancing
5bm_5ZGK Advertising
5ZCI54Wn Taking photos
5a-86KeI Tour guide
5bqU55So5qGM6Z2i Desktop application
5Z-65pys6L-Q5Yqo Basic exercise
6aKE5ZSk6YaS Pre-wake-up
5byC5bi4 Abnormal
6KeG6aKR Video
5Zyw5Zu-6K6-572u Map settings
5Y2H57qn Upgrading
5a-86KeI5byV6aKG Tour guide and lead
6Ieq5qOA Self-inspection
5oCl5YGc Emergency stop
5aSp5rCU Weather
5pel5Y6G Calendar
6L-c56iL5YiG6Lqr Remote control
6KeG6aKR6YCa6K-d Video call
5YWo5o6l566h Full control
5qGM6Z2i Desktop
6L-c56iL6YeN5a6a5L2N Remote relocation
562J5b6F6YCB6aSQ Waiting for delivery
6YCB6aSQ5Lit Delivery in progress
5o-95a6i Picking up passengers
5beh6Iiq Cruising
562J5b6F6aKG5L2N Waiting for lead position
6aKG5L2N5Lit Lead position in progress
5L2O55S16YeP Low battery
5YWF55S15Lit Charging

Other states

  • The robot will occasionally report other strange states, which can be classified as "others" and do not need to be concerned about.
  • Last modified: 2024-04-09 20:55 +0800