gammu
– Mobile phone access¶
This module wraps all python-gammu functionality.
gammu.StateMachine
¶
- class gammu.StateMachine(Locale)¶
StateMachine object, that is used for communication with phone.
- Parameters
Locale (str) – What locales to use for gammu error messages, default is
auto
which does autodetection according to user locales
- AddCalendar(Value)¶
Adds calendar entry.
- Parameters
Value (dict) – Calendar entry data, see Calendar Object
- Returns
Location of newly created entry
- Return type
- AddCategory(Type, Name)¶
Adds category to phone.
- AddFilePart(File)¶
Adds file part to filesystem.
- Parameters
File (dict) – File data, see File Object
- Returns
File data for subsequent calls (Finished indicates transfer has been completed)
- Return type
- AddFolder(ParentFolderID, Name)¶
Adds folder to filesystem.
- AddMemory(Value)¶
Adds memory (phonebooks or calls) entry.
- Parameters
Value (dict) – Memory entry, see Phonebook Object
- Returns
Location of created entry
- Return type
- AddSMS(Value)¶
Adds SMS to specified folder.
- Parameters
Value (dict) – SMS data, see SMS Object
- Returns
Tuple for location and folder.
- Return type
- AddSMSFolder(Name)¶
Creates SMS folder.
- AddToDo(Value)¶
Adds ToDo in phone.
- Parameters
Value (dict) – ToDo data, see Todo Object
- Returns
Location of created entry
- Return type
- AnswerCall(ID, All)¶
Accept current incoming call.
- CancelCall(ID, All)¶
Deny current incoming call.
- ConferenceCall(ID)¶
Initiates conference call.
- DeleteAllMemory(Type)¶
Deletes all memory (phonebooks or calls) entries of specified type.
- DeleteCalendar(Location)¶
Deletes calendar entry.
- DeleteFile(FileID)¶
Deletes file from filesystem.
- DeleteFolder(FolderID)¶
Deletes folder on filesystem.
- DeleteMemory(Type, Location)¶
Deletes memory (phonebooks or calls) entry.
- DeleteSMS(Folder, Location)¶
Deletes SMS.
- Parameters
- Returns
None
- Return type
Note
In most cases you want to use Folder=0 as in this mode it will accept locations as GetNextSMS returns them.
- DeleteSMSFolder(ID)¶
Deletes SMS folder.
- DeleteToDo(Location)¶
Deletes ToDo entry in phone.
- DialService(Number)¶
Dials number and starts voice call.
- DialVoice(Number, ShowNumber)¶
Dials number and starts voice call.
- EnterSecurityCode(Type, Code, NewPIN)¶
Enters security code.
- GetAlarm(Location)¶
Reads alarm set in phone.
- GetBatteryCharge()¶
Gets information about battery charge and phone charging state.
- Returns
Dictionary containing information about battery state (BatteryPercent and ChargeState)
- Return type
- GetCalendar(Location)¶
Retrieves calendar entry.
- Parameters
Location (int) – Calendar entry to read
- Returns
Dictionary with calendar values, see Calendar Object
- Return type
- GetCalendarStatus()¶
Retrieves calendar status (number of used entries).
- Returns
Dictionary with calendar status (Used)
- Return type
- GetCallDivert(Divert='AllTypes', Type='All')¶
New in version 1.31.90.
Gets call diverts.
- Parameters
Divert (Divert Type) – When to do the divert.
Type (Call Type) – What call types to divert.
- Returns
List of call diverts.
- Return type
- GetCategory(Type, Location)¶
Reads category from phone.
- GetCategoryStatus(Type)¶
Reads category status (number of used entries) from phone.
- GetConfig(Section)¶
- Gets specified config section. Configuration consists of all params which can be defined in gammurc config file:
Model
DebugLevel
Device
Connection
SyncTime
LockDevice
DebugFile
StartInfo
UseGlobalDebugFile
- GetDateTime()¶
Reads date and time from phone.
- Returns
Date and time from phone as datetime.datetime object.
- Return type
- GetDisplayStatus()¶
Acquired display status. :return: List of indicators displayed on display :rtype: list
- GetFilePart(File)¶
Gets file part from filesystem.
- Parameters
File (dict) – File data, see File Object
- Returns
File data for subsequent calls (Finished indicates transfer has been completed), see File Object
- Return type
- GetFileSystemStatus()¶
Acquires filesystem status.
- Returns
Dictionary containing filesystem status (Used and Free)
- Return type
- GetFirmware()¶
Reads firmware information from phone.
- Returns
Tuple from version, date and numeric version.
- Return type
- GetFolderListing(Folder, Start)¶
Gets next filename from filesystem folder.
- Parameters
- Returns
File data as dict, see File Object
- Return type
- GetHardware()¶
Gets hardware information about device.
- Returns
Hardware information as str.
- Return type
- GetLocale()¶
Gets locale information from phone.
- Returns
Dictionary of locale settings.
SetLocale()
lists them all.- Return type
- GetManufactureMonth()¶
Gets month when device was manufactured.
- Returns
Month of manufacture as str.
- Return type
- GetManufacturer()¶
Reads manufacturer from phone.
- Returns
String with manufacturer name
- Return type
- GetMemory(Type, Location)¶
Reads entry from memory (phonebooks or calls). Which entry should be read is defined in entry.
- Parameters
Type (str) – Memory type, one of
ME
,SM
,ON
,DC
,RC
,MC
,MT
,FD
,VM
- Returns
Memory entry as dict, see Phonebook Object
- Return type
- GetMemoryStatus(Type)¶
Gets memory (phonebooks or calls) status (eg. number of used and free entries).
- GetModel()¶
Reads model from phone.
- Returns
Tuple containing gammu identification and real model returned by phone.
- Return type
- GetNetworkInfo()¶
Gets network information.
- Returns
Dictionary with information about network (NetworkName, State, NetworkCode, CID and LAC)
- Return type
- GetNextCalendar(Start, Location)¶
Retrieves calendar entry. This is useful for continuous reading of all calendar entries.
- Parameters
- Returns
Dictionary with calendar values, see Calendar Object
- Return type
- GetNextFileFolder(Start)¶
Gets next filename from filesystem.
- Parameters
Start (bool) – Whether we’re starting listing. Defaults to False.
- Returns
File data as dict, see File Object
- Return type
- GetNextMemory(Type, Start, Location)¶
Reads entry from memory (phonebooks or calls). Which entry should be read is defined in entry. This can be easily used for reading all entries.
- Parameters
- Returns
Memory entry as dict, see Phonebook Object
- Return type
- GetNextRootFolder(Folder)¶
Gets next root folder from filesystem. Start with empty folder name.
- Parameters
Folder (str) – Previous read folder. Start with empty folder name.
- Returns
Structure with folder information
- GetNextSMS(Folder, Start, Location)¶
Reads next (or first if start set) SMS message. This might be faster for some phones than using
GetSMS()
for each message.- Parameters
- Returns
Dictionary with SMS data, see SMS Object
- Return type
- GetNextToDo(Start, Location)¶
Reads ToDo from phone.
- Parameters
- Returns
Dictionary with ToDo values, see Todo Object
- Return type
- GetOriginalIMEI()¶
Gets original IMEI from phone.
- Returns
Original IMEI of phone as string.
- Return type
- GetProductCode()¶
Gets product code of device. :return: Product code as string. :rtype: str
- GetSMS(Folder, Location)¶
Reads SMS message.
- Parameters
- Returns
Dictionary with SMS data, see SMS Object
- Return type
- GetSMSC(Location)¶
Gets SMS Service Center number and SMS settings.
- Parameters
Location (int) – Location of entry to read. Defaults to 1
- Returns
Dictionary with SMSC information, see SMSC Object
- Return type
- GetSMSStatus()¶
Gets information about SMS memory (read/unread/size of memory for both SIM and phone).
- Returns
Dictionary with information about phone memory (SIMUnRead, SIMUsed, SIMSize, PhoneUnRead, PhoneUsed, PhoneSize and TemplatesUsed)
- Return type
- GetSecurityStatus()¶
Queries whether some security code needs to be entered.
- Returns
String indicating which code needs to be entered or None if none is needed
- Return type
- GetSignalQuality()¶
Reads signal quality (strength and error rate).
- Returns
Dictionary containing information about signal state (SignalStrength, SignalPercent and BitErrorRate)
- Return type
- GetSpeedDial(Location)¶
Gets speed dial.
- GetToDo(Location)¶
Reads ToDo from phone.
- Parameters
Location (int) – Location of entry to read
- Returns
Dictionary with ToDo values, see Todo Object
- Return type
- GetToDoStatus()¶
Gets status of ToDos (count of used entries).
- Returns
Dictionary of status (Used)
- Return type
- Init(Replies)¶
Initialises the connection with phone.
- PressKey(Key, Press)¶
Emulates key press.
- ReadConfig(Section, Configuration, Filename)¶
Reads specified section of gammurc
- ReadDevice(Wait)¶
Reads data from device. This should be used in busy wait loop in case you are waiting for incoming events on the device.
- Reset(Hard)¶
Performs phone reset.
- ResetPhoneSettings(Type)¶
Resets phone settings.
- SendDTMF(Number)¶
Sends DTMF (Dual Tone Multi Frequency) tone.
- SendFilePart(File)¶
Sends file part to phone.
- Parameters
File (dict) – File data, see File Object
- Returns
File data for subsequent calls (Finished indicates transfer has been completed), see File Object
- Return type
- SendSMS(Value)¶
Sends SMS.
- Parameters
Value (dict) – SMS data, see SMS Object
- Returns
Message reference as int
- Return type
- SendSavedSMS(Folder, Location)¶
Sends SMS saved in phone.
- SetAlarm(DateTime, Location, Repeating, Text)¶
Sets alarm in phone.
- Parameters
DateTime (datetime.datetime) – When should alarm happen.
Location (int) – Location of alarm to set. Defaults to 1.
Repeating (bool) – Whether alarm should be repeating. Defaults to True.
Text (str) – Text to be displayed on alarm. Defaults to empty.
- Returns
None
- Return type
- SetCalendar(Value)¶
Sets calendar entry
- Parameters
Value (dict) – Calendar entry data, see Calendar Object
- Returns
Location of set entry
- Return type
- SetConfig(Section, Values)¶
Sets specified config section.
- Parameters
Section (int) – Index of config section to modify
Values (dict) – Config values, see
GetConfig()
for description of accepted
- Returns
None
- Return type
- SetCallDivert(Divert, Type, Number, Timeout=0)¶
New in version 1.31.90.
Sets call divert.
- Parameters
Divert (Divert Type) – When to do the divert.
Type (Call Type) – What call types to divert.
Number (str) – Phone number where to divert.
Timeout (int) – Optional timeout when divert happens.
- Returns
None
- Return type
- SetDateTime(Date)¶
Sets date and time in phone.
- Parameters
Date (datetime.datetime) – Date to set
- Returns
None
- Return type
- SetDebugFile(File, Global)¶
Sets state machine debug file.
- Parameters
File (mixed) – File where to write debug stuff (as configured by
SetDebugLevel()
). Can be either None for no file, Python file object or filename.Global (bool) – Whether to use global debug structure (overrides File)
- Returns
None
- Return type
- SetDebugLevel(Level)¶
Sets state machine debug level accorting to passed string. You need to configure output file using
SetDebugFile()
to activate it.
- SetFileAttributes(Filename, ReadOnly, Protected, System, Hidden)¶
Sets file attributes.
- Parameters
- Returns
None
- Return type
- SetIncomingCB(Enable)¶
Gets network information from phone.
- SetIncomingCall(Enable)¶
Activates/deactivates noticing about incoming calls.
- SetIncomingCallback(Callback)¶
Sets callback function which is called whenever any (enabled) incoming event appears. Please note that you have to enable each event type by calling SetIncoming* functions.
The callback function needs to accept three parameters: StateMachine object, event type and it’s data in dictionary.
- Parameters
Callback (function) – callback function or None for disabling
- Returns
None
- Return type
- SetIncomingSMS(Enable)¶
Enable/disable notification on incoming SMS.
- SetIncomingUSSD(Enable)¶
Activates/deactivates noticing about incoming USSDs (UnStructured Supplementary Services).
- SetLocale(DateSeparator, DateFormat, AMPMTime)¶
Sets locale of phone.
- SetMemory(Value)¶
Sets memory (phonebooks or calls) entry.
- Parameters
Value (dict) – Memory entry, see Phonebook Object
- Returns
Location of created entry
- Return type
- SetSMS(Value)¶
Sets SMS.
- Parameters
Value (dict) – SMS data, see SMS Object
- Returns
Tuple for location and folder.
- Return type
- SetSMSC(Value)¶
Sets SMS Service Center number and SMS settings.
- Parameters
Value (dict) – SMSC information, see SMSC Object
- Returns
None
- Return type
- SetSpeedDial(Value)¶
Sets speed dial.
- Parameters
Value (dict) – Speed dial data, see
GetSpeedDial()
for listing.- Returns
None
- Return type
- SetToDo(Value)¶
Sets ToDo in phone.
- Parameters
Value (dict) – ToDo data, see Todo Object
- Returns
Location of created entry
- Return type
- TransferCall(ID, Next)¶
Transfers call.
Generic functions¶
Debugging configuration¶
- gammu.SetDebugFile(File)¶
Sets global debug file.
- Parameters
File (mixed) – File where to write debug stuff (as configured by
SetDebugLevel()
). Can be either None for no file, Python file object or filename.- Returns
None
- Return type
- gammu.SetDebugLevel(Level)¶
Sets global debug level accorting to passed string. You need to configure output file using
SetDebugFile()
to activate it.
Message processing¶
- gammu.LinkSMS(Messages, EMS)¶
Links multi part SMS messages.
- Parameters
Messages (list) – List of messages to link, see SMS Object
EMS (bool) – Whether to detect ems, defauls to True
- Returns
List of linked messages, see SMS Object
- Return type
- gammu.SMSCounter(Text, UDH='NoUDH', Coding='Default')¶
Calculates number of SMS and free chars in SMS.
- Parameters
- Returns
Number of messages and number of free chars
- Return type
New in version 1.29.90.
- gammu.DecodeSMS(Messages, EMS)¶
Decodes multi part SMS message.
- Parameters
Messages (list) – Nessages to decode, see SMS Object
EMS (bool) – Whether to use EMS, defalt to True
- Returns
Multi part message information, see SMS Info Object
- Return type
- gammu.EncodeSMS(MessageInfo)¶
Encodes multi part SMS message.
- Parameters
MessageInfo (dict) – Description of message, see SMS Info Object
- Returns
List of dictionaries with raw message, see SMS Object
- Return type
- gammu.DecodePDU(Data, SMSC=False)¶
Parses PDU packet.
- Parameters
- Returns
Message data, see SMS Object
- Return type
Example:
gammu.DecodePDU( '0681678968986811000a8152564557550010ff0d3bf67aed5ebbddeb1d7bed06'.decode('hex') )
- gammu.EncodePDU(SMS, Layout=Submit)¶
Creates PDU packet.
- Parameters
SMS (dict) – SMS dictionary, see SMS Object
Layout (str) – Layout (one of Submit, Deliver, StatusReport), Submit is default
- Returns
Message data
- Return type
New in version 1.27.93.
Encoding and decoding entries¶
- gammu.DecodeVCARD(Text)¶
Decodes memory entry v from a string.
- Parameters
Text (str) – String to decode
- Returns
Memory entry, see Phonebook Object
- Return type
- gammu.EncodeVCARD(Entry)¶
Encodes memory entry to a vCard.
- Parameters
Entry (dict) – Memory entry, see Phonebook Object
- Returns
String with vCard
- Return type
- gammu.DecodeVCS(Text)¶
Decodes todo/calendar entry v from a string.
- Parameters
Text (str) – String to decode
- Returns
Calendar or todo entry (whatever one was included in string), see Calendar Object, Todo Object
- Return type
- gammu.DecodeICS(Text)¶
Decodes todo/calendar entry v from a string.
- Parameters
Text (str) – String to decode
- Returns
Calendar or todo entry (whatever one was included in string), see Calendar Object, Todo Object
- Return type
- gammu.EncodeVCALENDAR(Entry)¶
Encodes calendar entry to a vCalendar.
- Parameters
Entry (dict) – Calendar entry, see Calendar Object
- Returns
String with vCalendar
- Return type
- gammu.EncodeICALENDAR(Entry)¶
Encodes calendar entry to a iCalendar.
- Parameters
Entry (dict) – Calendar entry, see Calendar Object
- Returns
String with iCalendar
- Return type
- gammu.EncodeVTODO(Entry)¶
Encodes todo entry to a vTodo.
- Parameters
Entry (dict) – Todo entry, see Todo Object
- Returns
String with vTodo
- Return type
- gammu.EncodeITODO(Entry)¶
Encodes todo entry to a iTodo.
- Parameters
Entry (dict) – Todo entry, see Todo Object
- Returns
String with vCard
- Return type
Backup reading and writing¶
- gammu.SaveRingtone(Filename, Ringtone, Format)¶
Saves ringtone into file.
- gammu.SaveBackup(Filename, Backup, Format)¶
Saves backup into file.
- Parameters
Filename (str) – Name of file to read backup from
Backup (dict) – Backup data, see
ReadBackup()
for descriptionFormat (str) – File format to use (
Auto
,AutoUnicode
,LMB
,VCalendar
,VCard
,LDIF
,ICS
,Gammu
,GammuUnicode
, the default isAutoUnicode
)
- Returns
None
- Return type
- gammu.ReadBackup(Filename, Format)¶
Reads backup into file.
- Parameters
- Returns
Dictionary of read entries, it contains following keys, each might be empty:
IMEI
Model
Creator
PhonePhonebook
SIMPhonebook
Calendar
ToDo
DateTime
- Return type
- gammu.SaveSMSBackup(Filename, Backup)¶
Saves SMS backup into file.
Various data¶
- gammu.GSMNetworks¶
Dictionary with GSM network codes.
- gammu.GSMCountries¶
Dictionary with GSM country codes.