Debian Codegraph @

src/scripts/device/README.rst

raw
1 Device Profile/Route Management Scripts
2 =======================================
3
4 These scripts are tasked to select appropriate profiles and routes for each
5 device.
6
7 Hooks
8 -----
9
10 .. list-table:: Hooks triggered by changes in the graph
11 :header-rows: 1
12 :width: 100%
13 :widths: 20 10 20 50
14
15 * - Hook name
16 - File
17 - Triggered by
18 - Action
19
20 * - device/select-profile
21 - select-profile.lua
22 - device added or EnumProfiles changed
23 - schedules a 'select-profile' event
24
25 * - device/select-route
26 - select-routes.lua
27 - device added or EnumRoute changed
28 - updates the device info cache with the latest routes and schedules a 'select-routes' event, if needed
29
30 * - device/store-user-selected-profile
31 - select-profile.lua
32 - device Profile param changed
33 - stores profile into the state file if it was selected by the user (profile.save == true)
34
35 * - device/store-or-restore-routes
36 - select-routes.lua
37 - device Route param changed
38 - stores or restores Route selections based on the current state; may push a 'select-routes' event to update properties
39
40 .. list-table:: Hooks for the select-profile event, in order of execution
41 :header-rows: 1
42 :width: 100%
43 :widths: 20 20 60
44
45 * - Hook name
46 - File
47 - Description
48
49 * - device/find-calling-profile
50 - find-voice-call-profile.lua
51 - selects a profile based on the state of calls
52
53 * - device/find-stored-profile
54 - state-profile.lua
55 - selects the profile that has been stored in the state file (user's explicit selection)
56
57 * - device/find-preferred-profile
58 - find-preferred-profile.lua
59 - selects the profile based on device configured priorities
60
61 * - device/find-best-profile
62 - find-best-profile.lua
63 - finds the best profile for a device based on profile priorities and availability
64
65 * - device/apply-profile
66 - apply-profile.lua
67 - applies the selected profile to the device
68
69 .. list-table:: Hooks for the select-routes event, in order of execution
70 :header-rows: 1
71 :width: 100%
72 :widths: 20 20 60
73
74 * - Hook name
75 - File
76 - Description
77
78 * - device/find-stored-routes
79 - state-routes.lua
80 - restores routes selection for a newly selected profile
81
82 * - device/find-best-routes
83 - find-best-routes.lua
84 - finds the best routes based on availability and priority
85
86 * - device/apply-route-props
87 - state-routes.lua
88 - augments the selected routes to include properties stored in the state file (volume, channel map, codecs, ...)"
89
90 * - device/apply-routes
91 - apply-routes.lua
92 - applies the selected routes to the device
93
94 select-profile event
95 --------------------
96
97 High priority event to select a profile for a given device. The event hooks
98 must also apply the profile.
99
100 The event "subject" is the device (`WpDevice`) object.
101
102 This event has no special properties.
103
104 .. list-table:: Exchanged event data
105 :header-rows: 1
106
107 * - Name
108 - Description
109
110 * - selected-profile
111 - The selected profile to be set:
112 - Type: string, containing a JSON object
113 - The JSON object should contain the properties of the Profile param
114
115 select-routes event
116 -------------------
117
118 High priority event to select routes for a given profile. The event hooks
119 must also apply the routes.
120
121 The event "subject" is the device (`WpDevice`) object.
122
123 .. list-table:: Event Properties
124 :header-rows: 1
125
126 * - Property name
127 - Description
128
129 * - profile.changed
130 - true if a new profile has been selected / false if only the available routes changed
131
132 * - profile.name
133 - the active profile's name
134
135 * - profile.active-device-ids
136 - json array of integers containing the active device IDs for which to select routes
137
138
139 .. list-table:: Exchanged event data
140 :header-rows: 1
141
142 * - Name
143 - Description
144
145 * - selected-routes
146 - The selected routes to be set:
147 - Type: map<string, string>
148 - The keys are device IDs (as represented in EnumRoute)
149 - The values are JSON objects like this: { index: <a route index>, props: { <object with route props> } }