JobHistory Capability

[bensweet86]

Discussion around the scope of the PR#669. Currently Valetudo JobHistory capability can show a list of completed cleans. Suggested additional functionality to align with what a Roborock can generate:

1. Summary of all previous cleans - persisted state on vacuum, lifetime cleaning stats.
2. Capability to display the corresponding map for a clean

To implement:

1. Would require a JobSummary type attribute as the elements of total cleaned area / count / time don't align to a standard Job
2. Current release of Valetudo doesn't support persisting multiple maps, with only the current map stored. Could either expand to a snapshot buffer or array that aligns with the map upload miio function.

Thoughts on the merit of this capability before getting distracted with the implementation methodology?

[Hypfer]

For reference, here's how those views look like for dreame:

Click me

And here's roborock:

Click me

Viomi tbd
@depau ?

So a JobSummary could probably contain

• some kind of run id?
• cleanup type
  • full
  • segment
  • area
  • ??
• cleaned area
• duration(?)
• start and/or end timestamp(?)
• a result code
  • success
  • error
  • aborted
  • unknown?

and of course

• the map

The reason for why Valetudo has no understanding of multiple maps is that we don't really know how the map upload actually works.
Well... at least I don't.

What I do know is that it receives a bunch of URLs and then sometimes uploads a map to those which - in the current implementation - will always be the current map since we only request that.
Unfortunately, I have absolutely no idea how to seperate different types of maps there, so if possible, I'd like to avoid that altogether.

Semi-OT sidenote:
The map snapshot feature of roborock vacuums apparently also provides map data previous for each snapshot. I'd assume that it behaves similarily to the cleanup history maps

[depau]

Viomi: (you can also see what the "point clean" feature does)

Screenshots

But as far as I can tell the history is not stored on the vacuum (edit: it looks like it's stored in the cloud)

[bensweet86]

So it looks like there are 3 objects related to each of these:

1. Consolidated cleaning summary - for the roborock vacuums this is the lifetime cleaning staistics, for viaomi its a shorter term record (i.e. 30days) based on the screengrab stored in the cloud. In any case this object contains consolidated area / count / duration metrics
2. Job statistics - individual metrics for each cleaning run / job. For the roborock this history is retained on the vacuum, viomi is not. Statistics are the same with area / count / duration metrics
3. Job map - every job will have a map at some point but upon request the roborocks only store ~17 maps so will not be available in all cases, as with the viomi without the history.

When I was first porting the JobHistory capability in its current form (item 1+2) above PR# 669, there was the thought of storing history within Valetudo vs reading history from the vacuum. I think this needs to be resolved first given the Viomi's functionality as storing in Valetudo creates a lot of complexity beyond simply asking the vacuum for current history states and displaying them.

[depau]

This sounds like a job for a simple sqlite3 database, it shouldn't be too hard to add. Add a base capability, a capability for each vacuum that already stores the history on its own and a common capability for the ones that don't keep history.

Each capability can also have an internal API to feed data to it. The SQLite one will actually store it, the other ones may simply ignore it, or extend the SQLite one and only store what the vacuum software doesn't store.

Then the capability can be registered and the robot class can provide proxy methods to call the capability storage methods that can be called when something needs to be stored.

[Hypfer]

Valetudo should not implement any persistence whatsoever apart from its settings and the preset features.

[bensweet86]

That is ultimately where I landed to not over complicate the job history and poll the vacuum as required - it felt like the Roborocks did enough to not be concerned by the added complexity of persistence. On the map discussion, after I did further testing and subsequently found this issue #86 the could be a refinement to the map process based the following functionality:

• Initialisation of map upload url's via _sync.batch_gen_room_up_url currently exists, each unique URL is based on timestamp
  

  Valetudo/lib/robots/roborock/RoborockValetudoRobot.js

  Lines 112 to 113 in 1541ca3

  	"/api/miio/map_upload_handler?" +
  	process.hrtime().toString().replace(/,/g, "")

• Each time a map upload is initiated by get_map_v1 or get_clean_record_map the response is either "retry" or a fragment from the _sync.batch_gen_room_up_url is returned.
  

  Valetudo/lib/robots/roborock/RoborockValetudoRobot.js

  Line 270 in 1541ca3

  this.sendCloud({"method": "get_map_v1"}).then(res => {

  
  https://github.com/bensweet86/Valetudo/blob/da47933ad18b6dd69d9b789656eff6d589de2223/lib/robots/roborock/capabilities/RoborockJobHistoryCapability.js#L106
• Based on the current functionality the posted / put values (i.e. after the ?) are not returned but the values in the url string are. For example, current response is map_upload_handler but if the '?' was omitted from the URL string below the response would be map_upload_handler[process.hrtime() value]
  

  Valetudo/lib/robots/roborock/RoborockValetudoRobot.js

  Lines 112 to 113 in 1541ca3

  	"/api/miio/map_upload_handler?" +
  	process.hrtime().toString().replace(/,/g, "")

• Link now exists between the map image that has been uploaded to the service and whether the request originated from a get_map_v1 request or something else
• Would require an additional process to store all incoming maps temporarily and then as part of the update map logic test whether this temporarily stored map originated from get_map_v1 and needs to be stored in the the map state or accessed as a one time retrieval. There would be a clean way of achieving this, what I have in my fork is a quick and dirty way to figure out the functionality
  

  Valetudo/lib/robots/roborock/RoborockValetudoRobot.js

  Lines 304 to 309 in 1541ca3

  	parseMap(data) {
  	this.state.map = RRMapParser.PARSE(data);
  	this.emitMapUpdated();
  	return this.state.map;
  	}

[bensweet86]

Example JobSummary;

• unique record id
• state - success / failed / etc
• start / end time
• Duration
• Area
• Error codes

From a Roborock perspective getting the job summary list is reasonably fast but grabbing the map data at the same time will slow the process down. I figured the map should be part of the Job Summary but there is only a need to load if it the map retrieval process is initiated separately.

All of the above fit within the current Job structure without modification and seems to work ok, with the only change to allow the Job entity to store any sort of array structure for its child attributes - ErrorJobAttribute, HistoryJobAttribute, StatisticsJobAttribute, etc.

There is also the question of lifetime cleaning statistics, these need a structure and can be abbreviated into the job summary structure...

https://github.com/bensweet86/Valetudo/blob/da47933ad18b6dd69d9b789656eff6d589de2223/lib/entities/job/Job.js#L24-L41

https://github.com/bensweet86/Valetudo/blob/da47933ad18b6dd69d9b789656eff6d589de2223/lib/robots/roborock/capabilities/RoborockJobHistoryCapability.js#L62-L83