TODO forever when life runs faster than you can afford

Sakis3G as a udev rule

Notice: This post provides links and instructions referring to an old version of Sakis3G script. Page is still available only for historical reasons. Please visit www.sakis3g.org for latest Sakis3G script version.

Question: What is the fastest way to get connected with your 3G network?
Answer: Have Sakis3G script setup as a udev rule! This way Sakis3G script will be executed immediately upon physical connection.

If managed to trigger your interest, check teaser videos below (external link) to further motivate yourself and proceed with this guide:

 
 

On this one (external link) SIM card requires PIN number:
 

Contents

Keep in mind that this kind of installation is not intended for all audiences, as it requires some skills. Especially if troubleshooting is required. Easiest way to install and use Sakis3G can be found here.

1. What do I need?
2. Step #1: Fixing PIN
3. Step #2: Check connectivity
4. Step #3: Enable OSD progress bar
5. Step #4: Create udev rule file
6. Step #5: Reload udev rules
7. Step #6: Test it
8. Uninstall

Note: Throughout this guide, you should be checking for "prompt". That is the symbol which prefixes each command. Dollar sign "$" refers to commands that should be executed as a user, while dash symbol "#" refers to commands that require you to have root privileges.

What do I need?

1. First, you need to be on a i386 architect.
   Other architects will be supported soon.
2. You need pppd for handling PPP connection with your operator.
   On Debian, Ubuntu and openSUSE is provided by ppp package.
3. If your modem needs switching before becoming usable, you also need uudecode.
   On Debian, Ubuntu and openSUSE is provided by sharutils package.
4. For those OSD messages you saw in video, you need libxosd and osd_cat binary. If you do not want OSD, you can perfectly skip that.
   On Debian and Ubuntu they are provided by libxosd2 and xosd-bin packages.
   On openSUSE they are both provided by xosd package.
5. You need at least version 0.1.3+ of Sakis3G script.
   Latest version is available here.


Debian
$ su -
Password:
# apt-get install ppp sharutils xosd-bin
# cd /usr/bin
# wget 'http://sakis.tel4u.gr/sakis3g/legacy/sakis3g.gz'
# gunzip sakis3g.gz
# chmod +x sakis3g



Ubuntu
$ sudo bash
Password:
# apt-get install ppp sharutils xosd-bin
# cd /usr/bin
# wget 'http://sakis.tel4u.gr/sakis3g/legacy/sakis3g.gz'
# gunzip sakis3g.gz
# chmod +x sakis3g



openSUSE
$ su -
Password:
# yast -i ppp sharutils xosd
# cd /usr/bin
# wget 'http://sakis.tel4u.gr/sakis3g/legacy/sakis3g.gz'
# gunzip sakis3g.gz
# chmod +x sakis3g


(Back to contents)

 

Step #1: Fixing PIN

Sakis3G will need your SIM card's PIN number. There are four ways for Sakis3G to be provided your PIN number. You have to choose one of them:

You may as well completely skip this part if your SIM card does not need PIN number. To remove existing PIN number requirement from your SIM card, temporarily put SIM card onto a cellular phone and disable PIN lock.

 

1. Method #1: Leave it alone. If you change nothing, Sakis3G script will be asking PIN number anytime you plug your modem.
   
    
2. Method #2: Setup PIN globally. This method should only be followed if only one SIM card is ever going to be used on this system. Plug an other SIM card, and that card will go PIN locked until you provide it with PUK code.
   
Setup PIN globally
# echo "1234" > /etc/3gpin

    
3. Method #3: Each user have its own PIN number. This method should be followed if computer is shared among different people, while each one of them provides his/her own SIM card or modem. Login with your user account, and have a terminal open.
   
Setup PIN per user
$ echo "1234" > "$HOME/.3gpin"

   ATTENTION: This method works properly only if during modem connection, there is only one user logged in with an X session. Otherwise, you still risk SIM card to get SIM locked.
   
    
