laforge has uploaded this change for review. ( https://gerrit.osmocom.org/c/pysim/+/27207 ) Change subject: README.md: Remove old usage examples, refer to user manual instead ...................................................................... README.md: Remove old usage examples, refer to user manual instead We want people to use pySim-shell and should not mislead them by having usage examples of old tools in README.md. Also, all documentation should be in the manuals, let's try to have bits and pieces in various places. Change-Id: I8c07a2e0778ab95fb42be6074acb80874e681d20 --- M README.md 1 file changed, 20 insertions(+), 36 deletions(-) git pull ssh://gerrit.osmocom.org:29418/pysim refs/changes/07/27207/1 diff --git a/README.md b/README.md index 7f46085..5e1937e 100644 --- a/README.md +++ b/README.md @@ -93,46 +93,30 @@ <https://osmocom.org/projects/cellular-infrastructure/wiki/Gerrit> -Usage Examples --------------- +Documentation +------------- - * Program customizable SIMs. Two modes are possible: +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. - - one where you specify every parameter manually: -``` -./pySim-prog.py -n 26C3 -c 49 -x 262 -y 42 -i <IMSI> -s <ICCID> -``` +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>. - - 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> -``` +A slightly dated video presentation about pySim-shell can be found at +<https://media.ccc.de/v/osmodevcall-20210409-laforge-pysim-shell>. -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 -conflict with anyone. (for e.g. your name as ``<random_string_of_choice>`` and -0 1 2 ... for ``<card num>``). -You also need to enter some parameters to select the device: +pySim-shell vs. legacy tools +---------------------------- - -t TYPE : type of card (``supersim``, ``magicsim``, ``fakemagicsim`` or try ``auto``) - -d DEV : Serial port device (default ``/dev/ttyUSB0``) - -b BAUD : Baudrate (default 9600) +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. - * Interact with SIMs from a python interactive shell (e.g. ipython): - -``` -from pySim.transport.serial import SerialSimLink -from pySim.commands import SimCardCommands - -sl = SerialSimLink(device='/dev/ttyUSB0', baudrate=9600) -sc = SimCardCommands(sl) - -sl.wait_for_card() - - # Print IMSI -print(sc.read_binary(['3f00', '7f20', '6f07'])) - - # Run A3/A8 -print(sc.run_gsm('00112233445566778899aabbccddeeff')) -``` -- To view, visit https://gerrit.osmocom.org/c/pysim/+/27207 To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: pysim Gerrit-Branch: master Gerrit-Change-Id: I8c07a2e0778ab95fb42be6074acb80874e681d20 Gerrit-Change-Number: 27207 Gerrit-PatchSet: 1 Gerrit-Owner: laforge &lt;laforge(a)osmocom.org&gt; Gerrit-MessageType: newchange