AGVC Python SDK User Function Interface and Data Structure Specification Document

Version information

• Version number: 0.1.0
• Date of issue: August 25, 2025

1 Introduction

This document provides developers with detailed descriptions of the interfaces and data structures for the AGVC Python SDK. With this document, developers can learn how to call the functional modules of AGVC, including setting the system time, managing stations and paths, operating maps, and controlling AGV operating modes. This document is intended for all developers who use the AGVC Python SDK for AGV development and integration.

2. Data types

2.1 Enumerations

2.1.1 Running mode enumeration type: RunningMode

RunningMode is used to indicate the current running mode of the AGV.

Running mode	Value	Description
NONE	0	-
START	1	Start mode.
MAPPING	2	Mapping mode.
NAVIGATE	3	Navigation mode.
CHARGING	4	Automatic charging mode.
MAINTAIN	5	Maintenance mode.
STOP	6	Stop mode.

2.1.2 Path shape enumeration type: PathShape

PathShape is used to indicate the shape of the AGV travel path.

Path shape	Value	Description
NONE	0	-
LINE	1	Straight line.
ARC	2	Arc.
BEZIER	3	Bezier curve.

2.1.3 Map format enumeration type: MapFormat

MapFormat is used to indicate the storage format of the map.

Map format	Value	Description
NONE	0	-
OCCUPANCY_GRID	1	Occupancy grid map.
BASE64_PNG	2	Base64-encoded PNG map.

2.1.4 Virtual area enumeration type: MapVirtualAreaType

MapVirtualAreaType is used to indicate the type of virtual area in the map.

Virtual area type	Value	Description
NONE	0	-
OBSTACLE	1	Virtual wall.
SLOW_DOWN	2	Deceleration zone.
INFLATE	3	Inflation zone.

2.1.5 Virtual area shape enumeration: MapVirtualAreaShape

MapVirtualAreaShape is used to indicate the geometry of a virtual area in the map.

Shape	Value	Description
NONE	0	-
LINE	1	Straight line.
ARC	2	Arc.
CIRCLE	3	Circle.
POLYGON	4	Polygon.

2.1.6 AGV navigation enumeration type: NavType

NavType is used to indicate the navigation type of an AGV.

Navigation type	Value	Description
NONE	0	-
FREE_TO_POSE	1	Free navigation to any point.
FREE_TO_STATION	2	Free navigation to a station.
PATH_TO_STATION	3	Path navigation to a station.

2.1.7 Automatic charging enumeration type: AutoChargingType

AutoChargingType is used to indicate the automatic charging type of an AGV.

Charging type	Value	Description
NONE	0	-
LOW_POWER_TO_BOARD	1	Automatic docking when the battery level is low (determined by a preset threshold).
HIGH_POWER_LEAVE_BOARD	2	Automatic undocking when the battery level is high (determined by a preset threshold).
FORCE_TO_BOARD	3	Forced automatic docking (regardless of battery level and threshold).
FORCE_LEAVE_BOARD	4	Forced automatic undocking (regardless of battery level and threshold).

2.1.8 Operation feedback enumeration type: FeedbackStatus

FeedbackStatus is used to indicate the feedback status after an operation is executed.

Status type	Value	Description
NONE	0	-
FINISHED	1	Succeeded.
FAILED	2	Failed.
RUNNING	3	Running.
PAUSED	4	Paused.
CANCELED	5	Canceled.

2.1.9 Firmware update operation enumeration: FirmwareUpdateMode

FirmwareUpdateMode is used to indicate the update configuration for the module firmware.

Configuration type	Value	Description
NONE	0	Firmware not updated by default.
UPDATE	1	Update firmware.
FORCED_UPDATE	2	Forced update of firmware.
NOT_UPDATE	3	Not update firmware.

2.1.10 Script runtime state enumeration: ScriptRuntimeState

ScriptRuntimeState is used to indicate the runtime state of a script.

Status	Value	Description
RUNNING	0	Running.
PAUSED	1	Paused.
STOPPED	2	Stopped.
ABORTING	3	Aborting.

2.1.11 Calibration type enumeration: CalibrationType

CalibrationType is used to indicate the calibration type of an AGV.

