Hey Martin,

On Thu, Jan 12, 2017 at 9:46 PM, Martin MOKREJŠ <mmokr...@gmail.com> wrote:
> I propose improving mmcli manpage. The EXAMPLES section should start with:
> 1. how shall one figure out where is any modem seen
> 2. how to read the status, shown "registered" and later "connected" states.
> 3. although it seems it is not relevant to mmcli, a hint where to go next to 
> get use of the "connected" modem would be very helpful.
>

Any patch to increase documentation is totally welcome; even if they
may not be perfect from the beginning, at least we would start the
ball rolling to improve the docs.

>
> Aleksander Morgado wrote:
>> On Thu, Jan 12, 2017 at 3:49 PM, Martin MOKREJŠ <mmokr...@gmail.com> wrote:
>>> # mmcli  --connect -m /org/freedesktop/ModemManager1/Modem/0
>>> error: no bearer was specified
>>
>> --connect is a bearer action, you need to pass a bearer object path,
>> not a modem object path.
>
> I think "mmcli --help" could show some hints in the bearer section, like 
> --create-bearer="apn=internet.t-mobile.xx"
>

I don't like that as users may think the hints are the only allowed
parameters... What we should do is make sure we keep the manpage up to
date, which I don't think is currently the case, it was written a
looong time ago :)

>>
>>> # mmcli  --list-bearers -m /org/freedesktop/ModemManager1/Modem/0
>>>
>>> No bearers were found
>>
>> Ok, so you would first need to create a bearer with
>> --create-bearer="key=value,..." in one of the modems.
>>
>> E.g.
>>
>> mmcli -m 0 --create-bearer="apn=internet"
>
> Yeah, but I again had to rescan my devices and only then I was able to use a 
> modem. And it appeared at different index pos. Again, the EXAMPLES section 
> could be improved so that a user can use it as a real step-by-step manual to 
> get connected (to have a network device with an IP!).

Yep, agree, it would be good to have such a sequence in the EXAMPLES section.

>
>>
>> See:
>> https://www.freedesktop.org/software/ModemManager/api/latest/gdbus-org.freedesktop.ModemManager1.Modem.html#gdbus-method-org-freedesktop-ModemManager1-Modem.CreateBearer
>>
>>> # mmcli  --bearer -m /org/freedesktop/ModemManager1/Modem/0
>>> error: invalid path or index string specified: '-m'
>>
>> --bearer expects a bearer path or index (help says "--bearer=[PATH|INDEX]")
>>
>>> # mmcli  --bearer
>>> error: no actions specified
>>
>> Same thing, --bearer expects a bearer path or index (help says
>> "--bearer=[PATH|INDEX]")
>>
>>> # mmcli  -b
>>> error: no actions specified
>>
>> Same thing, --bearer expects a bearer path or index (help says
>> "--bearer=[PATH|INDEX]")
>>
>>> # mmcli  -b -m /org/freedesktop/ModemManager1/Modem/0
>>> error: invalid path or index string specified: '-m'
>>
>> Same thing, --bearer expects a bearer path or index (help says
>> "--bearer=[PATH|INDEX]")
>
>
> How about mmcli being more friendly and output after the error message a list 
> of my modems?
>

Truth be told, I think there are more critical things to include in
mmcli, like a machine-friendly output of the results that may be used
easier in scripts. I know people that parse the output of mmcli
commands in shell scripts (me included) and that is totally not
ideal...

> # mmcli -L
>
> Found 1 modems:
>         /org/freedesktop/ModemManager1/Modem/2 [huawei] E3372
>
> #
>
> From "experience" I now know it is at index 2. Don't expect users are that 
> smart when doing first steps. ;-)
>

The index isn't fixed. The index just happens to be the number of
modems detected since the startup of ModemManager; if you unplug and
replug the modem the index will change. If you want to have a "name"
for a modem that doesn't change e.g. across reboots, you can tag the
USB port where the modem is available with a label that may be used
later on instead of the modem index; e.g. "mmcli -m USB1" or so. See:
https://sigquit.wordpress.com/2016/10/06/naming-devices-in-modemmanager/

>>
>>>
>>>
>>> # mmcli  --set-power-state-on -m /org/freedesktop/ModemManager1/Modem/0
>>> error: couldn't set new power state in the modem: 
>>> 'GDBus.Error:org.freedesktop.ModemManager1.Error.Core.WrongState: Cannot 
>>> set power state: not in disabled state'
>>
>> Your modem is already registered, so it is already in "on" power state.
>
> If one doesn't know what are all the options, it is hard to find what needs 
> to be done in what order. The help text could say how the power-related 
> options relate to "--enable", "--disable". For example, "not applicable when 
> connected/enabled/whatever".
>

Help text in --help doesn't allow too many explanations. Such things
should be included in either the mmcli manpage or directly in the
ModemManager gtk-doc documentation published in the website.

>>
>>>
>>> The mmcli --help-all are too cryptic to me. I failed to find a way to 
>>> really get the device connected. There should be some typical examples at 
>>> the end of --help-all output. Even figuring out I need to specify "-m 
>>> /org/freedesktop/ModemManager1/Modem/0" took me a long while. Why sometimes 
>>> it is rejected as a wrong argument I do not know (shown above).
>>
>> For launching a connection you can use the "manual" way of creating
>> the bearer object and then --connect; OR, easier, just
>> "--simple-connect" in the modem object. E.g.:
>>
>> mmcli -m 0 --simple-connect="apn=internet"
>
> And the "simple" seemed like a provisional solution, probably only a partial 
> "something". So what is "full" connect then?
>

Simple isn't a provisional solution, it's just that: simple :) The
"Simple.Connect()" command does everything you may need to do to get
the modem connected:
  * Unlock PIN, if SIM-PIN locked.
  * Get the modem enabled.
  * Get the modem registered in a network.
  * Create a bearer.
  * Connect the bearer.

The manual creation of the bearer and so on lets you do more
"experienced" things, like e.g. creating multiple data bearers that
may be connected in parallel to different APNs.

NetworkManager, the main user of ModemManager, uses Simple.Connect()
for example.

>>
>> See 
>> https://www.freedesktop.org/software/ModemManager/api/latest/gdbus-org.freedesktop.ModemManager1.Modem.Simple.html#gdbus-method-org-freedesktop-ModemManager1-Modem-Simple.Connect
>
> So I had:
> # mmcli  --simple-status -m 2
>
> /org/freedesktop/ModemManager1/Modem/2
>   -------------------------
>   Status |          state: 'connected'
>          | signal quality: '38' (recent)
>          |          bands: 'unknown'
>          |    access tech: 'lte'
>   -------------------------
>   3GPP   |   registration: 'home'
>          |  operator code: '23001'
>          |  operator name: 'T-Mobile CZ'
>          |   subscription: 'unknown'
>
> #

The Simple Status just contains the main information that a normal
user of ModemManager would require.


-- 
Aleksander
https://aleksander.es
_______________________________________________
ModemManager-devel mailing list
ModemManager-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/modemmanager-devel

Reply via email to