mirror of https://gerrit.osmocom.org/pysim
Update README
* Add instructions for convenient install on Archlinux * Update hyperlinks, replace http with https * Fix incorrect implicit code markup by explicit markup * Fix Typos, etc. * Adjust headlines Change-Id: I96ac0f7caea8a28d2bbeba9e54911b4bd44aaad5
This commit is contained in:
parent
b07a3e9c87
commit
f658c55745
120
README.md
120
README.md
|
@ -1,8 +1,8 @@
|
||||||
pySim-prog - Utility for programmable SIM/USIM-Cards
|
pySim - Read, Write and Browse Programmable SIM/USIM Cards
|
||||||
====================================================
|
====================================================
|
||||||
|
|
||||||
This repository contains a Python-language program that can be used
|
This repository contains Python programs that can be used
|
||||||
to program (write) certain fields/parameters on so-called programmable
|
to read, program (write) and browse certain fields/parameters on so-called programmable
|
||||||
SIM/USIM cards.
|
SIM/USIM cards.
|
||||||
|
|
||||||
Such SIM/USIM cards are special cards, which - unlike those issued by
|
Such SIM/USIM cards are special cards, which - unlike those issued by
|
||||||
|
@ -13,50 +13,73 @@ This is useful particularly if you are running your own cellular
|
||||||
network, and want to issue your own SIM/USIM cards for that network.
|
network, and want to issue your own SIM/USIM cards for that network.
|
||||||
|
|
||||||
|
|
||||||
Homepage
|
Homepage and Manual
|
||||||
--------
|
-------------------
|
||||||
|
|
||||||
The official homepage of the project is
|
Please visit the [official homepage](https://osmocom.org/projects/pysim/wiki) for usage instructions, manual and examples.
|
||||||
<http://osmocom.org/projects/pysim/wiki>
|
|
||||||
|
|
||||||
GIT Repository
|
Git Repository
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
You can clone from the official libosmocore.git repository using
|
You can clone from the official Osmocom git repository using
|
||||||
|
```
|
||||||
|
git clone git://git.osmocom.org/pysim.git
|
||||||
|
```
|
||||||
|
|
||||||
git clone git://git.osmocom.org/pysim.git
|
There is a cgit interface at <https://git.osmocom.org/pysim>
|
||||||
|
|
||||||
There is a cgit interface at <http://git.osmocom.org/pysim/>
|
|
||||||
|
|
||||||
|
|
||||||
Dependencies
|
Installation
|
||||||
------------
|
------------
|
||||||
|
|
||||||
pysim requires:
|
Please install the following dependencies:
|
||||||
|
|
||||||
- pyscard
|
- pyscard
|
||||||
- serial
|
- serial
|
||||||
- pytlv
|
- pytlv
|
||||||
- cmd2
|
- cmd2
|
||||||
- jsonpath-ng
|
- jsonpath-ng
|
||||||
- bidict
|
- construct
|
||||||
|
- bidict
|
||||||
|
- gsm0338
|
||||||
|
|
||||||
Example for Debian:
|
Example for Debian:
|
||||||
|
```
|
||||||
apt-get install python3-pyscard python3-serial python3-cmd2 python3-pip python3-yaml
|
apt-get install python3-pyscard python3-serial python3-cmd2 python3-pip python3-yaml
|
||||||
pip3 install pytlv bidict
|
pip3 install pytlv jsonpath-ng construct bidict gsm0338
|
||||||
|
```
|
||||||
|
|
||||||
Alternatively, everything can be installed using pip:
|
Alternatively, everything can be installed using pip:
|
||||||
|
```
|
||||||
|
pip3 install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
pip3 install -r requirements.txt
|
After installing all dependencies, the pySim applications ``pySim-read.py``, ``pySim-prog.py`` and ``pySim-shell.py`` may be started directly from the cloned repository.
|
||||||
|
|
||||||
|
### Archlinux Package
|
||||||
|
|
||||||
|
Archlinux users may install the package ``python-pysim-git``
|
||||||
|
[![](https://img.shields.io/aur/version/python-pysim-git)](https://aur.archlinux.org/packages/python-pysim-git)
|
||||||
|
from the [Arch User Repository (AUR)](https://aur.archlinux.org).
|
||||||
|
The most convenient way is the use of an [AUR Helper](https://wiki.archlinux.org/index.php/AUR_helpers),
|
||||||
|
e.g. [yay](https://aur.archlinux.org/packages/yay) or [pacaur](https://aur.archlinux.org/packages/pacaur).
|
||||||
|
The following example shows the installation with ``yay``.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# Install
|
||||||
|
yay -Sy python-pysim-git
|
||||||
|
|
||||||
|
# Uninstall
|
||||||
|
sudo pacman -Rs python-pysim-git
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
Mailing List
|
Mailing List
|
||||||
------------
|
------------
|
||||||
|
|
||||||
There is no separate mailing list for this project. However,
|
There is no separate mailing list for this project. However,
|
||||||
discussions related to pysim-prog are happening on the
|
discussions related to pysim-prog are happening on the
|
||||||
openbsc@lists.osmocom.org mailing list, please see
|
<openbsc@lists.osmocom.org> mailing list, please see
|
||||||
<https://lists.osmocom.org/mailman/listinfo/openbsc> for subscription
|
<https://lists.osmocom.org/mailman/listinfo/openbsc> for subscription
|
||||||
options and the list archive.
|
options and the list archive.
|
||||||
|
|
||||||
|
@ -64,6 +87,7 @@ Please observe the [Osmocom Mailing List
|
||||||
Rules](https://osmocom.org/projects/cellular-infrastructure/wiki/Mailing_List_Rules)
|
Rules](https://osmocom.org/projects/cellular-infrastructure/wiki/Mailing_List_Rules)
|
||||||
when posting.
|
when posting.
|
||||||
|
|
||||||
|
|
||||||
Contributing
|
Contributing
|
||||||
------------
|
------------
|
||||||
|
|
||||||
|
@ -74,40 +98,35 @@ We are using a gerrit-based patch review process explained at
|
||||||
<https://osmocom.org/projects/cellular-infrastructure/wiki/Gerrit>
|
<https://osmocom.org/projects/cellular-infrastructure/wiki/Gerrit>
|
||||||
|
|
||||||
|
|
||||||
Manual
|
Usage Examples
|
||||||
------
|
--------------
|
||||||
p
|
|
||||||
Please see the sphinx based documentation in the 'docs' sub-directory
|
|
||||||
of the source. A PDF rendering of the user manual is available from
|
|
||||||
<https://ftp.osmocom.org/docs/latest/osmosmlc-usermanual.pdf>
|
|
||||||
|
|
||||||
|
|
||||||
Usage
|
|
||||||
-----
|
|
||||||
|
|
||||||
* Program customizable SIMs. Two modes are possible:
|
* Program customizable SIMs. Two modes are possible:
|
||||||
|
|
||||||
- one where you specify every parameter manually :
|
- one where you specify every parameter manually:
|
||||||
|
```
|
||||||
./pySim-prog.py -n 26C3 -c 49 -x 262 -y 42 -i <IMSI> -s <ICCID>
|
./pySim-prog.py -n 26C3 -c 49 -x 262 -y 42 -i <IMSI> -s <ICCID>
|
||||||
|
```
|
||||||
|
|
||||||
|
- one where they are generated from some minimal set:
|
||||||
- one where they are generated from some minimal set :
|
```
|
||||||
|
|
||||||
./pySim-prog.py -n 26C3 -c 49 -x 262 -y 42 -z <random_string_of_choice> -j <card_num>
|
./pySim-prog.py -n 26C3 -c 49 -x 262 -y 42 -z <random_string_of_choice> -j <card_num>
|
||||||
|
```
|
||||||
|
|
||||||
With <random_string_of_choice> and <card_num>, the soft will generate
|
With ``<random_string_of_choice>`` and ``<card_num>``, the soft will generate
|
||||||
'predictable' IMSI and ICCID, so make sure you choose them so as not to
|
'predictable' IMSI and ICCID, so make sure you choose them so as not to
|
||||||
conflict with anyone. (for eg. your name as <random_string_of_choice> and
|
conflict with anyone. (for e.g. your name as ``<random_string_of_choice>`` and
|
||||||
0 1 2 ... for <card num>).
|
0 1 2 ... for ``<card num>``).
|
||||||
|
|
||||||
You also need to enter some parameters to select the device :
|
You also need to enter some parameters to select the device:
|
||||||
-t TYPE : type of card (supersim, magicsim, fakemagicsim or try 'auto')
|
|
||||||
-d DEV : Serial port device (default /dev/ttyUSB0)
|
|
||||||
-b BAUD : Baudrate (default 9600)
|
|
||||||
|
|
||||||
* Interact with SIMs from a python interactive shell (ipython for eg :)
|
-t TYPE : type of card (``supersim``, ``magicsim``, ``fakemagicsim`` or try ``auto``)
|
||||||
|
-d DEV : Serial port device (default ``/dev/ttyUSB0``)
|
||||||
|
-b BAUD : Baudrate (default 9600)
|
||||||
|
|
||||||
|
* Interact with SIMs from a python interactive shell (e.g. ipython):
|
||||||
|
|
||||||
|
```
|
||||||
from pySim.transport.serial import SerialSimLink
|
from pySim.transport.serial import SerialSimLink
|
||||||
from pySim.commands import SimCardCommands
|
from pySim.commands import SimCardCommands
|
||||||
|
|
||||||
|
@ -121,3 +140,4 @@ print(sc.read_binary(['3f00', '7f20', '6f07']))
|
||||||
|
|
||||||
# Run A3/A8
|
# Run A3/A8
|
||||||
print(sc.run_gsm('00112233445566778899aabbccddeeff'))
|
print(sc.run_gsm('00112233445566778899aabbccddeeff'))
|
||||||
|
```
|
||||||
|
|
Loading…
Reference in New Issue