SIM Unlocker for broadband modem K3765-Z

Gero Treuner (Author and Copyright 2011-09-09)
Stuttgart (Germany)
http://www.70t.de/projects/k3765-z_unlock/
License GPLv3+

Summary

This is a script to unlock the SIM card on a broadband (GPRS, UMTS) modem contained in a USB device after insertion. Although it is designed and tested for the model "K3765-Z" (distributed by Vodafone) it should be no hard work to make it fit for other devices.

It was motivated by annoying PIN requesting popups and too many checks whether the device is ready.

Prerequisites

GNU/Linux or other POSIX machine
UDEV activated
"chat" program installed (usually part of PPP)

Files contained in this package

README: This file
k3765-z_unlock: The main script
k3765-z_unlock.8 (formatted): Manual page
51_vmc_zte_local.rules: UDEV rules

Installation

Step 1.

Choose whether you want to install the script for multiple users, or for a single user. Permissions should be limited to a specific group for multiple users, or to your user for single-user installation. This is because the required PIN of the SIM card should be kept as private as possible.

For multiple users, get the name of the group. If you don't want to create a new group. it would be a good idea to choose the group to which the modem device is set ("dialout" on Debian).

Step 2.

Choose places where the main script, the manual page and the run directory should be located. Recommended directories are:

Multi-user installation

Main script:	/usr/local/sbin
Manual page:	/usr/local/share/man/man8
Run:	/var/run/k3765-z_unlock

Single-user installation ($HOME means your home directory):

All of above:

$HOME/.k3765-z_unlock

Step 3.

Check the path of the chat command. Probably that is /usr/sbin/chat. Check whether the dash shell is available.

Step 4.

Get the serial number of your modem device: Connect it to your computer and run this command (eventually adapt chat's directory):
/usr/sbin/chat -t 1 -e 'OK-AT-OK AT+CGSN' </dev/ttyUSB1 >/dev/ttyUSB1

Step 5.

Step 6.

Create the run directory:
mkdir <run-path-chosen-in-step-2>

For multi-user installation change group and permissions to this:
chown :<group-chosen-in-step-1> <run-path-chosen-in-step-2>
chmod g+w <run-path-chosen-in-step-2>

For single-user installation change permissions to this:
chmod og-rwx <run-path-chosen-in-step-2>

Step 7.

Edit the file k3765-z_unlock:

Set VARRUNDIR to <run-path-chosen-in-step-2>.
Set DEVICE_SERIAL to <serial-number-in-step-4>
Set DEVICE_PIN to the PIN code to unlock the SIM card.
If <chat-path-in-step-3> is not in one of the directories /usr/bin, /bin, /usr/sbin, then add the path to PATH variable.
If the dash shell is not available as checked in step 3, then change the shell in line 1 to /bin/bash (which hopefully is there).

Step 8.

Install the edited k3765-z_unlock file to <main-script-path-chosen-in-step-2>.

For multi-user installation change group and permissions to this:
chown :<group-chosen-in-step-1> <main-script-path-chosen-in-step-2>
chmod o-rwx <main-script-path-chosen-in-step-2>

Step 9.

Install k3765-z_unlock.8 to <manual-page-path-chosen-in-step-2>

Step 10.

Edit the file 51_vmc_zte_local.rules to contain <main-script-path-chosen-in-step-2> as value for the variable "RUN", which must be enclosed in quotation marks.

Step 11.

Install the UDEV rules contained in the edited file 51_vmc_zte_local.rules. How this is done depends on your distribution. On Debian just copy the file to the directory /etc/udev/rules.d. See the manual pages for UDEV and the documention of your Linux (or other POSIX system) distribution.

Step 12.

Start operation by executing the command:
<main-script-path-chosen-in-step-2> -force

Troubleshooting

Of course the USB broadband modem must be plugged to the computer.

Device /dev/ttyUSB1:

If the device /dev/ttyUSB1 is not there then something is wrong with your general system setup. See the documention of the system in this case.

If you have multiple USB devices providing terminal devices, the path of the TTY device may be different than /dev/ttyUSB1. See the system log or /sys filesystem for more information.

This script is not designed to handle varying devices names. This would not be easy, because the modem provides multiple devices, and the right one must be selected among them.

Control file:

If the control file with name "accepted" (directory selected in installation step 2, for instance the complete path could typically be /var/run/k3765-z_unlock/accepted) is not present, the script is inactive because risk to permanently lock the SIM card is avoided.

To start running the script the -force option is required. If unsure whether this is your "last try" first reset the retry counter of your SIM card by entering your PIN manually — if accepted 2 more attempts should not harm. Then execute the command k3765-z_unlock from the directory where you installed it (from installation step 2, for instance /usr/local/sbin, used in this example):
/usr/local/sbin/k3765-z_unlock -force

After that check if the "accepted" file mentioned above is present now. if not, continue with the next item.

Conversation with modem:

The chat program, which is used to communicate with the modem, can log via syslog. The output location depends on your configuration. Examine some files in the directory /var/log, chances should be good for "messages", "syslog" or "debug".

The logging is enabled when k3765-z_unlock is invoked with the -force option, or you can enable it permanently be editing the script, changing the variable DEBUG to "true".

A good example looks like this:

		chat[27965]: abort on (ERROR)
		chat[27965]: abort on (+CPIN: READY)
		chat[27965]: abort on (+CPIN: SIM PUK)
		chat[27965]: expect (OK)
		chat[27965]: alarm
		chat[27965]: send (AT^M)
		chat[27965]: expect (OK)
		chat[27965]: ^M
		chat[27965]: OK
		chat[27965]:  -- got it
		chat[27965]: send (AT+CGSN^M)
		chat[27965]: expect (356561040123456)
		chat[27965]: ^M
		chat[27965]: ^M
		chat[27965]: 356561040123456
		chat[27965]:  -- got it
		chat[27965]: send (AT+CPIN?^M)
		chat[27965]: expect (+CPIN: SIM PIN)
		chat[27965]: ^M
		chat[27965]: ^M
		chat[27965]: OK^M
		chat[27965]: ^M
		chat[27965]: +CPIN: SIM PIN
		chat[27965]:  -- got it
		chat[27965]: send (AT+CPIN=1234^M)
		chat[27965]: expect (OK)
		chat[27965]: ^M
		chat[27965]: ^M
		chat[27965]: OK
		chat[27965]:  -- got it

On errors try to enter the commands seen above manually and check the results. This is done with so-called terminal programs like miniterm or kermit.

As these are standard commands, you can try to get the support of the phone provider to solve the problem (ha ha).

Still does not work:

Although the author of this script is going to answer general questions and is interested in fixing errors regarding this script, he definitely does not have time to solve individual problems regarding your setup or environment. Please keep in mind that the work behind the script is done in spare time and is available without a fee.
Please refer to internet resources, or look for someone near to you who can do that, like an administrator.

Caveats

During the communication with the modem the PIN is visible in the list of processes (for instance with the ps command) which is not really secure.

To solve this some arguments for the chat programm must be delivered via a file. This suggests to introduce a configuration as base for generating this file. As the handling of configuration is more in the domain of operating system distributions, this is left out at the moment.
Maybe someone tests more broadband adapters or adds support for them, or another one needs multiple configurations for a bunch of modems — we will see what requirements matter.

[Legal Info / Impressum / Data Protection Declaration] / Last change 2011-09-09