Type	Value	Description
NONE	0	-
LASER_ODOM	1	Laser-odometer calibration.

2.1.12 AGV navigation state enumeration: NavStatus

NavStatus is an alias for FeedbackStatus and is used to indicate the navigation state of an AGV.

Status type	Value	Description
NONE	0	-
FINISHED	1	Navigation finished.
FAILED	2	Navigation failed.
RUNNING	3	Navigation running.
PAUSED	4	Navigation paused.
CANCELED	5	Navigation canceled.

2.1.13 Save Map asynchronous interface status: SaveMapStatus

SaveMapStatus is an alias for FeedbackStatus and is used to indicate the Save Map interface status.

Status type	Value	Description
NONE	0	Save Map interface not running.
FINISHED	1	Save Map interface running finished.
FAILED	2	Invalid value.
RUNNING	3	Map being saved.
PAUSED	4	Invalid value.
CANCELED	5	Invalid value.

2.1.14 Switch Map asynchronous interface status: SwitchMapStatus

SwitchMapStatus is an alias for FeedbackStatus and is used to indicate the Switch Map interface status.

Status type	Value	Description
NONE	0	Switch Map interface not running.
FINISHED	1	Switch Map interface running finished.
FAILED	2	Invalid value.
RUNNING	3	Map being switched.
PAUSED	4	Invalid value.
CANCELED	5	Invalid value.

2.1.15 Change Running Mode asynchronous interface status: ChangeRunningModeStatus

ChangeRunningModeStatus is an alias for FeedbackStatus and indicates the Change Running Mode interface status.

Status type	Value	Description
NONE	0	Change Running Mode interface not running.
FINISHED	1	Change Running Mode interface running finished.
FAILED	2	Invalid value.
RUNNING	3	Running mode being changed.
PAUSED	4	Invalid value.
CANCELED	5	Invalid value.

2.1.16 Relocation status: RelocationStatus

RelocationStatus is an alias for FeedbackStatus and indicates the Relocation interface status.

Status type	Value	Description
NONE	0	Relocation interface not running.
FINISHED	1	Relocation interface running finished.
FAILED	2	Invalid value.
RUNNING	3	Relocating.
PAUSED	4	Invalid value.
CANCELED	5	Invalid value.

2.1.17 Upload Png Map Information interface status: SetPngMapAllInfoStatus

SetPngMapAllInfoStatus is an alias for FeedbackStatus and indicates the Upload All Png Map Information interface status.

Status type	Value	Description
NONE	0	Set Map Information interface not running.
FINISHED	1	Set Map Information interface running finished.
FAILED	2	Invalid value.
RUNNING	3	Map information being uploaded.
PAUSED	4	Invalid value.
CANCELED	5	Invalid value.

2.1.18 Get Png Map Information interface status: GetPngMapAllInfoStatus

GetPngMapAllInfoStatus is an alias for FeedbackStatus and indicates the Get All Png Map Information interface status.

Status type	Value	Description
NONE	0	Get Png Map Information interface not running.
FINISHED	1	Get Png Map Information interface running finished.
FAILED	2	Invalid value.
RUNNING	3	Png map information being got.
PAUSED	4	Invalid value.
CANCELED	5	Invalid value.

2.1.19 Get Grid Map interface status: GetGridMapStatus

GetGridMapStatus is an alias for FeedbackStatus and indicates the Get Grid Map interface status.

Status type	Value	Description
NONE	0	Get Grid Map interface not running.
FINISHED	1	Get Grid Map interface running finished.
FAILED	2	Invalid value.
RUNNING	3	Grid map being got.
PAUSED	4	Invalid value.
CANCELED	5	Invalid value.

2.1.20 Send Grid Map interface status: SendGridMapStatus

SendGridMapStatus is an alias for FeedbackStatus and indicates the Send Grid Map interface status.

Status type	Value	Description
NONE	0	Send Grid Map interface not running.
FINISHED	1	Send Grid Map interface running finished.
FAILED	2	Invalid value.
RUNNING	3	Grid map being sent.
PAUSED	4	Invalid value.
CANCELED	5	Invalid value.

2.1.21 Get Png Map interface status: GetPngMapStatus

