Raritan PX2/PX3 JSON-RPC API
GsmModem.idl
1 /* SPDX-License-Identifier: BSD-3-Clause */
2 /*
3  * Copyright 2011 Raritan Inc. All rights reserved.
4  */
5 
6 #ifndef __GSMMODEM_IDL__
7 #define __GSMMODEM_IDL__
8 
9 #include <Event.idl>
10 
11 /** Serial Ports */
12 module serial {
13 
14  /**
15  * Interface for communication with a GSM modem attached
16  * to a serial port
17  */
18  interface GsmModem_1_0_2 {
19  /**
20  * Error codes
21  */
22  constant int SUCCESS = 0; ///< No error
23  constant int ERR_INVALID_VALUE = 1; ///< Invalid argument
24  constant int ERR_WRONG_PIN = 2; ///< The PIN is incorrect or missing
25  constant int ERR_SMS_SEND_FAILED = 3; ///< SMS delivery failed
26  constant int ERR_COMMUNICATION_FAILURE = 4; ///< Communication with the modem failed
27  constant int ERR_SIM_LOCKED = 5; ///< The SIM card is locked and waits for the PUK
28  constant int ERR_WRONG_SIM_STATUS = 6; ///< The SIM card doesn't wait for the PUK
29  constant int ERR_WRONG_PUK = 7; ///< The PUK is incorrect or missing
30  constant int ERR_SIM_PROBLEM = 8; ///< There is a problem with the SIM or service subscription
31 
32  /**
33  * Possible security states the sim card can be in at a given time
34  */
35  enumeration SimSecurityStatus {
36  UNLOCKED, ///< SIM card is unlocked
37  WAITFORPIN, ///< PIN must be entered to unlock the SIM card
38  WAITFORPUK, ///< PUK and new PIN must be entered to unlock the SIM card
39  UNKNOWN ///< Unkown security status
40  };
41 
42  /**
43  * Structure for holding settings of the GSM modem
44  * and its SIM card
45  */
46  structure Settings {
47  string pin; ///< PIN of the SIM card
48  string smsc; ///< Custom SMS center number (in ITU-T E.164 format),
49  ///< leave empty to use number stored on SIM card
50  };
51 
52  /**
53  * Structure holding information about the modem and the SIM card.
54  * Any of the fields may be empty if the information can not be retrieved.
55  */
56  structure Information {
57  string imei; ///< IMEI of the modem
58  string imsi; ///< IMSI of the SIM card
59 
60  string manufacturer; ///< modem manufacturer string
61  string model; ///< modem model string
62  string revision; ///< modem revision string
63 
64  string ownNumber; ///< own phone number in ITU-T E.164 format
65  string simSmsc; ///< SMS center number stored on SIM card
66  string networkName; ///< Name of the currently used network (PLMN)
67  string serviceProviderName; ///< Name of the service provider (SPN)
68  int receptionLevel; ///< reception level in dBm
69  ///< 0 means unknown, -1 means no reception
70  };
71 
72  /**
73  * Sim card security status changed event
74  */
75  valueobject SimSecurityStatusChangedEvent extends idl.Event {
76  SimSecurityStatus newSimStatus; ///< new SIM card security status
77  };
78 
79  /**
80  * Sim pin updated event
81  */
82  valueobject SimPinUpdatedEvent extends idl.Event {
83  string newPin; ///< new PIN for SIM card after Unlock
84  };
85 
86  /**
87  * @brief Get modem settings
88  *
89  * @return -- Current modem settings
90  */
91  Settings getSettings();
92 
93  /**
94  * @brief Set modem settings
95  *
96  * @param settings -- New settings
97  *
98  * @return SUCCESS -- on success
99  * @return ERR_INVALID_VALUE -- if any passed value was invalid
100  */
101  int setSettings(in Settings settings);
102 
103  /**
104  * @brief Send out a SMS message
105  *
106  * @param recipient -- Phone number of the message recipient in ITU-T E.164 format
107  * @param text -- Message text (will be sent in multiple messages if longer than 160 characters)
108  *
109  * @return SUCCESS -- on success
110  * @return ERR_WRONG_PIN -- if the PIN currently stored in the settings is incorrect or missing
111  * @return ERR_SMS_SEND_FAILED -- if the delivery of the SMS to the network failed
112  * @return ERR_SIM_LOCKED -- if the SIM card is locked and waits for the PUK
113  * @return ERR_COMMUNICATION_FAILURE -- if communication with the modem failed
114  */
115  int sendSms(in string recipient, in string text);
116 
117  /**
118  * @brief Send out a test SMS message
119  *
120  * The message will be sent to the selected recipient with the text 'SMS Test'.
121  *
122  * @param recipient -- Phone number of the message recipient in ITU-T E.164 format
123  * @param testSettings -- Modem settings to be used temporarily during testing
124  *
125  * @return SUCCESS -- on success
126  * @return ERR_WRONG_PIN -- if the PIN currently stored in the settings is incorrect or missing
127  * @return ERR_SMS_SEND_FAILED -- if the delivery of the SMS to the network failed
128  * @return ERR_SIM_LOCKED -- if the SIM card is locked and waits for the PUK
129  * @return ERR_COMMUNICATION_FAILURE -- if communication with the modem failed
130  */
131  int sendTestSms(in string recipient, in Settings testSettings);
132 
133  /**
134  * @brief Retrieve low-level information about the modem and the SIM card.
135  *
136  * @param info -- structure holding the returned information
137  *
138  * @return SUCCESS -- on success
139  * @return ERR_WRONG_PIN -- if the used PIN is incorrect or missing
140  * @return ERR_SIM_LOCKED -- if the SIM card is locked and waits for the PUK
141  * @return ERR_COMMUNICATION_FAILURE -- if communication with the modem failed
142  */
143  int getInformation(out Information info);
144 
145  /**
146  * @brief Retrieve low-level information about the modem and the SIM card.
147  * Like #getInformation, but allows providing a PIN not stored in the settings
148  *
149  * @param pin -- PIN to use for authentication
150  * @param info -- structure holding the returned information
151  *
152  * @return SUCCESS -- on success
153  * @return ERR_WRONG_PIN -- if the used PIN is incorrect or missing
154  * @return ERR_SIM_LOCKED -- if the SIM card is locked and waits for the PUK
155  * @return ERR_COMMUNICATION_FAILURE -- if communication with the modem failed
156  */
157  int getInformationWithPin(in string pin, out Information info);
158 
159  /**
160  * @brief Retrieve security status of the SIM card.
161  *
162  * @param simStatus -- SIM card security status
163  *
164  * @return SUCCESS -- on success
165  * @return ERR_COMMUNICATION_FAILURE -- if communication with the modem failed
166  */
167  int getSimSecurityStatus(out SimSecurityStatus simStatus);
168 
169  /**
170  * @brief Unlock SIM card with PUK and set new PIN if the SIM card is in security status WAITFORPUK.
171  * The new PIN is automatically saved in the settings.
172  *
173  * @param puk -- PUK to use for authentication
174  * @param newPin -- new PIN to use for future authentication
175  *
176  * @return SUCCESS -- on success
177  * @return ERR_WRONG_SIM_STATUS -- if the SIM card doesn't wait for the PUK
178  * @return ERR_WRONG_PUK -- if the used PUK is incorrect or missing
179  * @return ERR_COMMUNICATION_FAILURE -- if communication with the modem failed
180  */
181  int unlockSimCard(in string puk, in string newPin);
182  };
183 
184 }
185 
186 #endif /* __GSMMODEM_IDL__ */
PUK and new PIN must be entered to unlock the SIM card.
Definition: GsmModem.idl:38
string pin
PIN of the SIM card.
Definition: GsmModem.idl:47
string serviceProviderName
Name of the service provider (SPN)
Definition: GsmModem.idl:67
string networkName
Name of the currently used network (PLMN)
Definition: GsmModem.idl:66
Interface for communication with a GSM modem attached to a serial port.
Definition: GsmModem.idl:18
string revision
modem revision string
Definition: GsmModem.idl:62
SIM card is unlocked.
Definition: GsmModem.idl:36
string imei
IMEI of the modem.
Definition: GsmModem.idl:57
Serial Ports.
Definition: AnalogModem.idl:12
PIN must be entered to unlock the SIM card.
Definition: GsmModem.idl:37
Basic IDL definitions.
Definition: Event.idl:10
Structure holding information about the modem and the SIM card.
Definition: GsmModem.idl:56
string model
modem model string
Definition: GsmModem.idl:61
int receptionLevel
reception level in dBm 0 means unknown, -1 means no reception
Definition: GsmModem.idl:68
string manufacturer
modem manufacturer string
Definition: GsmModem.idl:60
string simSmsc
SMS center number stored on SIM card.
Definition: GsmModem.idl:65
string imsi
IMSI of the SIM card.
Definition: GsmModem.idl:58
Structure for holding settings of the GSM modem and its SIM card.
Definition: GsmModem.idl:46
SimSecurityStatus
Possible security states the sim card can be in at a given time.
Definition: GsmModem.idl:35
string smsc
Custom SMS center number (in ITU-T E.164 format), leave empty to use number stored on SIM card...
Definition: GsmModem.idl:48
string ownNumber
own phone number in ITU-T E.164 format
Definition: GsmModem.idl:64