doc: update document especially available_ecu_ids

[obi-t4]

Description

Update document especially availale_ecu_ids.
Also docs/SERVICES.md has been updated according to DEVELOPMENT.md

Check list

N/A (no test are needed)

• test file that covers the bug case(s) is implemented.
• local test is passed.

Bug fix

Current behavior

Current specification for available_ecu_ids is unclear.

Behaivor after fix

This PR adds more descriptions.
And adds the description who need to filtering out the update reqest.

Related links & ticket

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
otaclient/app
__init__.py	0	0	100%
__main__.py	3	3	0%	16–19
common.py	268	15	94%	55, 103, 185, 200, 275–277, 287, 296–298, 404, 416, 535–539
configs.py	71	0	100%
copy_tree.py	81	3	96%	45, 96, 125
downloader.py	270	44	84%	69, 82–83, 300, 305, 309, 327–328, 378–382, 401–411, 436–454, 463, 538–540, 556, 576–594
ecu_info.py	59	7	88%	78–79, 92, 97, 120–121, 130
errors.py	179	5	97%	55, 58, 116, 119, 139
interface.py	17	4	76%	32, 43, 47, 51
log_setting.py	26	7	73%	27–28, 55–65
main.py	31	2	94%	43–44
ota_client.py	318	87	73%	69–70, 92, 198–222, 259–261, 271–276, 286–288, 331–332, 337–344, 357–371, 377–380, 405–429, 443–448, 457, 460–468, 547, 552–570
ota_client_call.py	38	6	84%	42–44, 80–82
ota_client_service.py	29	3	90%	58–60
ota_client_stub.py	343	75	78%	81–90, 99–101, 106, 138, 165, 168, 250, 270, 272, 296, 341, 402, 470–471, 498, 505, 525–536, 540–554, 558–561, 613, 700–709, 741–791, 794
ota_metadata.py	314	31	90%	145, 150, 186–187, 197–201, 213, 271, 304–306, 323–326, 406, 409, 417–419, 432, 441–446, 719–730
ota_status.py	15	2	87%	36, 44
proxy_info.py	51	7	86%	82–87, 122–129, 137–138
update_stats.py	105	2	98%	162, 172
otaclient/app/boot_control
__init__.py	4	0	100%
_cboot.py	286	139	51%	91–99, 108–121, 127–130, 134, 141, 145, 149, 153–157, 161–165, 170–189, 192–235, 241, 244, 247, 250, 253, 256, 259, 262–263, 266–267, 270–274, 277–278, 293, 296, 329, 356–359, 369–372, 380, 419, 436–439, 448–451, 456–458, 467–473, 476, 483, 513–515, 552–554, 557–567, 570–575
_common.py	363	155	57%	65–74, 83–84, 88–89, 97–98, 109–110, 115–120, 125–130, 139, 148, 152, 156, 160, 174–177, 187–191, 196, 200, 210–214, 222–234, 245–249, 253–257, 269–271, 283–285, 296–310, 320–341, 360–376, 393–404, 412–418, 467, 489–496, 518–539, 577–578, 632, 636–637, 640–648, 652–655, 705–706, 709, 723–731, 746–747, 816–819, 840–843, 856–857, 866
_errors.py	47	19	60%	43–69, 89–90
_grub.py	402	90	78%	202, 224, 241–244, 250–254, 280–281, 288–308, 318–320, 328–330, 334, 337, 340, 343, 365–366, 384–385, 433, 468, 488–493, 506, 533–542, 679–681, 708–711, 720, 759–763, 807, 814, 833–836, 843–846, 849, 856, 883–885, 906–908, 911–916, 919–924
_rpi_boot.py	260	121	53%	89–91, 97–152, 176–178, 184–186, 199–201, 207–209, 222–243, 248, 252, 256, 260, 294, 324, 327–329, 337, 346–348, 358–361, 365–372, 451–455, 474–477, 482, 485, 506–511, 514–522, 525–533, 545–548, 552–554, 557
configs.py	57	2	96%	46–47
firmware.py	32	5	84%	63, 65, 76–78
protocol.py	28	5	82%	40, 44, 48, 52, 60
selecter.py	39	27	31%	45–69, 77–94
otaclient/app/create_standby
__init__.py	12	5	58%	30–36
common.py	216	45	79%	74, 77–78, 82–95, 141, 189–197, 200–203, 207, 218, 292–300, 312, 356–361, 377–378, 392–396, 421–422
interface.py	19	3	84%	55, 59, 63
rebuild_mode.py	99	9	91%	83–101, 128
otaclient/app/proto
__init__.py	31	3	90%	37, 44–45
_common.py	419	49	88%	85, 163, 170, 182–184, 203, 208, 219, 256, 262, 267, 298, 302, 306, 363, 380, 403, 464, 471, 474, 494, 501, 503, 529, 535, 538, 540, 565, 571, 574, 576, 605, 609, 611, 625, 642, 670, 673, 677, 680, 708, 714, 761–766, 797
_ota_metafiles_wrapper.py	84	13	85%	37, 40–42, 112–116, 122–125
_otaclient_v2_pb2_wrapper.py	276	36	87%	87, 90–93, 175, 183, 197, 207, 210–213, 258, 261, 264–265, 285, 305, 385, 452, 505, 513–515, 519–522, 525–530, 551, 559, 573, 581, 595
streamer.py	43	8	81%	32, 47, 65–66, 71, 80–81, 99
wrapper.py	4	0	100%
otaclient/ota_proxy
__init__.py	29	0	100%
__main__.py	21	21	0%	16–71
cache_control.py	84	9	89%	50, 75, 79, 95, 117, 125, 141, 147–148
config.py	16	0	100%
db.py	136	12	91%	66, 76–79, 108–110, 129, 162, 171–172, 187, 214
errors.py	10	0	100%
orm.py	115	10	91%	37, 91, 96, 101, 107, 113, 140–141, 231, 235
ota_cache.py	389	63	84%	146, 198, 214–217, 235–248, 260, 305–306, 311–312, 328, 384–385, 425–426, 531, 546–550, 684–685, 717–718, 729, 768–773, 786–799, 844, 852–854, 909–912, 916–920, 938–940, 994, 1001–1002, 1004–1005, 1008, 1038–1042
server_app.py	122	43	65%	102–108, 112–121, 173, 175, 181, 191–196, 204, 216–264, 275–277, 283–285
utils.py	28	1	96%	31
TOTAL	5889	1196	80%