GetPngMapStatus is an alias for FeedbackStatus and indicates the Get Png Map interface status.

Status type	Value	Description
NONE	0	Get Png Map interface not running.
FINISHED	1	Get Png Map interface running finished.
FAILED	2	Invalid value.
RUNNING	3	Png map being got.
PAUSED	4	Invalid value.
CANCELED	5	Invalid value.

2.1.22 Send Png Map interface status: SendPngMapStatus

SendPngMapStatus is an alias for FeedbackStatus and indicates the Send Png Map interface status.

Status type	Value	Description
NONE	0	Send Png Map interface status not running.
FINISHED	1	Send Png Map interface status running finished.
FAILED	2	Invalid value.
RUNNING	3	Png map being sent.
PAUSED	4	Invalid value.
CANCELED	5	Invalid value.

2.1.23 Set Grid Map Information interface status: SetGridMapAllInfoStatus

SetGridMapAllInfoStatus is an alias for FeedbackStatus and indicates the Set All Grid Map Information interface status.

Status type	Value	Description
NONE	0	Send All Grid Map Information interface not running.
FINISHED	1	Send All Grid Map Information interface running finished.
FAILED	2	Invalid value.
RUNNING	3	All grid map information being sent.
PAUSED	4	Invalid value.
CANCELED	5	Invalid value.

2.1.24 Get Grid Map Information interface status: GetGridMapAllInfoStatus

GetGridMapAllInfoStatus is an alias for FeedbackStatus and indicates the Get All Grid Map Information interface status.

Status type	Value	Description
NONE	0	Get All Grid Map Information interface not running.
FINISHED	1	Get All Grid Map Information interface running finished.
FAILED	2	Invalid value.
RUNNING	3	All grid map information being got.
PAUSED	4	Invalid value.
CANCELED	5	Invalid value.

2.1.25 Calibration status enumeration: CalibrationStatus

CalibrationStatus is an alias for FeedbackStatus and indicates the Calibration interface status.

Status type	Value	Description
NONE	0	-
FINISHED	1	Calibration finished.
FAILED	2	Calibration failed.
RUNNING	3	Collecting data.
PAUSED	4	Invalid value.
CANCELED	5	Calibration canceled.

2.2 Structure

2.2.1 2D point structure: Point2d

Attribute name	Type	Description
x	float	Unit m
y	float	Unit m

2.2.2 2D pose structure: Pose2d

Attribute name	Type	Description
x	double	Unit m
y	double	Unit m
yaw	double	Unit rad

2.2.3 Speed structure: Speed

Attribute name	Type	Description
v	double	Unit m
w	double	Unit rad/s

2.2.4 Header information structure: Header

Attribute name	Type	Description
id	str	Universally unique identifier (UUID).
name	str	Name.
stamp	int64	Timestamp (UTC time, unit: ns).
map_id	str	Current map ID.
error_code	int	Error code (-1 by default).

2.2.5 AGV information structure: AgvDetails

Attribute name	Type	Description
name	str	AGV name.
version	str	Version number of the current control program.
MFD	str	Manufacture date.
SN	str	Serial number.
communication_version	int	bridge Version information.
battery_version	int	Battery version information.
loop_times	int	Battery cycle count.
surplus_capacity	float	Remaining battery capacity.
left_motor_firmware_version	int	Left motor firmware version.
right_motor_firmware_version	int	Right motor firmware version.
master_board_firmware_version	int	Interface board firmware version information.
hardware_abstraction_version	int	Hardware abstraction layer version information.
error_code_version	int	Error code version.
max_speed	float	Maximum linear speed allowed for the AGV.
max_angular	float	Maximum angular speed allowed for the AGV.

2.2.6 AGV running information structure: RunningInfo