4. Method #4: Hard code PIN value inside script. This method is exactly like Method #2, having same restrictions applicable. Its sole advantage is that you do not create an additional file within your "/etc" directory. However, if you ever going to upgrade to a newer Sakis3G version, your PIN settings will be lost. You can either edit Sakis3G script and change SIM_PIN variable, or issue following command.
   
Hard code PIN number
# vi -c ":1,$ s/^SIM_PIN=.prompt.$/SIM_PIN=1234/g" -c ":wq" /usr/bin/sakis3g

    

(Back to contents)

 

Step #2: Check connectivity

On this section, you have to make sure that Sakis3G is able to connect you (handle your modem and operator). This one, is most critical step. If you manage to go beyond that, you are almost done setting up.

Have your modem plugged and wait until it is finished with its usual led-blinking sequence occurring every time it gets plugged (you may also need to wait for your distribution to "calm-down" with hardware discovery process). Now issue following command:

$ /usr/bin/sakis3g connect

 
If command returned flawlessly (with no output at all), you are now connected. Try pinging a destination or opening a web page (mind that Firefox might be in Offline mode, File->Work Offline to disable it). If command returned with an error (and error itself is not descriptive enough):

• Check this page if "Unknown operator XXXXX" is returned.
• Read here and here if your operator provides multiple APNs (Access Point Names).
• Try executing Sakis3G script without "connect" argument, in case menu interface can guide you through connection. Then you can replicate menu interface actions through command line variables.
• If none of these helped you, you may get help from troubleshoot section.

Important: No matter what variables you need to provide for "sakis3g connect" to get you connected, you have to embed them to Sakis3G script for it to work as a udev rule. As an example, if you need to supply the following command (worst case scenario, unknown operator, unknown modem, modem with no operator report command) to get connected:

# FORCE_ISP=20201 ISP_20201_name="Cosmote" FORCE_APN="internet::user:pass" USBMODEM=1199:68a3 USBDRIVER=sierra /usr/bin/sakis3g connect

Then, you need to edit Sakis3G script and provide those values within first lines:

#!/bin/sh
MYVERSION="0.1.3b"
FORCE_ISP=20201
ISP_20201_name="Cosmote"
FORCE_APN="internet::user:pass"
USBMODEM=1199:68a3
USBDRIVER=sierra
###########################################
# Sakis3G
###########################################

This will allow you to connect by simply issuing "sakis3g connect", which is required for next step.

ATTENTION: It is completely pointless to continue beyond this point until "sakis3g connect" is able to get you connected.

 
(Back to contents)

 

Step #3: Enable OSD progress bar

First, you have to enable OSD messages. You need to edit Sakis3G script and enable prefer_osd variable, or use following command:


# vi -c ":1,$ s/^#prefer_osd=/prefer_osd=/g" -c ":wq" /usr/bin/sakis3g


If you only want to see final message "Connected to <your operator>", you can skip to next step. If you want to enable OSD progress bar, the same way demonstrated in videos, you also need to enable VERBOSE variable. Either edit Sakis3G script, or issue following command:


# vi -c ":1,$ s/^#VERBOSE=/VERBOSE=/g" -c ":wq" /usr/bin/sakis3g


You may now test OSD:

$ /usr/bin/sakis3g connect
$ /usr/bin/sakis3g disconnect

(Back to contents)

 

Step #4: Create udev rule file

Now have your modem unplugged. Issue following command:

$ /usr/bin/lsusb
Bus 008 Device 002: ID 0408:03ba Quanta Computer, Inc.
Bus 008 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 007 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 006 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 005 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 001 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub

This will list all currently connected USB devices (along with USB hubs your computer is equipped with), which might be different than the ones on my computer. You now know which devices already exist. Have modem plugged and issue it again:

$ /usr/bin/lsusb
Bus 008 Device 002: ID 19d2:2000
Bus 008 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 007 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 006 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 005 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 001 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub

