Repository files navigation

This repository contains a number of Python programs that can be usedto read, program (write) and browse all fields/parameters/files onSIM/USIM/ISIM/HPSIM cards used in 3GPP cellular networks from 2G to 5G.

Note that the access control configuration of normal production cardsissue by operators will restrict significantly which files a normaluser can read, and particularly write to.

The full functionality of pySim hence can only be used with on so-calledprogrammable SIM/USIM/ISIM/HPSIM cards.

Such SIM/USIM/ISIM/HPSIM cards are special cards, which - unlike thoseissued by regular commercial operators - come with the kind of keys thatallow you to write the files/fields that normally only an operator canprogram.

This is useful particularly if you are running your own cellularnetwork, and want to configure your own SIM/USIM/ISIM/HPSIM cards forthat network.

Please visit theofficial homepagefor usage instructions, manual and examples.

The pySim user manual can be built from this very source code by meansof sphinx (with sphinxcontrib-napoleon and sphinx-argparse). See theMakefile in the 'docs' directory.

A pre-rendered HTML user manual of the current pySim 'git master' isavailable fromhttps://downloads.osmocom.org/docs/latest/pysim/ anda downloadable PDF version is published athttps://downloads.osmocom.org/docs/latest/osmopysim-usermanual.pdf.

A slightly dated video presentation about pySim-shell can be found athttps://media.ccc.de/v/osmodevcall-20210409-laforge-pysim-shell.

While you will find a lot of online resources still describing the use ofpySim-prog.py and pySim-read.py, those tools are considered legacy bynow and have by far been superseded by the much more capablepySim-shell. We strongly encourage users to adopt pySim-shell, unlessthey have very specific requirements like batch programming of largequantities of cards, which is about the only remaining use case for thelegacy tools.

You can clone from the official Osmocom git repository using

git clone https://gitea.osmocom.org/sim-card/pysim.git

There is a web interface athttps://gitea.osmocom.org/sim-card/pysim.

Please install the following dependencies:

• bidict
• cmd2 >= 1.5.0
• colorlog
• construct >= 2.9.51
• gsm0338
• jsonpath-ng
• packaging
• pycryptodomex
• pyscard
• pyserial
• pytlv
• pyyaml >= 5.1
• smpp.pdu (fromgithub.com/hologram-io/smpp.pdu)
• termcolor

Example for Debian:

sudo apt-get install --no-install-recommends \pcscd libpcsclite-dev \python3 \python3-setuptools \python3-pycryptodome \python3-pyscard \python3-pippip3 install --user -r requirements.txt

After installing all dependencies, the pySim applicationspySim-read.py,pySim-prog.py andpySim-shell.py may be started directly from the cloned repository.

In addition to the dependencies abovepySim-trace.py requirestshark and the python packagepyshark to be installed. It is known that thetshark packagein Debian versions before 11 may not work with pyshark.

Archlinux users may install the packagepython-pysim-gitfrom theArch User Repository (AUR).The most convenient way is the use of anAUR Helper,e.g.yay orpacaur.The following example shows the installation withyay.

# Installyay -Sy python-pysim-git# Uninstallsudo pacman -Rs python-pysim-git

There is no separate mailing list for this project. However,discussions related to pysim-prog are happening on theopenbsc@lists.osmocom.org mailing list, please seehttps://lists.osmocom.org/mailman/listinfo/openbsc for subscriptionoptions and the list archive.

Please observe theOsmocom Mailing ListRuleswhen posting.

Our coding standards are described athttps://osmocom.org/projects/cellular-infrastructure/wiki/Coding_standards

We are using a gerrit-based patch review process explained athttps://osmocom.org/projects/cellular-infrastructure/wiki/Gerrit