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.