Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 1 | == osmo-remsim-client-st2 |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 2 | |
Harald Welte | 35f2b20 | 2019-04-01 11:01:51 +0200 | [diff] [blame] | 3 | The client interfaces with GSM phones / modems via dedicated "Card |
| 4 | Emulation" devices such as the Osmocom SIMtrace2 or sysmocom sysmoQMOD |
| 5 | board + firmware. This hardware implements the ISO7816-3 electrical |
| 6 | interface and protocol handling and passes any TPDU headers received |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 7 | from the phone/modem to `osmo-remsim-client` for further processing of |
| 8 | the TPDUs associated to the given APDU transfer. |
Harald Welte | 35f2b20 | 2019-04-01 11:01:51 +0200 | [diff] [blame] | 9 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 10 | `osmo-remsim-client` connects via a RSPRO control connection to |
| 11 | `osmo-remsim-server` at startup and registers itself. It will receive |
| 12 | configuration data such as the `osmo-remsim-bankd` IP+Port and the |
| 13 | ClientId from `osmo-remsim-server`. |
Harald Welte | 35f2b20 | 2019-04-01 11:01:51 +0200 | [diff] [blame] | 14 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 15 | After receiving the configuration, `osmo-remsim-client` will establish a |
| 16 | RSPRO data connection to the `osmo-remsim-bankd` IP:Port. |
Harald Welte | 35f2b20 | 2019-04-01 11:01:51 +0200 | [diff] [blame] | 17 | |
| 18 | As the USB interface for remote SIM in simtrace2.git uses one interface |
| 19 | per slot, we can implement the client in blocking mode, i.e. use |
| 20 | blocking I/O on the TCP/RSPRO side. This simplifies the code compared |
| 21 | to a more complex async implementation. |
| 22 | |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 23 | === Running |
| 24 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 25 | osmo-remsim-client-st2 currently has the following command-line options: |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 26 | |
| 27 | ==== SYNOPSIS |
| 28 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 29 | *osmo-remsim-client-st2* [...] |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 30 | |
| 31 | ==== OPTIONS |
| 32 | |
| 33 | *-h, --help*:: |
| 34 | Print a short help message about the supported options |
| 35 | *-s, --server-host A.B.C.D*:: |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 36 | Specify the remote IP address / hostname of the `osmo-remsim-server` to |
| 37 | which this client shall establish its RSPRO control connection |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 38 | *-p, --server-port <1-65535>*:: |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 39 | Specify the remote TCP port number of the `osmo-remsim-server` to which |
| 40 | this client shall establish its RSPRO control connection |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 41 | *-c, --client-id <1-65535>*:: |
| 42 | Specify the numeric client identifier of the SIM bank this bankd |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 43 | instance operates. The tuple of client-id and client-slot must be |
| 44 | unique among all clients connecting to the same `osmo-remsim-server`. |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 45 | *-n, --client-slot <0-65535>*:: |
| 46 | Specify the slot number served within this client. The tuple of |
| 47 | client-id and client-slot must be unique among all clients connecting |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 48 | to the same `osmo-remsim-server`. |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 49 | *-i, --gsmtap-ip A.B.C.D*:: |
| 50 | Specify the IP address (if any) to which APDU traces are sent in |
| 51 | GSMTAP format (useful for debugging; supported by wireshark). |
| 52 | *-k, --keep-running*:: |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 53 | Specify if the `osmo-remsim-client` should terminate after handling one |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 54 | session, or whether it should keep running. Fast respawn (i.e. no |
| 55 | --keep-running) is probably the more robust option at this point. |
| 56 | *-V, --usb-vendor*:: |
| 57 | Specify the USB Vendor ID of the USB device served by this client, |
| 58 | use e.g. 0x1d50 for SIMtrace2, sysmoQMOD and OWHW. |
| 59 | *-P, --usb-product*:: |
| 60 | Specify the USB Product ID of the USB device served by this client, |
| 61 | use e.g. 0x4004 for sysmoQMOD. |
| 62 | *-C, --usb-config*:: |
| 63 | Specify the USB Cofiguration number of the USB device served by this |
| 64 | client. Default will use current configuration of the device. |
| 65 | *-I, --usb-interface*:: |
| 66 | Specify the USB Interface number (within active configuration) of the |
| 67 | USB device served by this client. Default will use FIXME. |
| 68 | *-S, --usb-altsetting*:: |
| 69 | Specify the USB Alternate Setting to be used within the USB Interface |
| 70 | of the USB device served by this client. Default will use FIXME. |
| 71 | *-A, --usb-address <0-255>*:: |
| 72 | Specify the USB Address of the USB device served by this client. This |
| 73 | is useful in case multiple identical USB devices are attached to the |
| 74 | same host. However, the address changed at every re-enumeration and |
| 75 | it's therefor recommended to use the USB path (see below). |
| 76 | *-H, --usb-path*:: |
| 77 | Specify the USB path of the USB device served by this client. This is |
| 78 | usefule to disambiguate between multiple identical USB devices |
| 79 | attached to the same host. You don't need this if you have only one |
| 80 | SIM emulation device attached to your system. |
| 81 | *-a, --atr HEXSTRING*:: |
| 82 | Specify the initial ATR to be communicated to the modem/phone. Can |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 83 | and will later be overridden by the ATR as specified by |
| 84 | `osmo-remsim-bankd` once a card has been mapped to this client. |
Harald Welte | 55c7f44 | 2019-12-17 01:14:43 +0100 | [diff] [blame^] | 85 | *-e, --event-script COMMAND*:: |
| 86 | Specify the shell command to be execute when the client wants to call its |
| 87 | helper script |
| 88 | |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 89 | |
Joachim Steiger | 68f9510 | 2019-07-03 19:03:24 +0200 | [diff] [blame] | 90 | ==== Examples |
| 91 | .remsim-server is on 10.2.3.4, sysmoQMOD on usb bus, all 4 modems: |
| 92 | ---- |
| 93 | osmo-remsim-client-st2 -s 10.2.3.4 -V 1d50 -P 4004 -C 1 -I 0 -H 2-1.1 -c 0 -n 0 |
| 94 | osmo-remsim-client-st2 -s 10.2.3.4 -V 1d50 -P 4004 -C 1 -I 1 -H 2-1.1 -c 0 -n 1 |
| 95 | osmo-remsim-client-st2 -s 10.2.3.4 -V 1d50 -P 4004 -C 1 -I 0 -H 2-1.4 -c 0 -n 2 |
| 96 | osmo-remsim-client-st2 -s 10.2.3.4 -V 1d50 -P 4004 -C 1 -I 1 -H 2-1.4 -c 0 -n 3 |
| 97 | ---- |
| 98 | |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 99 | === Logging |
| 100 | |
Harald Welte | 51cfec0 | 2019-04-03 09:18:44 +0200 | [diff] [blame] | 101 | `osmo-remsim-client` currently logs to stdout only, and the logging |
| 102 | verbosity is not yet configurable. However, as the libosmocore logging |
| 103 | framework is used, extending this is an easy modification. |
Harald Welte | 55c7f44 | 2019-12-17 01:14:43 +0100 | [diff] [blame^] | 104 | |
| 105 | === Helper Script |
| 106 | |
| 107 | `osmo-remsim-client` can call an external shell command / script / program at specific |
| 108 | instances of time. This serves two purposes: |
| 109 | |
| 110 | * To keep external system integration posted about the overall status of remsim-client, |
| 111 | such as whether or not it is connected to a server and/or bankd. |
| 112 | * To request the external system to perform specific actions, such as triggering the reset |
| 113 | of the modem - in case the hardware doesn't allow the simtrace2 firmware to do that itself. |
| 114 | |
| 115 | ==== Script Environment Variables |
| 116 | |
| 117 | The environment passed to the helper script contains a number of variables to provide inormation |
| 118 | to the external script: |
| 119 | |
| 120 | .Environment Variables |
| 121 | [options="header",cols="27%,18%,55%"] |
| 122 | |=== |
| 123 | | Name | Example Value | Description |
| 124 | | REMSIM_CLIENT_VERSION | 0.2.2.37-5406a | Compile version of the software |
| 125 | | REMSIM_SERVER_ADDR | 1.2.3.4:1234 | Address and port of the remsim-server |
| 126 | | REMSIM_SERVER_STATE | CONNECTED | FSM state of the connection to remsim-server |
| 127 | | REMSIM_BANKD_ADDR | 1.2.3.4:1234 | Address and port of the remsim-bankd |
| 128 | | REMSIM_BANKD_STATE | CONNECTED | FSM state of the connection to remsim-bankd |
| 129 | | REMSIM_CLIENT_SLOT | 23:42 | Client ID and Client Slot Number |
| 130 | | REMSIM_BANKD_SLOT | 55:33 | Bank ID and Bank Slot Number |
| 131 | | REMSIM_USB_PATH | 2-1.1 | USB path of the USB device with simtrace2 cardem firmware |
| 132 | | REMSIM_USB_INTERFACE | 1 | Interface number of the USB device with simtrace2 cardem firmware |
| 133 | | REMSIM_SIM_VCC | 1 | Whether or not the modem currently applies SIM VCC (0/1) |
| 134 | | REMSIM_SIM_RST | 1 | Whether or not the modem currently asserts SIM RST (0=inactive, 1=active) |
| 135 | | REMSIM_CAUSE | request-card-insert | The cause why this script has been called |
| 136 | |=== |
| 137 | |
| 138 | ==== REMSIM_CAUSE values |
| 139 | |
| 140 | The REMSIM_CAUSE environment variable (as well as the first argument) passed to the helper |
| 141 | script indicated why the script has been called. |
| 142 | |
| 143 | [options="header",cols="25%,75%"] |
| 144 | |=== |
| 145 | | Name | Description |
| 146 | | event-modem-status | The SIM card interface status has changed (e.g. VCC/RST change) |
| 147 | | event-bankd-connect | A logical RSPRO connection to a bankd has been established |
| 148 | | event-server-connect | A logical RSPRO connection to a server has been established |
| 149 | | event-config-bankd | The server has instructed the client of the bankd address |
| 150 | | request-card-insert | The client asks the system to simulate SIM card insertion to the modem |
| 151 | | request-card-remove | The client asks the system to simulate SIM card removal from the modem |
| 152 | | request-sim-remote | The client asks the system to switch to remote SIM |
| 153 | | request-sim-local | The client asks the system to switch to local SIM |
| 154 | | request-modem-reset | The client asks the system to perform a modem reset |
| 155 | |=== |