A new line has appear: This one line represents your modem, and again might be different than my own ZTE MF636. Mind your modem's USB IDs (mine are: Vendor 19d2 and Product 2000). You do need them for next commands (replace 19d2 and 2000 with your own):

# rm -f "/etc/udev/rules.d/10-sakis3g.rules"
# printf "ACTION==\"add\", SUBSYSTEM==\"usb\", " >> /etc/udev/rules.d/10-sakis3g.rules
# printf "ATTRS{idVendor}==\"19d2\", " >> /etc/udev/rules.d/10-sakis3g.rules
# printf "ATTRS{idProduct}==\"2000\", " >> /etc/udev/rules.d/10-sakis3g.rules
# printf "ATTRS{bInterfaceNumber}==\"00\", " >> /etc/udev/rules.d/10-sakis3g.rules
# printf "RUN+=\"/usr/bin/sakis3g toggle\"\n" >> /etc/udev/rules.d/10-sakis3g.rules

You may noticed already, we used "toggle" argument instead of "connect" one we were using so far. "toggle" will eventually force a "connect". Their difference is that "toggle" displays a final message "Connected to..." while "connect" is silent (as you've noticed so far). Issue one last command, to verify that a long single line exists within 10-sakis3g.rules:


# cat "/etc/udev/rules.d/10-sakis3g.rules"
ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="19d2", ATTRS{idProduct}=="2000", ATTRS{bInterfaceNumber}=="00", RUN+="/usr/bin/sakis3g toggle"


If you intend using more than modems, you can repeat "printf" commands for that other modem, without issuing "rm" command anymore. Make sure you choose correct SIM policy if doing so.

 
(Back to contents)

 

Step #5: Reload udev rules

You now have to inform udevd that rules have changed. You can either reboot your Linux system, if you are familiar with this technique by using other operating systems, or issue a rules reload. Reloading rules is somehow different according to udev version installed on your system. Issue this command to discover your version:

# udevadm -V
or, if it didn't work
# udevadm --version
or if no udevadm exists, try
# which udevcontrol

According to output, follow one of these steps:

• If you have version 128 and above, issue "udevadm --reload-rules".
• If you have version 127 and below, issue "udevadm --reload_rules".
• If "udevcontrol" exists instead of "udevadm", issue "udevcontrol reload_rules".

Your system is now, hypothetically, ready.
 
(Back to contents)

 

Step #6: Test it

In order to test it, have modem unplugged (if still plugged). Wait a bit (1-2 seconds) for system to clean up and modem to get electrically reset, and plug it again. If all have gone well, you should be seeing OSD progress bar (if enabled) after modem has finished with its led-flashing initialization sequence. Check if connected by pinging a destination.

If OSD has not appear, do not unplug modem (yet): wait. Wait long enough to check that connection has indeed failed. Connection may happen even if you don't witness OSD messages. If you wish/is-required to troubleshoot, keep in mind that when Sakis3G script is spawned by udevd, stores its log file at "/var/log/sakis3g.log".

If you can't help it to connect, you can either manually use it by issuing "sakis3g connect" and "sakis3g disconnect" commands, or choose to rollback installation following instructions on next section.

(Back to contents)

 

Uninstall

I am really sorry if Sakis3G script failed to help you getting connected. You can consider contacting me through email (my email address is contained within first 10 lines of script) so that we work around your problem, or investigate some more by troubleshooting. If you are still determined to go through uninstall, follow these steps:


1. Remove Sakis3G script, settings and rule file
# rm -f /usr/bin/sakis3g /etc/3gpin /etc/udev/rules.d/10-sakis3g.rules
2. Reload rules now that rule file is deleted
<follow instructions of step #5>
3. As a user
$ rm -f "$HOME/.3gpin" "$HOME/.3gnet"
4. Uninstall packages you installed during first step (*)


(*) Keep in mind that you don't want to uninstall ppp package, if you wish to try other software for connecting you with your 3G operator. If you insist doing it, you may need to reinstall it later.