Attribute name	Type	Description
header	Header	AGV's SN, name, current time, and map ID.
running_mode	RunningMode	Current running mode of the AGV.
current_speed	Speed	Current driving speed {v w}, in {m/s rad/s}.
location_score	int8	Current location score, [0-100].
total_dist	double	Total distance traveled, in m.
current_dist	double	Distance traveled in the current session, in m.
total_running_time	double	Total running time, in s.
current_running_time	double	Running time of the current session, in s.
battery_voltage	double	Battery voltage, in V.
battery_current	double	Battery current, in A.
remaining_voltage	int8	Remaining battery level, in percentage (%), [0-100].
battery_status	int8	Battery status: 0- None, 1- Discharging, 2- Charging, 3- Fully charged, 4- Charging urgently needed.
safety_edge_status	int8	Safety edge status: 0- None, 1- Front-left collision, 2- Front-right collision, 3- Rear-left collision, 4- Rear-right collision.
low_battery	bool	Whether the battery level is low.
pause	bool	Whether the AGV is in a paused state.
emergency_stop	bool	Whether the AGV is in an emergency stop state.
blocked	bool	Whether the AGV is blocked by an obstacle.
localization_loss	bool	Whether localization is lost.
fault_alarm	bool	Fault alarm (motor fault, sensor fault, battery fault). For detailed fault information, see the log.

2.2.7 Save Map asynchronous interface status structure: SaveMapWorkingStatus

Attribute name	Type	Description
header	Header	header.id represents the ID of the issued saveMap command.
status	SaveMapStatus	Running status of the SaveMap interface: NONE- Not running, RUNNING- Running, FINISH- Finished.

2.2.8 Switch Map asynchronous interface status structure: SwitchMapWorkingStatus

Attribute name	Type	Description
header	Header	header.id represents the ID of the issued switchMap command.
status	SwitchMapStatus	Running status of the switchMap interface: NONE- Not running, RUNNING- Running, FINISH- Finished.

2.2.9 Change Running Mode asynchronous interface status structure: ChangeModeWorkingStatus

Attribute name	Type	Description
header	Header	header.id represents the ID of the issued changeRunningMode command.
status	ChangeRunningModeStatus	Running status of the changeRunningMode interface: NONE- Not running, RUNNING- Running, FINISH- Finished.

2.2.10 Relocation asynchronous interface status structure: RelocationWorkingStatus

Attribute name	Type	Description
header	Header	header.id represents the ID of the issued Relocation command.
status	RelocationStatus	Running status of the Relocation interface: NONE- Not running, RUNNING- Running, FINISH- Finished.

2.2.11 Set Png Map Information asynchronous interface status structure: SetPngMapAllInfoWorkingStatus

Attribute name	Type	Description
header	Header	header.id represents the ID of the issued setPngMapAllInfo command.
status	SetPngMapAllInfoStatus	Running status of the setPngMapAllInfo interface: NONE- Not running, RUNNING- Running, FINISH- Finished.

2.2.12 Get Png Map Information asynchronous interface status structure: GetPngMapAllInfoWorkingStatus

Attribute name	Type	Description
header	Header	header.id represents the ID of the issued getPngMapAllInfo command.
status	GetPngMapAllInfoStatus	Running status of the getPngMapAllInfo interface: NONE- Not running, RUNNING- Running, FINISH- Finished.

2.2.13 Get Grid Map asynchronous interface status structure: GetGridMapWorkingStatus

Attribute name	Type	Description
header	Header	header.id represents the ID of the issued getGridMapFromAgv command.
status	GetGridMapStatus	Running status of the getGridMapFromAgv interface: NONE- Not running, RUNNING- Running, FINISH- Finished.

2.2.14 Send Grid Map asynchronous interface status structure: SendGridMapWorkingStatus

Attribute name	Type	Description
header	Header	header.id represents the ID of the issued sendGridMapToAgv command.
status	SendGridMapStatus	Running status of the sendGridMapToAgv interface: NONE- Not running, RUNNING- Running, FINISH- Finished.

2.2.15 Get Png Map asynchronous interface status structure: GetPngMapWorkingStatus

Attribute name	Type	Description
header	Header	header.id represents the ID of the issued getBase64PngMapFromAgv command.
status	GetPngMapStatus	Running status of the getBase64PngMapFromAgv interface: NONE- Not running, RUNNING- Running, FINISH- Finished.

2.2.16 Send Png Map asynchronous interface status structure: SendPngMapWorkingStatus

