diff --git a/command-middleware/README.md b/command-middleware/README.md index 55f4ddc..9ec6423 100644 --- a/command-middleware/README.md +++ b/command-middleware/README.md @@ -1,27 +1,119 @@ -Robot state object - * x: current x-coordinate (integer) - * y: current y-coordinate (integer) - * size_x: (integer) - * size_y: (integer) - * angle: (integer) - * status: idle, think, forward, reverse, left, right, charging, daijuing (string) - * motors_on: (boolean) - * autonomous_exploration: (boolean) - * battery: (object) - ** charging: (boolean) - ** charge_finished: (boolean) - ** voltage: (double) - ** percentage: (integer) - ** charge_voltage: (double) - * lidar: (object) - ** offset_x: (integer) - ** offset_y: (integer) - -SocketIO commands - * start_mapping: start driving around to create map - * go(x, y): calculate a route to coordinate (x,y), avoiding obstacles, and go there - * go_straight(x, y, mode): go straight to coordinate (x,y); mode must be "forward" or "reverse" - * go_list(list): for each point (x,y) in the list, calculate a route to it, avoiding obstacles, and go there. If a point cannot be reached, skip it. The list must contain points (x,y). E.g. [[1,1], [2,2], [3,3]]. - * stop: stop immediately - * add_obstacle(x, y): add an obstacle at coordinate (x,y) - * remove_obstacle(x, y): remove an obstacle at coordinate (x,y) \ No newline at end of file +Command middleware for Pulurobotics robot +========================================= + +The command middleware communicates with the robot through TCP using a binary protocol, and exposes a Socket.IO interface to obtain information about the robot and to control it. + +SocketIO messages sent *from* the middleware +------------------------------------------ + +The middleware sends the following commands with the specified payload. The payload objects are described in more detail below. + + * robot_status: Payload: a robot status object. + * lidar_lowres: Payload: a robot status object. (TODO: This should be changed to contain lidar data.) + * lidar_highres: Not documented. Payload: Empty. + * picture: Not documented. Payload: Empty. + * debug: Not documented. Payload: Empty. + * dbgpoint: Not documented. Payload: Empty. + * sonar: Not documented. Payload: Empty. + * routeinfo: Payload: A route info object. + * movement_status: Describes the result of a straight movement operation. Payload: a straight movement status object. + * route_status: Describes the result of a routing movement operation. Payload: a routing movement status object. + * sync_request: A notification that maps have been updated and should be synchronised. Payload: Empty. + * localization_result: Result of mapping? (TODO: Unverified.) Payload: Empty. + * command_received: Sent when a command has been successfully received. Payload: an object of the format {command: }, with the string being the name of the command which triggered this message. + +SocketIO messages sent *to* the middleware +---------------------------------------- + +Each message results in a `command_received` message being sent from the middleware (see above). + + * start_mapping: Start driving around to create map. + * go(point): Calculate a route to a specified point, avoiding obstacles, and go there. + * point: {x, y} – x and y must be integers. The unit is mm. + * go_straight(point, mode): Go straight to point, either forward or backwards. + * point: {x, y} – x and y must be integers. The unit is mm. + * mode (string): Either "forward" or "reverse". + * go_list(list): For each point in the list, calculate a route to it, avoiding obstacles, and go there. If a point cannot be reached, skip it. + * list: [ {x1, y1}, {x2, y2}, ... ] – xn and yn must be integers. The unit is mm. + * stop: Stop the current operation. Note: Does not guarantee that the robot stops immediately. + * add_obstacle(point): Add an obstacle at point. + * point: {x, y} – x and y must be integers. The unit is mm. + * remove_obstacle(point): Remove an obstacle at point. + * point: {x, y} – x and y must be integers. The unit is mm. + +Payload objects +--------------- + +In the messages described above, the following payload objects are used: + +### Robot status object + + * x (integer): Robot's current x-coordinate in mm. The origin is determined by the location at start-up. + * y (integer): Robot's current y-coordinate in mm. The origin is determined by the location at start-up. + * size_x (integer): Robot's x-size in mm. + * size_y (integer): Robot's y-size in mm. + * angle (integer): Robot's angle in degrees. The starting angle is determined at start-up. + * status (string): A string describing the current processing state of the robot. Possible values: + * "idle" – The robot is idle. + * "think" – The robot is processing, e.g., calculating a route. + * "forward" – The robot is moving forward. + * "reverse" – The robot is moving backward. + * "left" – The robot is turning left. + * "right" – The robot is turning right. + * "charging" – The robot is charging. + * "daijuing" – The robot is randomly moving whereever possible as a last resort when route-finding fails. + * motors_on (boolean): Whether the motors are engaged on not. + * autonomous_exploration (boolean): Whether the robot is autonomously exploring its surroundings. + * battery (object): An object describing the robot's battery and charging state. + * charging (boolean): Whether the robot is currently charging. + * charge_finished (boolean): Whether the charging operation has finished. + * voltage (double): The current voltage of the battery. + * percentage (integer): The state of charge of the battery (how "full" it is). + * charge_voltage (double): The current voltage fed from the charger. + * lidar (object): An object representing data from the robot's lidar sensor. + * offset_x (integer): Not documented. + * offset_y (integer): Not documented. + +### Route info object + + * start (object): An object describing the starting point of the route. + * x (integer): The x coordinate of the starting point, in mm. + * y (integer): The y coordinate of the starting point, in mm. + * points (list): A list of points describing the route. + * point: {x, y} – x and y must be integers. The unit is mm. + +### Straight movement status object + + * start (object): An object describing the starting point and angle. + * x (integer): The x starting position in mm. + * y (integer): The y starting position in mm. + * angle (double): The starting angle in degrees. + * requested (object): An object describing the requested destination. + * x (integer): The requested destination x position in mm. + * y (integer): The requested destination y position in mm. + * backmode (integer): The requested driving direction. + * current (object): An object describing the current location. + * x (integer): The current x position in mm. + * y (integer): The current y position in mm. + * angle (double): The current angle in degrees. + * statuscode (integer): A status code describing the movement. + * success (boolean): Whether the movement succeeded or not. + * hardware_obstacle_flags: Not documented. + +### Routing movement status object + + * start (object): An object describing the starting point and angle. + * x (integer): The x starting position in mm. + * y (integer): The y starting position in mm. + * angle (double): The starting angle in degrees. + * requested (object): An object describing the requested destination. + * x (integer): The requested destination x position in mm. + * y (integer): The requested destination y position in mm. + * backmode (integer): The requested driving direction. + * current (object): An object describing the current location. + * x (integer): The current x position in mm. + * y (integer): The current y position in mm. + * angle (double): The current angle in degrees. + * statuscode (integer): A status code describing the movement. + * success (boolean): Whether the movement succeeded or not. + * reroute_count (integer): How many times the route was changed on the way. \ No newline at end of file