Phoenard
PHNSim.h
Go to the documentation of this file.
1 /*
2 The MIT License (MIT)
3 
4 This file is part of the Phoenard Arduino library
5 Copyright (c) 2014 Phoenard
6 
7 Permission is hereby granted, free of charge, to any person obtaining a copy
8 of this software and associated documentation files (the "Software"), to deal
9 in the Software without restriction, including without limitation the rights
10 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 copies of the Software, and to permit persons to whom the Software is
12 furnished to do so, subject to the following conditions:
13 
14 The above copyright notice and this permission notice shall be included in
15 all copies or substantial portions of the Software.
16 
17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
23 THE SOFTWARE.
24 */
25 
30 #include <Arduino.h>
31 
32 #ifndef _PHNSIM_H_
33 #define _PHNSIM_H_
34 
35 #include <utility/PHNUtils.h>
36 #include "PHNDate.h"
37 #include "PHNCore.h"
38 
39 #define SIM_BAUDRATE 57600
40 #define SIM_PWR_DELAY 1500
41 
42 // AT Command timeout in MS.
43 #define SIM_ATCOMMAND_TIMEOUT 500
44 // AT Send Text message timeout in MS
45 #define SIM_ATCOMMAND_SENDTEXT_TIMEOUT 8000
46 // AT Send DTFM message timeout in MS
47 #define SIM_ATCOMMAND_DTFM_TIMEOUT 1500
48 // Total amount of times an AT Command will be executed
49 // If set to 1, no retries are performed.
50 #define SIM_ATCOMMAND_TRYCNT 3
51 
52 // Pin status constants
53 #define SIM_PIN_STATUS_READY 0
54 #define SIM_PIN_STATUS_NEEDPIN 1
55 #define SIM_PIN_STATUS_NEEDPUK 2
56 #define SIM_PIN_STATUS_ERROR 3
57 
58 // Call status constants
59 #define SIM_CALL_STATUS_NONE 0
60 #define SIM_CALL_STATUS_CALLING 1
61 #define SIM_CALL_STATUS_CALLED 2
62 #define SIM_CALL_STATUS_BUSY 3
63 
65 typedef struct SimContact {
66  SimContact() : valid(false), type(129) {}
67 
68  bool valid;
69  int type;
70  char text[51];
71  char number[21];
72  uint8_t index;
73 
74  operator bool() const {
75  return valid;
76  }
77 } SimContact;
78 
80 typedef struct SimMessage {
81  SimMessage() : valid(false) {}
82 
83  bool valid;
84  SimContact sender;
85  Date date;
86  bool read;
87  char text[140*2+1];
88  uint8_t index;
89 
90  operator bool() const {
91  return valid;
92  }
93 } SimMessage;
94 
104 class PHN_Sim {
105 public:
107  void init();
109  void begin();
111  void end();
113  void reset();
115  void update();
117  bool isOn();
119  void togglePower();
120 
121  // Read SIM general information
123  int getRegStatus();
125  bool isConnected();
127  bool isSimCardInserted();
129  Date getDate();
131  void setDate(Date newDate);
133  bool readProvider(char* buffer, int bufferLength);
135  float readBatteryLevel();
137  int readSignalLevel();
138 
139  // Reading/Entering of access codes
141  bool enterPin(const char* pin);
143  bool enterPuk(const char* puk, const char* newPin);
145  int getPinStatus();
146 
147  // Calling
149  void call(const char* address);
151  void endCall();
153  void rejectCall();
155  void acceptCall();
157  bool isCalled();
159  int getCallStatus();
161  const char* getIncomingNumber();
163  void sendDTMF(char character);
165  bool setVolume(int level);
166 
167  // Text messages
169  int getMessageCount();
171  int getMessageLimit();
173  bool hasNewMessage();
177  SimMessage getMessage(int messageIndex);
179  void deleteMessage(int messageIndex);
181  bool sendMessage(const char* receiverAddress, const char* messageText);
182 
183  // Contacts
185  bool setContactBook(const char* bookName);
187  int getContactCount();
189  int getContactLimit() const { return this->bookSize; }
191  int getContactNumberLimit() const { return this->bookAddressLength; }
193  int getContactTextLimit() const { return this->bookNameLength; }
195  SimContact getContact(int contactIndex);
197  bool addContact(SimContact contact);
199  bool setContact(int contactIndex, SimContact contact);
201  bool deleteContact(int contactIndex);
202 
203  // AT Command handling routines
204  // Return value indicates whether it was successful
206  bool sendATCommand(const char* command);
208  bool sendATCommand(const char* command, char* respBuffer, uint16_t respBufferLength);
210  bool sendATCommand(const char* command, char* respBuffer, uint16_t respBufferLength, long timeout);
212  bool writeATCommand(const char* command);
213 
221  unsigned char getSimTextArgs(char *text, char **args, unsigned char maxArgs);
222 
224  Date readDate(char *text);
226  void writeDate(char* buffer, Date date);
227  private:
228  int latestInbox;
229  int callStatus;
230  int bookOffset, bookSize;
231  int bookNameLength, bookAddressLength;
232  char incomingNumber[20];
233  bool initialized;
234  bool callReady, gpsReady; // Used when switching between call/gps mode
235 
237  bool waitRead();
239  bool readToken(const char *token, unsigned long timeoutMS);
240 };
241 
242 extern PHN_Sim sim;
243 
244 #endif
bool deleteContact(int contactIndex)
Deletes the contact information at the index in the current book.
Definition: PHNSim.cpp:617
bool sendMessage(const char *receiverAddress, const char *messageText)
Sends a text message.
Definition: PHNSim.cpp:473
void endCall()
Ends the current call, or cancels a call silently.
Definition: PHNSim.cpp:312
Date getDate()
Get the current date according to the SIM.
Definition: PHNSim.cpp:223
SimMessage getMessage(int messageIndex)
Reads a message from the message inbox.
Definition: PHNSim.cpp:402
void reset()
Resets all SIM AT parameters to the factory defaults.
Definition: PHNSim.cpp:71
Struct to hold years, months, days, hours, minutes and seconds for a given Date.
Definition: PHNDate.h:37
int getPinStatus()
Gets the pin entering status.
Definition: PHNSim.cpp:193
void update()
Receives SIM status codes, call routinely to keep up to date.
Definition: PHNSim.cpp:93
bool enterPuk(const char *puk, const char *newPin)
Enters SIM PUK and new Pin code.
Definition: PHNSim.cpp:168
A single message contact.
Definition: PHNSim.h:65
unsigned char getSimTextArgs(char *text, char **args, unsigned char maxArgs)
Reads the arguments sent in a sim text response message.
Definition: PHNSim.cpp:746
void setDate(Date newDate)
Sets a new date stored and updated by the SIM.
Definition: PHNSim.cpp:216
int getMessageLimit()
Gets the total limit amount of messages that can be stored in memory.
Definition: PHNSim.cpp:371
A single text message.
Definition: PHNSim.h:80
void begin()
Sets up the SIM for first use.
Definition: PHNSim.cpp:48
bool isCalled()
Checks whether the SIM is being called, used getCallStatus()
Definition: PHNSim.cpp:327
void rejectCall()
Rejects an incoming call by stating you are busy.
Definition: PHNSim.cpp:317
bool isConnected()
Checks if the SIM has a connection with a network (is registered)
Definition: PHNSim.cpp:243
struct SimContact SimContact
A single message contact.
int getRegStatus()
Reads the SIM network registration status.
Definition: PHNSim.cpp:233
int getContactCount()
Gets how many valid contacts are stored in the current good book.
Definition: PHNSim.cpp:546
void init()
Ensures the SIM logic is initalized.
Definition: PHNSim.cpp:32
void writeDate(char *buffer, Date date)
Writes a DATE argument to an output buffer.
Definition: PHNSim.cpp:813
void acceptCall()
Accepts the call.
Definition: PHNSim.cpp:322
const char * getIncomingNumber()
Gets the number of the person calling this SIM.
Definition: PHNSim.cpp:336
int readSignalLevel()
Reads the signal level in dB, is 0 when there is no connection.
Definition: PHNSim.cpp:276
void end()
Shuts off the SIM.
Definition: PHNSim.cpp:62
void togglePower()
Toggles power on or off - for async toggling.
Definition: PHNSim.cpp:86
int getContactTextLimit() const
Gets the maximum length of a contact text field.
Definition: PHNSim.h:193
bool setContactBook(const char *bookName)
Switches to a different phone book to access contacts of.
Definition: PHNSim.cpp:509
float readBatteryLevel()
Reads the battery level ranging 0.0 (empty) to 1.0 (full)
Definition: PHNSim.cpp:264
int getCallStatus()
Gets the calling status.
Definition: PHNSim.cpp:331
bool readProvider(char *buffer, int bufferLength)
Reads the SIM provider name.
Definition: PHNSim.cpp:248
int getContactLimit() const
Gets how many contacts can possibly be stored in the current book.
Definition: PHNSim.h:189
Various utility functions for use all-around.
bool isSimCardInserted()
Checks whether a (valid) SIM card is inserted.
Definition: PHNSim.cpp:208
Pinout information for the Phoenard hardware components.
void sendDTMF(char character)
Sends a DTMF tone number, does nothing when character is NULL.
Definition: PHNSim.cpp:341
SimMessage getNewMessage()
Reads the message received last.
Definition: PHNSim.cpp:389
void deleteMessage(int messageIndex)
Deletes a message from the inbox.
Definition: PHNSim.cpp:395
bool setContact(int contactIndex, SimContact contact)
Writes new contact information at the index in the current book.
Definition: PHNSim.cpp:582
bool writeATCommand(const char *command)
Writes the command, handling non-responsiveness and retries, not reading the full response...
Definition: PHNSim.cpp:624
bool hasNewMessage()
Checks whether a new message is available.
Definition: PHNSim.cpp:384
int getContactNumberLimit() const
Gets the maximum length of a contact number field.
Definition: PHNSim.h:191
Date-related functions.
void call(const char *address)
Initiates a call.
Definition: PHNSim.cpp:300
struct SimMessage SimMessage
A single text message.
bool isOn()
Checks if the SIM is currently turned on.
Definition: PHNSim.cpp:82
Simplistic library to make use of the SIM908 (phone) controller.
Definition: PHNSim.h:104
bool enterPin(const char *pin)
Enters SIM Pin code.
Definition: PHNSim.cpp:179
bool addContact(SimContact contact)
Adds new contact information to the current book.
Definition: PHNSim.cpp:578
bool sendATCommand(const char *command)
Sends a command, returns whether it was successful.
Definition: PHNSim.cpp:664
bool setVolume(int level)
Sets the volume of the loudspeaker using a level 0 - 100.
Definition: PHNSim.cpp:351
int getMessageCount()
Gets the amount of messages stored in memory.
Definition: PHNSim.cpp:358
Date readDate(char *text)
Reads a DATE argument from received response (note: alters text buffer)
Definition: PHNSim.cpp:794
SimContact getContact(int contactIndex)
Reads the contact stored at the index in the current book.
Definition: PHNSim.cpp:559