2023-06-08 19:43:09 +00:00
pySim - Read, Write and Browse Programmable SIM/USIM/ISIM/HPSIM Cards
=====================================================================
2017-03-17 17:08:09 +00:00
2023-06-08 19:43:09 +00:00
This repository contains a number of Python programs that can be used
to read, program (write) and browse all fields/parameters/files on
SIM/USIM/ISIM/HPSIM cards used in 3GPP cellular networks from 2G to 5G.
2017-03-17 17:08:09 +00:00
2023-06-08 19:43:09 +00:00
Note that the access control configuration of normal production cards
issue by operators will restrict significantly which files a normal
user can read, and particularly write to.
The full functionality of pySim hence can only be used with on so-called
programmable SIM/USIM/ISIM/HPSIM cards.
Such SIM/USIM/ISIM/HPSIM cards are special cards, which - unlike those
issued by regular commercial operators - come with the kind of keys that
allow you to write the files/fields that normally only an operator can
program.
2017-03-17 17:08:09 +00:00
This is useful particularly if you are running your own cellular
2023-06-08 19:43:09 +00:00
network, and want to configure your own SIM/USIM/ISIM/HPSIM cards for
that network.
2017-03-17 17:08:09 +00:00
2023-06-08 19:45:37 +00:00
Homepage
--------
Please visit the [official homepage ](https://osmocom.org/projects/pysim/wiki )
for usage instructions, manual and examples.
Documentation
-------------
The pySim user manual can be built from this very source code by means
of sphinx (with sphinxcontrib-napoleon and sphinx-argparse). See the
Makefile in the 'docs' directory.
A pre-rendered HTML user manual of the current pySim 'git master' is
available from < https: / / downloads . osmocom . org / docs / latest / pysim / > and
a downloadable PDF version is published at
< https: / / downloads . osmocom . org / docs / latest / osmopysim-usermanual . pdf > .
A slightly dated video presentation about pySim-shell can be found at
< https: / / media . ccc . de / v / osmodevcall-20210409-laforge-pysim-shell > .
pySim-shell vs. legacy tools
----------------------------
While you will find a lot of online resources still describing the use of
pySim-prog.py and pySim-read.py, those tools are considered legacy by
now and have by far been superseded by the much more capable
pySim-shell. We strongly encourage users to adopt pySim-shell, unless
they have very specific requirements like batch programming of large
quantities of cards, which is about the only remaining use case for the
legacy tools.
2017-03-17 17:08:09 +00:00
2021-05-17 16:08:45 +00:00
Git Repository
2017-03-17 17:08:09 +00:00
--------------
2021-05-17 16:08:45 +00:00
You can clone from the official Osmocom git repository using
```
2022-08-29 18:03:39 +00:00
git clone https://gitea.osmocom.org/sim-card/pysim.git
2021-05-17 16:08:45 +00:00
```
2017-03-17 17:08:09 +00:00
2022-08-29 18:03:39 +00:00
There is a web interface at < https: / / gitea . osmocom . org / sim-card / pysim > .
2017-03-17 17:08:09 +00:00
2021-05-17 16:08:45 +00:00
Installation
2018-07-19 09:37:39 +00:00
------------
2021-05-17 16:08:45 +00:00
Please install the following dependencies:
2018-07-19 12:48:55 +00:00
2023-08-13 10:16:16 +00:00
- bidict
2023-05-05 12:01:28 +00:00
- cmd2 >= 1.5.0
2023-08-13 10:16:16 +00:00
- colorlog
2022-08-29 14:01:41 +00:00
- construct >= 2.9.51
2021-05-17 16:08:45 +00:00
- gsm0338
2023-08-13 10:16:16 +00:00
- jsonpath-ng
2023-04-27 13:18:13 +00:00
- packaging
2023-05-31 18:47:55 +00:00
- pycryptodomex
2023-08-13 10:16:16 +00:00
- pyscard
- pyserial
- pytlv
- pyyaml >= 5.1
- smpp.pdu (from `github.com/hologram-io/smpp.pdu` )
- termcolor
2018-07-19 12:48:55 +00:00
Example for Debian:
2022-08-29 18:20:18 +00:00
```sh
sudo apt-get install --no-install-recommends \
pcscd libpcsclite-dev \
python3 \
python3-setuptools \
2023-05-31 18:47:55 +00:00
python3-pycryptodome \
2022-08-29 18:20:18 +00:00
python3-pyscard \
python3-pip
pip3 install --user -r requirements.txt
2021-05-17 16:08:45 +00:00
```
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.
2023-07-28 09:19:40 +00:00
In addition to the dependencies above ``pySim-trace.py`` requires ``tshark`` and the python package ``pyshark`` to be installed. It is known that the ``tshark`` package
in Debian versions before 11 may not work with pyshark.
2021-05-17 16:08:45 +00:00
### Archlinux Package
2021-03-12 14:45:17 +00:00
2021-05-17 16:08:45 +00:00
Archlinux users may install the package ``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
```
2021-03-12 14:45:17 +00:00
2018-07-19 09:37:39 +00:00
2017-03-17 17:08:09 +00:00
Mailing List
------------
2021-05-17 16:08:45 +00:00
There is no separate mailing list for this project. However,
2017-03-17 17:08:09 +00:00
discussions related to pysim-prog are happening on the
2021-05-17 16:08:45 +00:00
< openbsc @ lists . osmocom . org > mailing list, please see
2017-03-17 21:34:08 +00:00
< https: / / lists . osmocom . org / mailman / listinfo / openbsc > for subscription
2017-03-17 17:08:09 +00:00
options and the list archive.
Please observe the [Osmocom Mailing List
Rules](https://osmocom.org/projects/cellular-infrastructure/wiki/Mailing_List_Rules)
when posting.
2021-05-17 16:08:45 +00:00
2017-03-17 17:08:09 +00:00
Contributing
------------
Our coding standards are described at
2017-03-17 21:34:08 +00:00
< https: / / osmocom . org / projects / cellular-infrastructure / wiki / Coding_standards >
2017-03-17 17:08:09 +00:00
2021-04-11 09:19:44 +00:00
We are using a gerrit-based patch review process explained at
< https: / / osmocom . org / projects / cellular-infrastructure / wiki / Gerrit >
