/
usb_moded-doc.txt
272 lines (190 loc) · 10.8 KB
/
usb_moded-doc.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
USB_MODED use and API description/overview.
==========================================
Usb_moded is a relatively simple daemon which tracks the
usb cable connection status and activates a certain USB
profile based on that.
To do this it has a number of built in common profiles,
an optional application launcher (app_sync) and configurable
dynamic modes.
All the system wide communication goes over the DBus system bus,
while application launching is handled on the session bus.
Thus if you need this functionality, usb_moded needs to be started
with the session.
(functionality not verified yet on multi-user setups. See TODO)
Usb cable detection is supported by several different methods.
Old deprecated hal, through Nokia's own battery monitoring bme,
or the preferred udev option. (This has to be chosen at compile time)
Starting usb_moded
-------------------
Simply start with usb_moded.
usb_moded --help will give you more details
Status and configuration query/setting
---------------------------------------
The current status can be queried any time over DBus. From a program
using a method call or using dbus-send.
dbus-send --system --type=method_call --print-reply --dest=com.meego.usb_moded /com/meego/usb_moded com.meego.usb_moded.mode_request
Similary a mode can be set.
dbus-send --system --type=method_call --print-reply --dest=com.meego.usb_moded /com/meego/usb_moded com.meego.usb_moded.set_mode string:'<mode_name>'
Even the configuration can be set over DBus (this will set either the gconf key or use the settings file)
dbus-send --system --type=method_call --print-reply --dest=com.meego.usb_moded /com/meego/usb_moded com.meego.usb_moded.set_config string:'<mode_name>'
To get the currently stored default mode from the config:
dbus-send --system --type=method_call --print-reply --dest=com.meego.usb_moded /com/meego/usb_moded com.meego.usb_moded.get_config
The supported modes can be queried over dbus as follows:
dbus-send --system --type=method_call --print-reply --dest=com.meego.usb_moded /com/meego/usb_moded com.meego.usb_moded.get_modes
=== WITH GCONF ONLY ===
However this can also be optionally handled by setting the following GConf key (gconf has to be compiled in).
/Meego/System/UsbMode (querying and setting can be done as follows:
gconftool-2 -g /Meego/System/UsbMode
gconftool-2 -s /Meego/System/UsbMode --type=string <mode_name>
=== END WITH GCONF ONLY ===
Usb_moded will also broadcast changes and errors over the system bus.
This will happen on the com.meego.usb_moded interface
For regular signals: sig_usb_state_ind
And errors: sig_usb_state_error_ind
More info and details in usb_moded-dbus.h
There is also a configuration file and some configuration directories under /etc/usb-moded
It should have some pre-filled fields for the default mass-storage profile
The first one would be mountpoints, this defines which device/filesystem entry should be
exported over mass-storage (this ideally also has an entry in /etc/fstab). You can add more
filesystems to the mount option, by making it a comma-seperated list in case there are
several exports (like internal mmc and sd card for example)
[mountpoints]
mount = /dev/mmcblk0p1
The following option plays with certain sync options that exist and have to be set per
fs and thus cannot be handled by setting them in /etc/modprobe.d/....conf
[sync]
nofua = 1
This mount is the alternative mountpoint for in case something goes wrong. Usb_moded
will mount a 512 RO tmpfs on that location to mitigate potential disasters on the system,
and make clear to programs on the device that something is wrong with the fs they want to use.
[altmount]
mount = /home/user/MyDocs
Also the default usb mode can be configured there. For example:
[usbmode]
mode = ask
The other settings and config dirs will be handled later in the appsync and dynamic modes part.
(This is optional and can be compiled out)
There is also an optional network configuration. The default ip set for usb networking is 192.168.2.15
(for Meego/Nemo). However this can be configured by hand in the ini file also.
For example:
[network]
ip = 10.0.0.2
interface = usb1
gateway = 10.0.0.1
By default usb0 will be used, so no need to fill it in if not needed. The gateway setting is also optional
and will not be set if there is no value filled in.
If the ip is set to dhcp, usb_moded will try to use dhcp to configure the network (requires dhclient atm)
The network configuration can also be set with dbus method calls via the net_config method.
This requires two strings as arguments. Supported are: ip, interface and gateway
for exmaple:
dbus-send --system --type=method_call --print-reply --dest=com.meego.usb_moded /com/meego/usb_moded com.meego.usb_moded.net_config string:'ip' string:'192.168.2.15'
Usb_moded will generate a random mac address for the g_ether driver. Thus when plugging in the device repeatedly the mac address will not
change and udev rules / network manager etc will not think it is a new device each time.
This mac is stored using the default modprobe configuration and thus will be in /etc/modprobe.d/g_ether.conf
If this file exits usb_moded will assume there is a default mac set and will not do anything.
Functional overview
--------------------
When a usb cable is insertion is detected usb_moded will start to act.
First it will warn on the system bus that a cable is connected.
Then it will check what the configuration setting is. Thus it knows how to act.
If it is a known configured mode it will load the correct modules (after checking
what is loaded and clean up if needed), perform other needed operations and
make sure the chosen mode works. At this point it will broadcast which mode
is set to warn other programs.
If things fail it will go to undefined state (and also broadcast this).
There is the special case where the config option is called "ask". In this
case usb_moded will enable a fake mass_storage profile to enable enumeration
so charging can be done, and wait until it is instructed which mode needs
to be selected. Thus this state can be used for an UI that will set the right
mode on user interaction. For this purpose usb_moded broadcasts it goes in ask
mode, and also stays in ask mode until a chosen mode is requested or the cable
is disconnected. This also avoids race conditions in case the UI starts
after a cable is inserted and usb_moded has also been started. The UI can then
query the state to know if it needs to show a selection dialog or not.
On disconnect usb_moded will broadcast a disconnect signal, so that all programs
that use the usb interface/mode know that a cable is disconnected and then can act
(if needed) on the changed situation. It will then do all the necessary to reset
the system to a clean state.
Appsync feature
---------------
In case you need some program to be started along some mode the appsync option
provides this option.
Only condition is that it can be activated by dbus and that (preferably) it will
notify usb_moded that it is ready by ready_method call on the session bus.
This ready method call is just calling the regular usb_moded interface, but now
on the session bus, with as argument the program name as defined in the config file.
To achieve this you need to have a config file in /etc/usb-moded/run.
Best practice would be giving it a descriptive name followed by .ini
For example:
/etc/usb-moded/run/foo.ini
Where foo.ini would be:
[info]
name = foo
mode = foo_mode
launch = com.meego.foo
Those files will be read on start and usb_moded will keep a list of apps to launch
for a certain mode. This also means that if you change the files or add/remove some
you need to restart usb_moded. Later when the mode is activated, usb_moded will start
each of them after the module has been loaded and keep track if they have been started.
It will warn you if that failed. This works together with an optional softconnect option
that will need kernel support. (Nokia only atm)
Dynamic modes
-------------
Dynamic modes will only work if the appsync feature is enabled, since it is expected
that this will need some special userspace programs. These will be started
through the appsync part and thus need their own config files in the normal appsync dir.
Dynamic modes need to be defined with an ini file also but this time in
/etc/usb-moded/dyn-modes.
The format would be for example for : /etc/usb-moded/dyn-modes/dyn-mode-1.ini
[mode]
name = dyn-mode-1
module = h_dyn-mode
appsync = 1
network = 1
network_interface = usb0
Only the mode name and module are mandatory.
If appsync is not defined or explicitly set to 0 it will not be used.
Trigger support
---------------
This will only work if udev is configured as it is a udev trigger.
Atm only one trigger is supported.
This is to support special equipment that will send a trigger event.
Usually this will be in combination with a dynamic mode.
You need to add the following to usb-moded.ini to get a trigger activated
For example
[trigger]
path = /sys/devices/platform/musb_hdrc
udev_subsystem = platform
mode = mass_storage
property = TRIGGER_CMD
Softconnect support
-------------------
In some cases gadget drivers are not active by default. (for example with the android gadget driver)
As there is no standard softconnect path, to use this feature it will have to be enabled
in the config file.
[soft_connect]
soft_connect_path = /path/where/softconnect/is
NOTE: It is expected that the value to connect is "connect", and "disconnect" to disconnect.
Android gadget driver support
-----------------------------
This will need usb_moded to be compiled after being configured with --enable-android
The regular gadget support will not work anymore as the android gadget driver is
supposed to be used built-in. A thusly build usb_moded will be usable on stock
android kernels.
atm only networking mode is fully supported, mass-storage partly.
Also note that the softconnect has to be configured!!!
rescue mode
-----------
When started with -r usb_moded will always enable developer mode (networking)
if it can. This is a debug feature and should not be used in a final image.
Turning it off when the device is booted completely can easily be done over dbus.
dbus-send --system --type=method_call --print-reply --dest=com.meego.usb_moded /com/meego/usb_moded com.meego.usb_moded.rescue_off
config files and config file merging
------------------------------------
The main config file for usb_moded is /etc/usb-moded/usb-moded.ini
If this does not exist usb_moded will create one for you, which will default
to setting up a default network with ip 192.168.2.15 and uses the g_ether module.
The different sections of the config file can be split out in different ini files,
however take into account usb_moded will need to be restarted to merge these in a
new usb-moded.ini file. As usb_moded will check if new files were added to the /etc/usb-moded
directory and refresh the main ini file as needed on start-up.