[Bodong-Yang]

I think this line should also prefixed with NOTE(or even WARNING), as user might think empty available_ecu_ids means not update any ECUs.
Also, I think this is backward-compatibility?

[Bodong-Yang]

as otaclient can work not only with web.auto agent, but also other implementation that using otaclient. For other implementation, they can use other kinds of implementation to generate the update request. The use of available_ecu_ids is required by web.auto agent, but it is not a requirement to other implementation that uses otaclient.

[Bodong-Yang]

@obi-t4 After some consideration, I agree that all OTA client user should follow the spec of available_ecu_ids, a.k.a, available_ecu_ids should represent the ECUs to be updated, but the use of available_ecu_ids is not mandatory.

[Bodong-Yang]

( We can add another line says that alternative client implementation can also use available_ecu_ids yield, but it is not mandatory.

[obi-t4]

@Bodong-Yang
update in a00549d, thanks!

[Bodong-Yang]

@obi-t4 I have some more questions, please have a check, thank you!

What if some ECUs presented in secondary_ecus field, but not listed in available_ecu_ids, should OTA client include the status of these ECUs in the status response? In other word, should otaclient tracks ECU that listed in secondary_ecus but not in available_ecu_ids?

Another question is, should we expect that secondary_ecus and available_ecu_ids are synced? A.k.a, available_ecu_ids are always either the same as secondary_ecus, or available_ecu_ids==<my_ecu_id> + secondary_ecus?

[obi-t4]

@Bodong-Yang

What if some ECUs presented in secondary_ecus field, but not listed in available_ecu_ids, should OTA client include the status of these ECUs in the status response? In other word, should otaclient tracks ECU that listed in secondary_ecus but not in available_ecu_ids?

secondary_ecus and available_ecu_ids are the independent information.
All secondary_ecus responses that can respond should be included in the Status response.
available_ecu_ids is the information for ota-client user(=caller, aka agent).

OTA client doesn't have a ECU filtering policy.

Another question is, should we expect that secondary_ecus and available_ecu_ids are synced? A.k.a, available_ecu_ids are always either the same as secondary_ecus, or available_ecu_ids==<my_ecu_id> + secondary_ecus?

they are the independent information.

[Bodong-Yang]

Thank you for the updates!