Wiki » History » Revision 60
Revision 59 (laforge, 10/30/2023 04:10 PM) → Revision 60/65 (laforge, 10/30/2023 04:11 PM)
h1. pySim WiKi
{{>toc}}
pySim is a suite of programs (develped in python) for interfacing with SIM/UICC/USIM/ISIM cards.
* @pySim-shell@ is an interactive command line tool for navigating around the card file system, reading/writing data to the files as well as administrative commands. It is the most sophisticated general purpose tool of the pySim suite and has long surpassed the capabilities of its older cousins like @pySim-prog@.
* @pySim-prog@ is a small command line utility for programming a small subset of parameters like IMSI, K, OP[c], SMSP in (batches of) various programmable SIM/USIM cards.
* @pySim-read@ is a small command line utility for reading some commonly used fields of a SIM card
* @piSim-trace@ is a high-level decoder of SIM card protocol traces (for example, traces generated by [[SIMtrace2:]])
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.
h2. Supported Cards
* Generic SIM/UICC/USIM/ISIM card
** only ETSI/3GPP standard files supported on generic cards
** writing of most fields is typically not possible as nobody except the card-issuing operator posesses the keys / ADM1 PIN to write
* Actively supported, fully programmable cards
** [[cellular-infrastructure:sysmoISIM-SJA2]] (3GPP Release 16 SIM + USIM + ISIM)
** [[cellular-infrastructure:sysmoISIM-SJA5]] (3GPP Release 17 SIM + USIM + ISIM + HPSIM)
* Older fully programmable cards
** [[cellular-infrastructure:sysmoUSIM-SJS1]] (SIM + USIM)
* Older much less configurable cards
** [[cellular-infrastructure:GrcardSIM]] (SIM)
** [[cellular-infrastructure:GrcardSIM2]] (SIM)
** [[cellular-infrastructure:MagicSIM]] (SIM)
h2. Supported Card Interfaces ("Readers")
The best-supported/recommended configuration is to use a Smart Card Interface device compliant with the _USB CCID_ specification, using the libccid/pcsc-lite driver stack.
However, pySim supports multiple card interface back-ends:
* @pcsc@: any reader suppored by "pcsc-lite":https://pcsclite.apdu.fr/
** pcsc-lite supports any reader that provides a so-called @ifd_handler@ driver. Those could come e.g. from reader vendors, but
** pcsc-lite is very well integrated with "libccid":https://ccid.apdu.fr/, whose reader support status is indicated at https://ccid.apdu.fr/ccid/section.html
* @serial@: simple serial/UART based readers, as sometimes shipped with GRcard SIMs
* @calypso@: A calypso chipset based mobile phone runnung [[OsmocomBB:]]
* @modem_atcmd@: Any cellular modem offering the @AT+CSIM@ command
The pySim developers as well as the continuous integration / automatic testing are utilizing USB-CCID readers via pcsc-lite. Your milage with other backends (not used much, not automatically tested) may vary!
h2. Documentation
h3. User Manual
The manual / documentation can be built from the source code by @(cd docs && make html latexpdf)@.
Pre-rendered versions of the current @master@ branch are available as "PDF":https://ftp.osmocom.org/docs/latest/osmopysim-usermanual.pdf and "HTML":https://downloads.osmocom.org/docs/latest/pysim/
h3. Video on pySim-shell usage
On April 9. 2021 @laforge gave a presentation on @pySim-shell@, a video recording can be found at
https://people.osmocom.org/tnt/osmodevcall/osmodevcall-20210409-laforge-pysim-shell_h264_420.mp4
h2. Installation Usage instructions
*Installation:* Please follow the instructions provided in [source:README.md]
h2. Usage instructions
* Connect SIM card reader.
* Insert programmable SIM card
h3. Check the status of connection by entering the following command:
<pre>
pcsc_scan
</pre>
* If SIM card reader is recognised then we can expect something similar to the below output:
<pre>
$ pcsc_scan
PC/SC device scanner
V 1.4.25 (c) 2001-2011, Ludovic Rousseau ludovic.rousseau@free.fr
Compiled with PC/SC lite version: 1.8.14
Using reader plug'n play mechanism
Scanning present readers...
0: SCM Microsystems Inc. SCR 3310 [CCID Interface] 00 00
Tue Oct 18 11:48:08 2016
Reader 0: SCM Microsystems Inc. SCR 3310 [CCID Interface] 00 00
Card state: Card inserted,
ATR: 3B 99 18 00 11 88 22 33 44 55 66 77 60
+ TS = 3B --> Direct Convention
+ T0 = 99, Y(1): 1001, K: 9 (historical bytes)
TA(1) = 18 --> Fi=372, Di=12, 31 cycles/ETU
129032 bits/s at 4 MHz, fMax for Fi = 5 MHz => 161290 bits/s
TD(1) = 00 --> Y(i+1) = 0000, Protocol T = 0
-----
+ Historical bytes: 11 88 22 33 44 55 66 77 60
Category indicator byte: 11 (proprietary format)
Possibly identified card (using /usr/share/pcsc/smartcard_list.txt):
3B 99 18 00 11 88 22 33 44 55 66 77 60
sysmocom sysmoSIM-GR1
</pre>
** Exit pcsc_scan : _Ctrl+C_
h3. Read (a few fields of) your SIM card
./pySim-read.py -p0 or ./pySim-read.py -p1
* Using sysmoSIM-GR1 and if everything is done correctly, you will see something similar to:
<pre>
$ ./pySim-read.py -p0
Reading ...
ICCID: 1791198229180000071
IMSI: 001640000000071
SMSP: ffffffffffffffffffffffffe1ffffffffffffffffffffffff0581005155f5ffffffffffff000000
ACC: ffff
MSISDN: Not available
Done !
</pre>
h3. Continuous Integration / Automatic Testing
pySim is continuously and automatically tested by a [[TestRig]] run by sysmocom
{{include(cellular-infrastructure:MacroCommercialSupport)}}