Attribute name	Type	Description
header	Header	header.id represents the ID of the issued sendBase64PngMapToAgv command.
status	SendPngMapStatus	Running status of the sendBase64PngMapToAgv interface: NONE- Not running, RUNNING- Running, FINISH- Finished.

2.2.17 Set Grid Map Information asynchronous interface status structure: SetGridMapAllInfoWorkingStatus

Attribute name	Type	Description
header	Header	header.id represents the ID of the issued setGridMapAllInfo command.
status	SetGridMapAllInfoStatus	Running status of the setGridMapAllInfo interface: NONE- Not running, RUNNING- Running, FINISH- Finished.

2.2.18 Get Grid Map Information asynchronous interface status structure: GetGridMapAllInfoWorkingStatus

Attribute name	Type	Description
header	Header	header.id represents the ID of the issued getGridMapAllInfo command.
status	GetGridMapAllInfoStatus	Running status of the getGridMapAllInfo interface: NONE- Not running, RUNNING- Running, FINISH- Finished.

2.2.19 Asynchronous interface running status structure: AsyncInterfaceResultStatus

Attribute name	Type	Description
header	Header	AGV's SN, name, current time, and map ID.
save_map_status	SaveMapWorkingStatus	Running status of the saveMap interface.
switch_map_status	SwitchMapWorkingStatus	Execution status of the switch map (switchMap) interface.
change_running_mode_status	ChangeModeWorkingStatus	Running status of the changeRunningMode interface.
relocation_status	RelocationWorkingStatus	Running status of the relocation interface.
get_grid_map_status	GetGridMapWorkingStatus	Running status of the getGridMapFromAgv interface.
send_grid_map_status	SendGridMapWorkingStatus	Running status of the sendGridMapToAgv interface.
get_png_map_status	GetPngMapWorkingStatus	Running status of the getBase64PngMapFromAgv interface.
send_png_map_status	SendPngMapWorkingStatus	Running status of the sendBase64PngMapToAgv interface.
set_png_all_status	SetPngMapAllInfoWorkingStatus	Running status of the setPngMapAllInfo interface.
get_png_all_status	GetPngMapAllInfoWorkingStatus	Running status of the getPngMapAllInfo interface.
set_grid_all_status	SetGridMapAllInfoWorkingStatus	Running status of the setGridMapAllInfo interface.
get_grid_all_status	GetGridMapAllInfoWorkingStatus	Running status of the getGridMapAllInfo interface.

3. Function interfaces

3.1 RpcClient-related interfaces

3.1.1 Set log handler

def setLogHandler(handler: callable)

Parameters:

• handler callable: A user-defined log handling function, defined as follows:

def handler(level: int, filename: str, line: int, message: str)

• level int: Log level, value range:
  • 0: FATAL (Critical Error)
  • 1: ERROR (Error)
  • 2: WARNING (Warning)
  • 3: INFO (Information)
  • 4: DEBUG (Debugging)
  • 5: BACKTRACE (Trace)
• filename str: File name
• line int: Code line number
• message str: Log message

Return value:

• None

Description:

• This function allows you to customize the log handling logic, overriding the default log handling method.

3.1.2 Connect to the RPC service

def connect(ip: str = "", port: int = 0) -> int

Parameters:

• ip str, optional: IP address of the RPC service, which is an empty string by default, indicating the use of a Unix domain socket.
• port int, optional: Port number of the RPC service, which is 0 by default, indicating the use of a Unix domain socket.

Return value:

• int: Connection result code:
  • 0: Connected successfully
  • -8: Connection failed, RPC connection refused
  • -15: Connection failed, SDK version incompatible with the server version

Description:

• Connect to the specified RPC service. If both ip and port are empty, a Unix domain socket is used for communication.

3.1.3 Disconnect from the RPC service

def disconnect() -> int

Parameters:

• None

Return value:

• int: Operation result code:
  • 0: Disconnected successfully
  • -1: Disconnection failed

Description:

• Disconnect from the RPC service.

3.1.4 Check if connected to the RPC service

def hasConnected() -> bool

Parameters:

• None

Return value:

• bool: Whether it is connected to the RPC service.
  • True: Connected
  • False: Not connected

Description:

• Check whether it is currently connected to the RPC service.

3.1.5 Log in to the RPC service

