2021-05-17 16:08:45 +00:00
pySim - Read, Write and Browse Programmable SIM/USIM Cards
2017-03-17 17:08:09 +00:00
====================================================
2021-05-17 16:08:45 +00:00
This repository contains Python programs that can be used
to read, program (write) and browse certain fields/parameters on so-called programmable
2017-03-17 17:08:09 +00:00
SIM/USIM cards.
Such SIM/USIM 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.
This is useful particularly if you are running your own cellular
network, and want to issue your own SIM/USIM cards for that network.
2021-05-17 16:08:45 +00:00
Homepage and Manual
-------------------
2017-03-17 17:08:09 +00:00
2022-07-18 08:13:59 +00:00
Please visit the [official homepage ](https://osmocom.org/projects/pysim/wiki ) for usage instructions, manual and examples. The user manual can also be built locally from this source code by ``cd docs && make html latexpdf`` for HTML and PDF format, respectively.
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
2021-05-17 16:08:45 +00:00
- pyscard
2022-08-29 14:10:12 +00:00
- pyserial
2021-05-17 16:08:45 +00:00
- pytlv
2021-06-11 21:45:26 +00:00
- cmd2 >= 1.3.0 but < 2.0.0
2021-05-17 16:08:45 +00:00
- jsonpath-ng
2022-08-29 14:01:41 +00:00
- construct >= 2.9.51
2021-05-17 16:08:45 +00:00
- bidict
- gsm0338
2022-08-29 14:12:03 +00:00
- pyyaml >= 5.1
- termcolor
- colorlog
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 \
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.
### 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 >
2017-03-17 17:08:09 +00:00
2021-04-11 09:21:00 +00:00
2022-02-15 14:33:52 +00:00
Documentation
-------------
2017-03-17 17:08:09 +00:00
2022-02-15 14:33:52 +00:00
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.
2017-03-17 17:08:09 +00:00
2022-02-15 14:33:52 +00:00
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 > .
2017-03-17 17:08:09 +00:00
2022-02-15 14:33:52 +00:00
A slightly dated video presentation about pySim-shell can be found at
< https: / / media . ccc . de / v / osmodevcall-20210409-laforge-pysim-shell > .
2017-03-17 17:08:09 +00:00
2022-02-15 14:33:52 +00:00
pySim-shell vs. legacy tools
----------------------------
2017-03-17 17:08:09 +00:00
2022-02-15 14:33:52 +00:00
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
