laforge has submitted this change. ( https://gerrit.osmocom.org/c/osmo-remsim/+/36417?usp=email )
Change subject: README.md: Major update / meaningful content ......................................................................
README.md: Major update / meaningful content
Change-Id: Iec6a38bc34fdb0f9f0427df1c0fa53d513655a2a --- M README.md 1 file changed, 65 insertions(+), 67 deletions(-)
Approvals: laforge: Looks good to me, approved Jenkins Builder: Verified
diff --git a/README.md b/README.md index 8f2657f..2aa3af5 100644 --- a/README.md +++ b/README.md @@ -1,89 +1,78 @@ osmo-remsim - Osmocom remote SIM software suite ===============================================
-This software suite is a work in progress. +osmo-remsim is a suite of software programs enabling physical/geographic separation of a cellular phone (or +modem) on the one hand side and the SIM/USIM/ISIM card on the other side. + +Using osmo-remsim, you can operate an entire fleet of modems/phones, as well as banks of SIM cards and +dynamically establish or remove the connections between modems/phones and cards. + +So in technical terms, it behaves like a proxy for the ISO 7816 smart card interface between the MS/UE and the +UICC/SIM/USIM/ISIM. + +While originally designed to be used in context of cellular networks, there is nothing cellular specific in +the system. It can therefore also be used with other systems that use contact based smart cards according to +ISO 7816. Currently only the T=0 protocol with standard (non-extended) APDUs is supported. + +Homepage +-------- +Please visit the [official homepage](https://osmocom.org/projects/osmo-remsim/wiki) +for usage instructions, manual and examples.
-osmo-remsim-client ------------------- +GIT Repository +--------------
-The client interfaces with GSM phones / modems via dedicated "Card -Emulation" devices such as the Osmocom SIMtrace2 or sysmocom sysmoQMOD -board + firmware. This hardware implements the ISO7816-3 electrical -interface and protocol handling and passes any TPDU headers received -from the phone/modem to osmo-remsim-client for further processing of the -TPDUs associated to the given APDU transfer. +You can clone from the official osmo-remsim.git repository using
-osmo-remsim-client connects via a RSPRO control connection to -osmo-remsim-server at startup and registers itself. It will receive -configuration data such as the osmo-remsim-bankd IP+Port and the -ClientId from osmo-remsim-server. + git clone https://gitea.osmocom.org/sim-card/osmo-remsim
-After receiving the configuration, osmo-remsim-client will establish a -RSPRO data connection to the osmo-remsim-bankd IP:Port. +There is a web interface at https://gitea.osmocom.org/sim-card/osmo-remsim.
-As the USB interface for remote SIM in simtrace2.git uses one interface -per slot, we can implement the client in blocking mode, i.e. use -blocking I/O on the TCP/RSPRO side. This simplifies the code compared -to a more complex async implementation. +Documentation +------------- + +The User Manual is [optionally] built in PDF form as part of the build process. + +A pre-rendered PDF version of the current `master` can be found at +[User Manual](https://downloads.osmocom.org/docs/latest/osmo-remsim-usermanual.pdf).
-osmo-remsim-bankd ------------------ +Forum +-----
-The osmo-remsim-bankd (SIM Bank Daemon) manages one given SIM bank. The -initial implementation supports a PC/SC driver to expose any PC/SC -compatible card readers as SIM bank. +We welcome any osmo-remsim related discussions in the +[SIM Card Technology](https://discourse.osmocom.org/c/sim-card-technology/) +section of the osmocom discourse (web based Forum).
-osmo-remsim-bankd initially connects via a RSPRO control connection to -osmo-remsim-server at startup, and will in turn receive a set of initial -[client,slot]:[bankd,slot] mappings. These mappings determine which -slot on the client (corresponding to a modem) is mapped to which slot on -the SIM bank. Mappings can be updated by osmo-remsim-server at any given -point in time.
-osmo-remsim-bankd implements a RSPRO server, where it listens to -connections from osmo-remsim-clients. +Mailing List +------------
-As PC/SC only offers a blocking API, there is one thread per PC/SC slot. -This thread will perform blocking I/O on the socket towards the client, -and blocking API calls on PC/SC. +There is no separate mailing list for this project. However, +discussions related to pySim are happening on the simtrace +simtrace@lists.osmocom.org mailing list, please see +https://lists.osmocom.org/mailman/listinfo/simtrace for subscription +options and the list archive.
-In terms of thread handling, we do: +Please observe the [Osmocom Mailing List +Rules](https://osmocom.org/projects/cellular-infrastructure/wiki/Mailing_List_Rules) +when posting.
-* accept() handling in [spare] worker threads -** this means blocking I/O can be used, as each worker thread only has - one TCP connection -** client identifies itself with client:slot -** lookup mapping based on client:slot (using mutex for protection) -** open the reader based on the lookup result
-The worker threads initially don't have any mapping to a specific -reader, and that mapping is only established at a later point after the -client has identified itself. The advantage is that the entire bankd -can live without any non-blocking I/O. +Issue Tracker +-------------
-The main thread handles the connection to osmo-remsim-server, where it -can also use non-blocking I/O. However, re-connection would be -required, to avoid stalling all banks/cards in the event of a connection -loss to the server. +We use the [issue tracker of the osmo-remsim project on osmocom.org](https://osmocom.org/projects/osmo-remsim/issues) for +tracking the state of bug reports and feature requests. Feel free to submit any issues you may find, or help +us out by resolving existing issues.
-worker threads have the following states: -* INIT (just started) -* ACCEPTING (they're blocking in the accept() call on the server socket fd) -* CONNECTED_WAIT_ID (TCP established, but peer not yet identified itself) -* CONNECTED_CLIENT (TCP established, client has identified itself, no mapping) -* CONNECTED_CLIENT_MAPPED (TCP established, client has identified itself, mapping exists) -* CONNECTED_CLIENT_MAPPED_CARD (TCP established, client identified, mapping exists, card opened) -* CONNECTED_SERVER (TCP established, server has identified itself)
-Once the client disconnects, or any other error occurs (such as card I/O -errors), the worker thread either returns to INIT state (closing client -socket and reader), or it terminates. Termination would mean that the -main thread would have to do non-blocking join to detect client -termination and then re-spawn clients, so the "return to INIT state" -approach seems to make more sense. +Contributing +------------
-Open topics: -* detecting multiple connections from a server, logging this or even - avoiding that situation +Our coding standards are described at +https://osmocom.org/projects/cellular-infrastructure/wiki/Coding_standards + +We are using a gerrit-based patch review process explained at +https://osmocom.org/projects/cellular-infrastructure/wiki/Gerrit