def login(usrname: str, passwd: str) -> int

Parameters:

• usrname str: User name
• passwd str: Password

Return value:

• int: Login result code:
  • 0: Logged in successfully

Description:

• Log in to the RPC service with the specified user name and password.

3.1.6 Log out of the RPC service

def logout() -> int

Parameters:

• None

Return value:

• int: Logout result code:
  • 0: Logged out successfully

Description:

• Log out of the RPC service.

3.1.7 Check if logged in

def hasLogined() -> bool

Parameters:

• None

Return value:

• bool: Whether it is logged in.
  • True: Logged in
  • False: Not logged in

Description:

• Check whether it is currently logged in to the RPC service.

3.1.8 Set the RPC request timeout

def setRequestTimeout(timeout: int = 10) -> int

Parameters:

• timeout int, optional: Request timeout in milliseconds, which is 10 by default.

Return value:

• int: Setting result code:
  • 0: Set successfully

Description:

• Set the timeout for RPC requests.

3.1.9 Set event handling

def setEventHandler(cb: callable) -> int

Parameters:

• cb callable: Event handling function, defined as follows:

def cb(event: int)

• event int: Event type, value range:
  • 0: Connected
  • 1: Disconnected

Return value:

• int: Setting result code:
  • 0: Set successfully

Description:

• Set the event handling function to process events for the RPC connection. When an event occurs, the registered callback function is automatically called and the corresponding event type parameter is passed in.

Note:

• If a Python exception is thrown during the execution of the callback function, it will be caught and output to the standard error stream, but it will not affect the execution of the main program.
• The framework automatically handles the Python Global Interpreter Lock (GIL) to ensure thread safety.
• The callback function should be kept as lightweight as possible to avoid long-term blocking that could affect the efficiency of event handling.

3.1.10 Set exception throwing

def setExceptionFree(enable: bool) -> int

Parameters:

• enable bool: Whether to enable exception throwing.

Return value:

• int: Setting result code:
  • 0: Set successfully

Description:

• Set whether to throw an exception when it occurs.

3.1.11 Get error code

def errorCode() -> int

Parameters:

• None

Return value:

• int: Error code of the last operation.

Description:

• Get the error code of the last operation.

3.2 AGVC-related function interfaces

3.2.1 Set AGV system time

def set_system_clock(stamp: str) -> int

Parameters:

• stamp str: Timestamp string in the format YYYY-MM-DDTHH:mm:ss.ssZ, for example, "2017-04-15T11:40:03.12Z".

Return value:

• int: Setting result code:
  • 0: Set successfully
  • Others: Error code

Description:

• Set the system clock of the AGV.

3.2.2 Get AGV details

def get_agv_details() -> AgvDetails

Parameters:

• None

Return value:

• AgvDetails(dict): A dictionary containing the detailed information of the AGV.

Description:

• Query the detailed information of the AGV, including its name, version, and production date.

3.2.3 Get AGV running information

def get_running_info() -> RunningInfo

Parameters:

• None

Return value:

• RunningInfo(dict): A dictionary containing the running information of the AGV.

Description:

• Query the detailed information of the AGV, including its running speed, battery level, and localization score.

3.2.4 Get current pose of AGV

def get_agv_current_pose() -> Pose2d

Parameters:

• None

Return value:

• Pose2d(dict): A dictionary containing the current pose of the AGV.

Description:

• Query the current pose of the AGV, including its position and attitude.

3.2.5 Get current lidar point cloud data

def get_laser_point_cloud() -> list<Point2d>

Parameters:

• None

Return value:

• Point2dlist: A list containing the current lidar point cloud data.

Description:

• Query the current lidar point cloud data.

3.2.6 Get the running status of asynchronous interfaces

def get_async_interface_result_status() -> AsyncInterfaceResultStatus

Parameters:

• None

Return value:

• AsyncInterfaceResultStatus: Containing the running status of all asynchronous interfaces.

Description:

• Querying the running status of an asynchronous interface does not represent the running result of the interface itself.

3.2.7 Get all station information

def get_all_stations() -> list<StationMark>

Parameters:

• None

Return value:

• list[StationMark]: A list containing information of all stations. Each element is a StationMark type station object.