diff --git a/.gitignore b/.gitignore index d9365e6..4d41f35 100644 --- a/.gitignore +++ b/.gitignore @@ -12,3 +12,4 @@ docs/_build/ # mkdocs documentation /site /docs/build/ +.DS_Store diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000..37b553a --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,13 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Python: Current File", + "type": "python", + "request": "launch", + "program": "${file}", + "console": "integratedTerminal", + "justMyCode": false + } + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..070cfda --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "esbonio.sphinx.confDir": "" +} diff --git a/docs/source/api_commands.rst b/docs/source/api_commands.rst index ff0daad..4776a2a 100644 --- a/docs/source/api_commands.rst +++ b/docs/source/api_commands.rst @@ -4,16 +4,359 @@ This page is still under construction. All of the following are the commands we Commands can have multiple parameters that can change from one model to another. +* :ref:`app_charge` +* :ref:`app_get_dryer_setting` +* :ref:`app_get_init_status` +* :ref:`app_pause` +* :ref:`app_rc_end` +* :ref:`app_rc_move` +* :ref:`app_rc_start` +* :ref:`app_rc_stop` +* :ref:`app_segment_clean` +* :ref:`app_set_dryer_setting` +* :ref:`app_start_collect_dust` +* :ref:`app_start_wash` +* :ref:`app_start` +* :ref:`app_stop_collect_dust` +* :ref:`app_stop_wash` +* :ref:`app_stop` +* :ref:`change_sound_volume` +* :ref:`close_dnd_timer` +* :ref:`del_server_timer` +* :ref:`dnld_install_sound` +* :ref:`get_clean_sequence` +* :ref:`get_consumable` +* :ref:`get_custom_mode` +* :ref:`get_customize_clean_mode` +* :ref:`get_dnd_timer` +* :ref:`get_dust_collection_mode` +* :ref:`get_clean_follow_ground_material_status` +* :ref:`get_identify_furniture_status` +* :ref:`get_identify_ground_material_status` +* :ref:`get_led_status` +* :ref:`get_map_v1` +* :ref:`get_multi_map` +* :ref:`get_multi_maps_list` +* :ref:`get_network_info` +* :ref:`get_prop` +* :ref:`get_room_mapping` +* :ref:`get_scenes_valid_tids` +* :ref:`get_serial_number` +* :ref:`get_smart_wash_params` +* :ref:`get_sound_progress` +* :ref:`get_status` +* :ref:`get_timezone` +* :ref:`get_turn_server` +* :ref:`get_valley_electricity_timer` +* :ref:`get_wash_towel_mode` +* :ref:`load_multi_map` +* :ref:`name_segment` +* :ref:`reset_consumable` +* :ref:`resume_segment_clean` +* :ref:`resume_zoned_clean` +* :ref:`retry_request` +* :ref:`reunion_scenes` +* :ref:`save_map` +* :ref:`send_ice_to_robot` +* :ref:`send_sdp_to_robot` +* :ref:`set_server_timer` +* :ref:`set_clean_motor_mode` +* :ref:`set_customize_clean_mode` +* :ref:`set_dnd_timer` +* :ref:`set_dust_collection_mode` +* :ref:`set_fds_endpoint` +* :ref:`set_identify_furniture_status` +* :ref:`set_identify_ground_material_status` +* :ref:`set_led_status` +* :ref:`set_mop_mode` +* :ref:`set_scenes_segments` +* :ref:`set_scenes_zones` +* :ref:`set_segment_ground_material` +* :ref:`set_smart_wash_params` +* :ref:`set_timezone` +* :ref:`set_valley_electricity_timer` +* :ref:`set_wash_towel_mode` +* :ref:`set_water_box_custom_mode` +* :ref:`start_camera_preview` +* :ref:`start_edit_map` +* :ref:`start_voice_chat` +* :ref:`start_wash_then_charge` +* :ref:`stop_camera_preview` +* :ref:`stop_segment_clean` +* :ref:`test_sound_volume` +* :ref:`upd_server_timer` + + +Robot status +------------ + +get_status +~~~~~~~~~~ + +Description: Returns the current status of the vacuum + +Parameters: None + +Returns: + + msg_ver: + + msg_seq: + + state: + + battery: Battery level of your device. + + clean_time: Total clean time in hours. + + clean_area: Total clean area in meters. + + error_code: + + map_reset: + + in_cleaning: + + in_returning: + + in_fresh_state: + + lab_status: + + water_box_status: + + back_type: + + wash_phase: + + wash_ready: + + fan_power: + + dnd_enabled: + + map_status: + + is_locating: + + lock_status: + + water_box_mode: + + water_box_carriage_status: + + mop_forbidden_enable: + + camera_status: + + is_exploring: + + home_sec_status: + + home_sec_enable_password: + + adbumper_status: + + water_shortage_status: + + dock_type: + + dust_collection_status: + + auto_dust_collection: + + avoid_count: + + mop_mode: + + debug_mode: + + collision_avoid_status: + + switch_map_mode: + + dock_error_status: + + charge_status: + + unsave_map_reason: + + unsave_map_flag: + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S7 MaxV Ultra Yes +Roborock S8 Pro Ultra Yes +====================== ========= + +App vacuum control +------------------ + +app_start +~~~~~~~~~ + +Description: + +Parameters: + +app_pause +~~~~~~~~~ + +Description: This pauses the vacuum's current task + +Parameters: None + +Returns ok or error + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= + +app_stop +~~~~~~~~ + +Description: + +Parameters: + + +app_start_collect_dust +~~~~~~~~~~~~~~~~~~~~~~ + +Description: This empties the bin while docked + +Parameters: None + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= + +app_stop_collect_dust +~~~~~~~~~~~~~~~~~~~~~~ + +Description: This stops the emptying of the dust bin while docked + +Parameters: None + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= + +app_start_wash +~~~~~~~~~~~~~~ + +Description: This washes the mop while docked + +Parameters: None + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= + + +app_stop_wash +~~~~~~~~~~~~~ + +Description: This stops washing the mop whiloe docked + +Parameters: None + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= + +app_goto_target +~~~~~~~~~~~~~~~ + +Description: Got to target + +Parameters: To be determined + +Returns ok or error + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= + app_charge ----------- +~~~~~~~~~~ Description: This tells your vacuum to go back to the dock and charge. Parameters: None +Returns : ok or error + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S7 MaxV Ultra Yes +Roborock S8 Pro Ultra Yes +====================== ========= + + +App status +---------- + +app_get_init_status +~~~~~~~~~~~~~~~~~~~ + +Description: Returns details on the app being used to interact with Roborock servers ?? In this case the app is backend supporting the HA integration ? + +Parameters: None + +Returns: + + local_info: + + name: Name of the app + + bom: Version of the app + + location: Location of the app + + language: Language of the app + + wifiplan: Wifi plan of the app + + timezone: Timezone of the app + + logserver: Log server of the app + + featureset: Featureset of the app + + feature_info: List of features + + new_feature_info: New feature info + +Return example:: + {'local_info': {'name': 'custom_A.03.0342_CE', 'bom': 'A.03.0342', 'location': 'de', 'language': 'en', 'wifiplan': '', 'timezone': 'Europe/Berlin', 'logserver': 'awsde0.fds.api.xiaomi.com', 'featureset': 3}, 'feature_info': [111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125], 'new_feature_info': 2247395306799103, 'new_feature_info_str': '00000008009EFFFE'} + + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= + +App dryer settings +------------------ app_get_dryer_setting ---------------------- +~~~~~~~~~~~~~~~~~~~~~ Description: Get dock dryer settings. @@ -47,183 +390,343 @@ Return example:: Source: Roborock S7 MaxV Ultra -app_get_init_status -------------------- +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S7 MaxV Ultra Yes +Roborock S8 Pro Ultra Yes +====================== ========= -Description: +app_set_dryer_setting +~~~~~~~~~~~~~~~~~~~~~ -Parameters: +Description: Set the time for the dryer to run +Parameters: '{"status":1,"on":{"dry_time":14400}}' -app_goto_target ---------------- +dry_time is the time in seconds the dryer will run for -Description: +Returns ok or error -Parameters: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= -app_pause ---------- +App remote control +------------------ -Description: This pauses the vacuum's current task +app_rc_start +~~~~~~~~~~~~ + +Description: Starts remote control. + +Parameters: None + +Returns ok or error + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= + + +app_rc_move +~~~~~~~~~~~ + +Description: Moves the robot in the direction specified + +Parameters: To be documented + +Returns ok or error + +.. + Need to document the parameters - will need to explore the app to find out what they are + + +app_rc_stop +~~~~~~~~~~~ + +Description: Stops the remote control Parameters: None +Returns ok or error + +.. + Assume stop stops a move ?? Need to check app_rc_end ----------- +~~~~~~~~~~ -Description: +Description: Ends the remote control task Parameters: +Returns ok or error -app_rc_move ------------ +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= -Description: -Parameters: +App other +--------- -app_rc_start ------------- +app_set_smart_cliff_forbidden +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Description: Parameters: -app_rc_stop ------------ +app_spot +~~~~~~~~ Description: Parameters: -app_segment_clean ------------------ +app_stat +~~~~~~~~ -Description: +Description: This returns the current status of the vacuum -Parameters: +Parameters: None +Returns: ok or error -app_set_dryer_setting ---------------------- +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= + +app_wakeup_robot +~~~~~~~~~~~~~~~~ Description: Parameters: -app_set_smart_cliff_forbidden ------------------------------ +app_zoned_clean +~~~~~~~~~~~~~~~ -Description: +Description: Starts a zone clean Parameters: +.. + Us this the last known zone -app_spot --------- +Returns: ok or error + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= + +Segments and Zones +------------------ + +app_segment_clean +~~~~~~~~~~~~~~~~~ + +Description: This starts a segment clean and repeats it the number of times specified. + +Parameters: An array of segments to clean. Each segment is an integer with the segment id and the number of times to clean it. For example, to clean segment 18 twice, the parameter would be + + [{'segments': [18], 'repeat': 2}] + +.. Comment: The segment id can be obtained from the initial data returned on login + +Command: + roborock -d command --device_id deviceIdRedacted --cmd app_segment_clean --params '[{"segments": [17,19], "repeat": 2}]' + +Returns ok or error + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= + +set_segment_ground_material +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Description: Sets the groud material for the segment + +Parameters: "{'data':[[22,3,0]]}" + +Returns ok or error + +name_segment +~~~~~~~~~~~~ Description: -Parameters: +Parameters: To be determined +.. + Need to work out parameter format + Does this allow us to name a segment ? -app_start ---------- + +resume_segment_clean +~~~~~~~~~~~~~~~~~~~~ Description: Parameters: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= -app_start_collect_dust ----------------------- +stop_segment_clean +~~~~~~~~~~~~~~~~~~ Description: Parameters: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= -app_start_wash --------------- +set_scenes_zones +~~~~~~~~~~~~~~~~ Description: Parameters: - -app_stat --------- +set_scenes_segments +~~~~~~~~~~~~~~~~~~~ Description: Parameters: -app_stop --------- +get_scenes_valid_tids +~~~~~~~~~~~~~~~~~~~~~ + +Description: To be confirmed + +Parameters: None + +.. + Appears to be associated with rooms ?? + +Returns:: + +[{'tid': '1699679077347', 'map_flag': 0, 'segs': [{'sid': 24}, {'sid': 20}, {'sid': 22}, {'sid': 18}]}, {'tid': '1699679236553', 'map_flag': 0, 'segs': [{'sid': 24}, {'sid': 20}, {'sid': 22}]}, {'tid': '1699679386045', 'map_flag': 0, 'segs': [{'sid': 16}, {'sid': 19}, {'sid': 17}]}, {'tid': '1699679335823', 'map_flag': 0, 'segs': [{'sid': 19}, {'sid': 16}, {'sid': 17}]}] + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= + +resume_zoned_clean +~~~~~~~~~~~~~~~~~~ Description: Parameters: - -app_stop_wash -------------- +reunion_scenes +~~~~~~~~~~~~~~ Description: Parameters: +Camera +------ -app_wakeup_robot ----------------- +start_camera_preview +~~~~~~~~~~~~~~~~~~~~ Description: Parameters: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra No +====================== ========= -app_zoned_clean ---------------- +stop_camera_preview +~~~~~~~~~~~~~~~~~~~ Description: Parameters: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra No +====================== ========= -camera_status -------------- - -Get: get_camera_status +get_camera_status +~~~~~~~~~~~~~~~~~ Description: Get camera status. Parameters: None Returns: 3457 +  387 Roborock S8 Pro Ultra Source: Roborock S7 MaxV Ultra -Set: set_camera_status +set_camera_status +~~~~~~~~~~~~~~~~~ + +Description: + +Parameters: + + + +start_voice_chat +~~~~~~~~~~~~~~~~ Description: Parameters: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra No +====================== ========= + -carpet_clean_mode +Clean modes ----------------- -Get: get_carpet_clean_mode +get_carpet_clean_mode +~~~~~~~~~~~~~~~~~~~~~ Description: Get carpet clean mode. @@ -240,17 +743,15 @@ Return example:: Source: Roborock S7 MaxV Ultra -Set: set_carpet_clean_mode +set_carpet_clean_mode +~~~~~~~~~~~~~~~~~~~~~~~~~~ Description: Parameters: - -carpet_mode ------------ - -Get: get_carpet_mode +get_carpet_mode +~~~~~~~~~~~~~~~ Description: @@ -276,901 +777,1168 @@ Return example:: Vacuum Model Supported ====================== ========= Roborock S7 MaxV Ultra Yes +Roborock S8 Pro Ultra Yes ====================== ========= - -Set: set_carpet_mode +set_carpet_mode +~~~~~~~~~~~~~~~~~~~~ Description: Parameters: +get_smart_wash_params +~~~~~~~~~~~~~~~~~~~~~ -child_lock_status ------------------ +Description: Returns the smartwash parameters -Get: get_child_lock_status +Parameters: None -Description: This gets the child lock status of the device. 0 is off, 1 is on. +.. + Not clear what this does -Parameters: None +Returns: + smart_wash: 0 is off, 1 is on -Set: set_child_lock_status + wash_interval: The interval in seconds between washes -Description: This sets the child lock status of the device. +Example:: -Parameters: None +{'smart_wash': 0, 'wash_interval': 1200} -collision_avoid_status ----------------------- +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= -Get: get_collision_avoid_status +set_smart_wash_params +~~~~~~~~~~~~~~~~~~~~~ -Description: +Description: Sets the smartwash parameters -Parameters: None +Parameters: -Returns: + smart_wash: 0 is off, 1 is on - status: + wash_interval: The interval in seconds between washes -Return example:: - {'status': 1} +{'smart_wash': 0, 'wash_interval': 1200} -Source: Roborock S7 MaxV Ultra +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= + +Cleaning history +---------------- -Set: set_collision_avoid_status +get_clean_record +~~~~~~~~~~~~~~~~ Description: -Parameters: +Parameters: To be determined -consumable ----------- +get_clean_record_map +~~~~~~~~~~~~~~~~~~~~ -Get: get_consumable +Description: -Description: This gets the status of all of the consumables for your device. +Parameters: -Parameters: None -Returns: +get_clean_sequence +~~~~~~~~~~~~~~~~~~ - main_brush_work_time: This is the amount of time the main brush has been used in seconds since it was last replaced +Description: - side_brush_work_time: This is the amount of time the side brush has been used in seconds since it was last replaced +Parameters: - filter_work_time: This is the amount of time the air filter inside the vacuum has been used in seconds since it was last replaced - filter_element_work_time: +get_clean_summary +~~~~~~~~~~~~~~~~~ - sensor_dirty_time: This is the amount of time since you have cleaned the sensors on the bottom of your vacuum. +Description: Get a summary of cleaning history. - strainer_work_times: +Parameters: None - dust_collection_work_times: +Returns: - cleaning_brush_work_times: + clean_time: + clean_area: + clean_count: -custom_mode ------------ + dust_collection_count: -Get: get_custom_mode + records: -Description: +Return example:: -Parameters: + {'clean_time': 568146, 'clean_area': 8816865000, 'clean_count': 178, 'dust_collection_count': 172, 'records': [1689740211, 1689555788, 1689259450, 1688999113, 1688852350, 1688693213, 1688692357, 1688614354, 1688613280, 1688606676, 1688325265, 1688174717, 1688149381, 1688092832, 1688001593, 1687921414, 1687890618, 1687743256, 1687655018, 1687631444]} +Source: Roborock S7 MaxV Ultra + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S7 MaxV Ultra Yes +Roborock S8 Pro Ultra Yes +====================== ========= -Set: set_custom_mode + +get_mop_template_params_summary +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Description: Parameters: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra No +====================== ========= -customize_clean_mode --------------------- +Child lock +---------- -Get: get_customize_clean_mode +get_child_lock_status +~~~~~~~~~~~~~~~~~~~~~~~~~~ -Description: +Description: This gets the child lock status of the device. 0 is off, 1 is on. -Parameters: +Parameters: None +Returns: -Set: set_customize_clean_mode + lock_status: -Description: +Return example:: -Parameters: + {'lock_status': 0} +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= -del_server_timer ----------------- +set_child_lock_status +~~~~~~~~~~~~~~~~~~~~~~~~~~ -Description: +Description: This sets the child lock status of the device. -Parameters: +Parameters: '{"lock_status" :0}' +Returns: ok -dnd_timer ---------- +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= -Get: get_dnd_timer -Description: Gets the do not disturb timer - start_hour: The hour you want dnd to start - start_minute: The minute you want dnd to start +Consumables +----------- - end_hour: The hour you want dnd to be turned off +get_consumable +~~~~~~~~~~~~~~ - end_minute: The minute you want dnd to be turned off +Description: This gets the status of all of the consumables for your device. + +Parameters: None + +Returns: - enabled: If the switch is currently turned on in the app for DnD + main_brush_work_time: This is the amount of time the main brush has been used in seconds since it was last replaced -Parameters: None + side_brush_work_time: This is the amount of time the side brush has been used in seconds since it was last replaced + filter_work_time: This is the amount of time the air filter inside the vacuum has been used in seconds since it was last replaced -Set: set_dnd_timer + filter_element_work_time: -Description: + sensor_dirty_time: This is the amount of time since you have cleaned the sensors on the bottom of your vacuum. -Parameters: + strainer_work_times: + dust_collection_work_times: -Close: close_dnd_timer + cleaning_brush_work_times: -Description: This disables the dnd timer +Return examples:: -Parameters: None + {'main_brush_work_time': 14151, 'side_brush_work_time': 41638, 'filter_work_time': 14151, 'filter_element_work_time': 0, 'sensor_dirty_time': 41522, 'strainer_work_times': 44, 'dust_collection_work_times': 19, 'cleaning_brush_work_times': 44} -dnld_install_sound ------------------- +reset_consumable +~~~~~~~~~~~~~~~~ Description: Parameters: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S7 MaxV Ultra Yes +Roborock S8 Pro Ultra Yes +====================== ========= -dust_collection_mode --------------------- -Get: get_dust_collection_mode +Custom modes +------------ -Description: +get_custom_mode +~~~~~~~~~~~~~~~~~~~~ + +Description: It returns the current custom mode. Parameters: None Returns: - mode: + integer value of the current custom mode Return example:: - {'mode': 0} + 102 -Source: Roborock S7 MaxV Ultra +.. + Not clear what a custom mode is = will explore +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S7 MaxV Ultra Yes +Roborock S8 Pro Ultra Yes +====================== ========= -Set: set_dust_collection_mode +set_custom_mode +~~~~~~~~~~~~~~~~~~~~ Description: Parameters: - -enable_log_upload ------------------ +get_customize_clean_mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Description: Parameters: -end_edit_map ------------- +set_customize_clean_mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Description: Parameters: +Furniture and ground material +----------------------------- -find_me -------- +get_identify_furniture_status +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Description: Parameters: +.. + Does not return anything for S8 Pro Ultra when docked may require vacumm to be cleaning -flow_led_status ---------------- - -Get: get_flow_led_status +set_identify_furniture_status +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Description: Parameters: +.. + Method not known for S8 Pro Ultra + -Set: set_flow_led_status +get_identify_ground_material_status +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Description: Parameters: +.. + Does not return anything for S8 Pro Ultra when docked may require vacumm to be cleaning -get_clean_record ----------------- + +set_identify_ground_material_status +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Description: Parameters: +.. + Method not known for S8 Pro Ultra -get_clean_record_map --------------------- + + +LEDs +---- + +get_flow_led_status +~~~~~~~~~~~~~~~~~~~ Description: Parameters: -get_clean_sequence ------------------- +set_flow_led_status +~~~~~~~~~~~~~~~~~~~ Description: Parameters: +get_led_status +~~~~~~~~~~~~~~~~~~~ -get_clean_summary ------------------ - -Description: Get a summary of cleaning history. +Description: Returns the LED status. If disabled the indicator light will turn off 1 minute after fully charged -Parameters: None +Parameters: Returns: - clean_time: + led_status: 0 is off, 1 is on - clean_area: - clean_count: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= - dust_collection_count: +set_led_status +~~~~~~~~~~~~~~ - records: +Description: Sets the LED status. If disabled the indicator light will turn off 1 minute after fully charged -Return example:: +Parameters: ???? - {'clean_time': 568146, 'clean_area': 8816865000, 'clean_count': 178, 'dust_collection_count': 172, 'records': [1689740211, 1689555788, 1689259450, 1688999113, 1688852350, 1688693213, 1688692357, 1688614354, 1688613280, 1688606676, 1688325265, 1688174717, 1688149381, 1688092832, 1688001593, 1687921414, 1687890618, 1687743256, 1687655018, 1687631444]} +.. + Need to work out parameter format -Source: Roborock S7 MaxV Ultra -get_current_sound ------------------ + +Maps +---- + +get_multi_map +~~~~~~~~~~~~~ Description: Parameters: +Comment: Response timed out for S8 Pro Ultra -get_device_ice --------------- +.. + times out after 4 secs -Description: +get_multi_maps_list +~~~~~~~~~~~~~~~~~~~ -Parameters: +Description: Returns a list of map information stored on the device. +Parameters: None required -get_device_sdp --------------- +Returns: -Description: + max_multi_map: + max_bak_map: + multi_map_count: + map_info:: -Parameters: + mapFlag: + add_time: + length: + name: + bak_maps:: + mapFlag: + add_time: -get_homesec_connect_status --------------------------- -Description: +Return example:: -Parameters: + {'max_multi_map': 4, 'max_bak_map': 1, 'multi_map_count': 2, 'map_info': [{'mapFlag': 0, 'add_time': 1699919699, 'length': 4, 'name': 'Home', 'bak_maps': [{'mapFlag': 4, 'add_time': 1699823921}]}, {'mapFlag': 1, 'add_time': 1699828035, 'length': 13, 'name': 'Boys bathroom', 'bak_maps': [{'mapFlag': 5, 'add_time': 1699828035}]}]} +Source: S8 Pro Ultra + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= get_map_v1 ----------- +~~~~~~~~~~ -Description: +Description: Returns the map -Parameters: +Parameters: Unknown +Comment: Returns a map in a format that is not yet understood by me -get_mop_template_params_summary -------------------------------- +.. + Explore what parameters it may take + Extend code to return byte stream ? + +start_edit_map +~~~~~~~~~~~~~~ Description: Parameters: -get_multi_map -------------- +get_room_mapping +~~~~~~~~~~~~~~~~ + +Description: Returns a list of rooms, ids as discovered by + +Parameters: None + +Returns: + + room_id + +Return example:: + + [[16, '14731399', 12], [17, '2220009', 2], [18, '2219688', 12], [19, '2219685', 9], [20, '2219691', 12], [21, '2431758', 12], [22, '2219677', 13], [23, '2312548', 12], [24, '2219678', 14], [25, '2219686', 15], [26, '2219772', 12], [27, '14768755', 12]] + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S7 MaxV Ultra Yes +Roborock S8 Pro Ultra Yes +====================== ========= + +load_multi_map +~~~~~~~~~~~~~~ Description: -Parameters: +Parameters: ??? +.. + Need to work out parameter format -get_multi_maps_list -------------------- + +save_map +~~~~~~~~ Description: Parameters: +Operating modes +--------------- -get_network_info ----------------- +get_mop_mode +~~~~~~~~~~~~ -Description: Get the device's network information. +Description: Get mop mode. Parameters: None -Returns: +Returns: Enumeration for mop mode. 300 - ssid: SSID of the wirelness network the device is connected to. +Example for S8 Pro Ultra:: - ip: IP address of the device. + standard = 300 + deep = 301 + deep_plus = 303 + fast = 304 + custom = 302 - mac: MAC address of the device. +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= - bssid: BSSID of the device. +set_mop_mode +~~~~~~~~~~~~ - rssi: RSSI of the device. +Description: Set mop mode. -Return example:: +Parameters: mop_mode 300 - {'ssid': 'My WiFi Network', 'ip': '192.168.1.29', 'mac': 'a0:2b:47:3d:24:51', 'bssid': '18:3b:1a:23:41:3c', 'rssi': -32} +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= -Source: Roborock S7 MaxV Ultra +set_clean_motor_mode +~~~~~~~~~~~~~~~~~~~~ +Description: -get_prop --------- +Parameters: + +get_dust_collection_mode +~~~~~~~~~~~~~~~~~~~~~~~~ Description: -Parameters: +Parameters: None + +Returns: + mode: -get_room_mapping ----------------- +Return example:: -Description: + {'mode': 0} -Parameters: +Source: Roborock S7 MaxV Ultra + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S7 MaxV Ultra Yes +Roborock S8 Pro Ultra Yes +====================== ========= -get_scenes_valid_tids ---------------------- +set_dust_collection_mode +~~~~~~~~~~~~~~~~~~~~~~~~ Description: Parameters: +get_wash_towel_mode +~~~~~~~~~~~~~~~~~~~~~~~~ -get_serial_number ------------------ - -Description: Get serial number of the vacuum. +Description: Parameters: None Returns: - serial_number: Serial number of the vacuum. + wash_mode: Return example:: - {'serial_number': 'B16EVD12345678'} + {'wash_mode': 1} Source: Roborock S7 MaxV Ultra -get_sound_progress ------------------- + unknown = -9999 -Description: + light = 0 -Parameters: + balanced = 1 + deep = 2 -get_turn_server ---------------- -Description: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S7 MaxV Ultra Yes +Roborock S8 Pro Ultra Yes +====================== ========= -Parameters: +set_wash_towel_mode +~~~~~~~~~~~~~~~~~~~~~~~~ -identify_furniture_status -------------------------- +Description: Sets the wash wash_towel_mode -Get: get_identify_furniture_status +Parameters: {'wash_mode': 2} -Description: +Returns: ok or error -Parameters: +Source: S8 Pro Ultra +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S7 MaxV Ultra Yes +Roborock S8 Pro Ultra Yes +====================== ========= -Set: set_identify_furniture_status +get_collision_avoid_status +~~~~~~~~~~~~~~~~~~~~~~~~~~ Description: -Parameters: - - -identify_ground_material_status -------------------------------- +Parameters: None -Get: get_identify_ground_material_status +Returns: -Description: + status: -Parameters: +Return example:: + {'status': 1} -Set: set_identify_ground_material_status +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S7 MaxV Ultra Yes +Roborock S8 Pro Ultra Yes +====================== ========= -Description: -Parameters: +set_collision_avoid_status +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Description: Update collision avoid status. -led_status ----------- +Parameters: '{"status" :1}' -Get: get_led_status +Returns: -Description: + ok -Parameters: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S7 MaxV Ultra Yes +Roborock S8 Pro Ultra Yes +====================== ========= -Set: set_led_status +start_wash_then_charge +~~~~~~~~~~~~~~~~~~~~~~ Description: Parameters: +.. + While this returns ok on the S8 Pro Ultra it does not appear to do anything -load_multi_map --------------- +switch_water_mark +~~~~~~~~~~~~~~~~~ Description: Parameters: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra No +====================== ========= -name_segment ------------- +.. + Not found for S8 Pro Ultra -Description: +System information +------------------ -Parameters: +get_network_info +~~~~~~~~~~~~~~~~ +Description: Get the device's network information. -reset_consumable ----------------- +Parameters: None -Description: +Returns: -Parameters: + ssid: SSID of the wirelness network the device is connected to. + ip: IP address of the device. -resume_segment_clean --------------------- + mac: MAC address of the device. -Description: + bssid: BSSID of the device. -Parameters: + rssi: RSSI of the device. + +Return example:: + + {'ssid': 'My WiFi Network', 'ip': '192.168.1.29', 'mac': 'a0:2b:47:3d:24:51', 'bssid': '18:3b:1a:23:41:3c', 'rssi': -32} +Source: Roborock S7 MaxV Ultra -resume_zoned_clean ------------------- +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S7 MaxV Ultra Yes +Roborock S8 Pro Ultra Yes +====================== ========= -Description: -Parameters: +get_serial_number +~~~~~~~~~~~~~~~~~ +Description: Get serial number of the vacuum. -retry_request -------------- +Parameters: None -Description: +Returns:: -Parameters: + serial_number: Serial number of the vacuum. +Return example:: -reunion_scenes --------------- + {'serial_number': 'B16EVD12345678'} -Description: +Source: Roborock S7 MaxV Ultra -Parameters: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S7 MaxV Ultra Yes +Roborock S8 Pro Ultra Yes +====================== ========= +get_prop +~~~~~~~~ -save_map --------- +Description: Generic get property command -Description: +Parameters: The property to get -Parameters: +Example:: + roborock -d command --device_id aHiddenDeviceId --cmd get_prop --params '["battery"]' -send_ice_to_robot ------------------ -Description: -Parameters: +Comment : This example returns the same as get_status. Initial testing has shown that not all get commands are supported by this method -send_sdp_to_robot ------------------ +get_turn_server +~~~~~~~~~~~~~~~ Description: Parameters: +.. + Not found for S8 Pro Ultra + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra No +====================== ========= -server_timer ------------- -Get: get_server_timer +enable_log_upload +~~~~~~~~~~~~~~~~~ Description: Parameters: -Set: set_server_timer - -Description: +find_me +~~~~~~~ -Parameters: +Description: This makes your vacuum speak so you can find it. +Parameters: None -set_app_timezone ----------------- +upd_server_timer +~~~~~~~~~~~~~~~~ Description: Parameters: - -set_clean_motor_mode --------------------- +get_homesec_connect_status +~~~~~~~~~~~~~~~~~~~~~~~~~~ Description: Parameters: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra No +====================== ========= + set_fds_endpoint ----------------- +~~~~~~~~~~~~~~~~ Description: Parameters: - -set_mop_mode ------------- +send_ice_to_robot +~~~~~~~~~~~~~~~~~ Description: Parameters: -set_scenes_segments -------------------- +send_sdp_to_robot +~~~~~~~~~~~~~~~~~ Description: Parameters: +get_device_ice +~~~~~~~~~~~~~~ -set_scenes_zones ----------------- +.. + This doeas not appear to be supported on S8 Pro Ultra Description: Parameters: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra No +====================== ========= -set_water_box_custom_mode -------------------------- +get_device_sdp +~~~~~~~~~~~~~~ Description: Parameters: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra No +====================== ========= -smart_wash_params ------------------ - -Get: get_smart_wash_params +retry_request +~~~~~~~~~~~~~ Description: Parameters: +Timers +------ -Set: set_smart_wash_params +del_server_timer +~~~~~~~~~~~~~~~~ Description: Parameters: -sound_volume ------------- +dnd_timer +~~~~~~~~~ -Get: get_sound_volume +get_dnd_timer +~~~~~~~~~~~~~ -Description: +Description: Gets the do not disturb timer -Parameters: + start_hour: The hour you want dnd to start + start_minute: The minute you want dnd to start -Set: change_sound_volume + end_hour: The hour you want dnd to be turned off -Description: + end_minute: The minute you want dnd to be turned off -Parameters: + enabled: If the switch is currently turned on in the app for DnD + +Parameters: None -start_camera_preview --------------------- +set_dnd_timer +~~~~~~~~~~~~~ Description: Parameters: -start_edit_map --------------- - -Description: +close_dnd_timer +~~~~~~~~~~~~~~~ -Parameters: +Description: This disables the dnd timer +Parameters: None -start_voice_chat ----------------- +get_server_timer +~~~~~~~~~~~~~~~~ Description: Parameters: -start_wash_then_charge ----------------------- +set_server_timer +~~~~~~~~~~~~~~~~ Description: Parameters: +get_timezone +~~~~~~~~~~~~~~~~~ -status ------- - -Get: get_status - -Description: Get status information of the device. +Description: Get the device's time zone. Parameters: None -Returns: - - msg_ver: - - msg_seq: +Returns: Time zone by the TZ identifier (e.g., America/Los_Angeles) - state: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S7 MaxV Ultra Yes +Roborock S8 Pro Ultra Yes +====================== ========= - battery: Battery level of your device. - clean_time: Total clean time in hours. +set_timezone +~~~~~~~~~~~~~~~~~ - clean_area: Total clean area in meters. +Description: Sets the device's time zone - error_code: +Parameters: - map_reset: - in_cleaning: - in_returning: - in_fresh_state: - lab_status: +Sound +------------ - water_box_status: +get_sound_volume +~~~~~~~~~~~~~~~~ - back_type: +Description: Returns the volume of the sound played by the vacuum - wash_phase: +Parameters: None - wash_ready: +Returns: - fan_power: + volume: The volume of the sound played by the vacuum - dnd_enabled: +Example:: - map_status: + 72 - is_locating: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= - lock_status: +change_sound_volume +~~~~~~~~~~~~~~~~~~~ - water_box_mode: +Description: Sets the volume of the sound played by the vacuum - water_box_carriage_status: +Parameters: volume - mop_forbidden_enable: +Returns: ok or error - camera_status: +roborock -d command --device_id aHiddenDeviceId --cmd change_sound_volume --params 72 - is_exploring: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= - home_sec_status: +test_sound_volume +~~~~~~~~~~~~~~~~~ - home_sec_enable_password: +Description: Plays a sound on the vacumm to identity volume - adbumper_status: +Parameters: None - water_shortage_status: +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= - dock_type: - dust_collection_status: +get_sound_progress +~~~~~~~~~~~~~~~~~~ - auto_dust_collection: +Description: - avoid_count: +Parameters: - mop_mode: +Returns:: - debug_mode: +{'sid_in_progress': 0, 'progress': 0, 'state': 0, 'error': 0} - collision_avoid_status: +.. + Is this where the vacumm is currently located ? - switch_map_mode: - dock_error_status: +get_current_sound +~~~~~~~~~~~~~~~~~ - charge_status: +.. + Is this an app setting ? - unsave_map_reason: +Description: - unsave_map_flag: +Parameters: Return example:: - {'msg_ver': 2, 'msg_seq': 1965, 'state': 8, 'battery': 100, 'clean_time': 1976, 'clean_area': 33197500, 'error_code': 0, 'map_present': 1, 'in_cleaning': 0, 'in_returning': 0, 'in_fresh_state': 1, 'lab_status': 1, 'water_box_status': 1, 'back_type': -1, 'wash_phase': 0, 'wash_ready': 0, 'fan_power': 102, 'dnd_enabled': 0, 'map_status': 3, 'is_locating': 0, 'lock_status': 0, 'water_box_mode': 203, 'water_box_carriage_status': 1, 'mop_forbidden_enable': 1, 'camera_status': 3457, 'is_exploring': 0, 'home_sec_status': 0, 'home_sec_enable_password': 0, 'adbumper_status': [0, 0, 0], 'water_shortage_status': 0, 'dock_type': 3, 'dust_collection_status': 0, 'auto_dust_collection': 1, 'avoid_count': 141, 'mop_mode': 300, 'debug_mode': 0, 'collision_avoid_status': 1, 'switch_map_mode': 0, 'dock_error_status': 0, 'charge_status': 1, 'unsave_map_reason': 0, 'unsave_map_flag': 0} - -Source: Roborock S7 MaxV Ultra + {'sid_in_use': 122, 'sid_version': 1, 'sid_in_progress': 0, 'location': 'de', 'bom': 'A.03.0342', 'language': 'en', 'msg_ver': 2} +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S7 MaxV Ultra Yes +Roborock S8 Pro Ultra Yes +====================== ========= -stop_camera_preview -------------------- +dnld_install_sound +~~~~~~~~~~~~~~~~~~ Description: Parameters: - -switch_water_mark +Off peak charging ----------------- -Description: - -Parameters: +get_valley_electricity_timer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Description: Get valley electricity timer. -test_sound_volume ------------------ +Parameters: None -Description: +Returns: -Parameters: + start_hour: The hour you want valley electricity to start + start_minute: The minute you want valley electricity to start -timezone --------- + end_hour: The hour you want valley electricity to be turned off -Get: get_timezone + end_minute: The minute you want valley electricity to be turned off -Description: Get the device's time zone. + enabled: If the switch is currently turned on in the app for valley electricity -Parameters: None -Returns: Time zone by the TZ identifier (e.g., America/Los_Angeles) +``` +{'start_hour': 0, 'start_minute': 0, 'end_hour': 0, 'end_minute': 0, 'enabled': 0} +``` +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= -Set: set_timezone +set_valley_electricity_timer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Description: +Description: Sets the valley electricity timer Parameters: + start_hour: The hour you want valley electricity to start -upd_server_timer ----------------- - -Description: + start_minute: The minute you want valley electricity to start -Parameters: + end_hour: The hour you want valley electricity to be turned off + end_minute: The minute you want valley electricity to be turned off -valley_electricity_timer ------------------------- + enabled: If the switch is currently turned on in the app for valley electricity -Get: get_valley_electricity_timer +Example:: -Description: +{'start_hour': 0, 'start_minute': 0, 'end_hour': 0, 'end_minute': 0, 'enabled': 0} -Parameters: +.. + This does not appear to have any effect on the S8 Pro Ultra - Params accepted however no affect ?? -Set: set_valley_electricity_timer +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra ??? +====================== ========= -Description: -Parameters: -wash_towel_mode ---------------- +Water box mode +-------------- -Get: get_wash_towel_mode +get_water_box_custom_mode +~~~~~~~~~~~~~~~~~~~~~~~~~ -Description: +Description: Get water box mode. Parameters: None -Returns: +Returns: Enumeration for water box mode. 203 - wash_mode: +.. + Not clear what this does - require Enumeration -Return example:: - {'wash_mode': 1} +get_clean_follow_ground_material_status +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Source: Roborock S7 MaxV Ultra +Description: +Parameters: None +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= -Set: set_wash_towel_mode +set_water_box_custom_mode +~~~~~~~~~~~~~~~~~~~~~~~~~ -Description: +Description: Set the water box mode. -Parameters: +Parameters: {'water_box_mode': 203} + +Returns: ok or error + +.. + Not clear what this does - require Enumeration + +====================== ========= +Vacuum Model Supported +====================== ========= +Roborock S8 Pro Ultra Yes +====================== ========= diff --git a/docs/source/conf.py b/docs/source/conf.py index 2394396..4014cc6 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,6 +16,7 @@ "sphinx.ext.autodoc", "sphinx.ext.autosummary", "sphinx.ext.intersphinx", + "sphinx.ext.autosectionlabel", ] intersphinx_mapping = { diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 4b29c7f..81b93c9 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -1,8 +1,6 @@ Usage ===== -.. _installation: - Installation ------------ @@ -11,3 +9,33 @@ To use Python-Roborock, first install it using pip: .. code-block:: console (.venv) $ pip install python-roborock + +Login +----- + +.. code-block:: console + + (.venv) $ roborock login --username username --password password + +List devices +------------ + +This will list all devices associated with the account: + +.. code-block:: console + + (.venv) $ roborock list_devices + + Known devices MyRobot: 7kI9d66UoPXd6sd9gfd75W + + +The deviceId 7kI9d66UoPXd6sd9gfd75W can be used to run commands on the device. + +Run a command +------------- + +To run a command: + +.. code-block:: console + + (.venv) $ roborock -d command --device_id 7kI9d66UoPXd6sd9gfd75W --cmd get_status