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 (string) – 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: int
-
AddCategory
(Type, Name)¶ Adds category to phone.
Parameters: - Type (string) – Type of category to read, one of
ToDo
,Phonebook
- Name (string) – Category name
Returns: Location of created category
Return type: - Type (string) – Type of category to read, one of
-
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: dict
-
AddFolder
(ParentFolderID, Name)¶ Adds folder to filesystem.
Parameters: - ParentFolderID (string) – Folder where to create subfolder
- Name (string) – New folder name
Returns: New folder ID.
Return type: string
-
AddMemory
(Value)¶ Adds memory (phonebooks or calls) entry.
Parameters: Value (dict) – Memory entry, see Phonebook Object Returns: Location of created entry Return type: int
-
AddSMS
(Value)¶ Adds SMS to specified folder.
Parameters: Value (dict) – SMS data, see SMS Object Returns: Tuple for location and folder. Return type: tuple
-
AddSMSFolder
(Name)¶ Creates SMS folder.
Parameters: Name (string) – Name of new folder Returns: None Return type: None
-
AddToDo
(Value)¶ Adds ToDo in phone.
Parameters: Value (dict) – ToDo data, see Todo Object Returns: Location of created entry Return type: int
-
AnswerCall
(ID, All)¶ Accept current incoming call.
Parameters: Returns: None
Return type:
-
CancelCall
(ID, All)¶ Deny current incoming call.
Parameters: Returns: None
Return type:
-
ConferenceCall
(ID)¶ Initiates conference call.
Parameters: ID (int) – ID of call Returns: None Return type: None
-
DeleteAllMemory
(Type)¶ Deletes all memory (phonebooks or calls) entries of specified type.
Parameters: Type (string) – Memory type, one of ME
,SM
,ON
,DC
,RC
,MC
,MT
,FD
,VM
Returns: None Return type: None
-
DeleteCalendar
(Location)¶ Deletes calendar entry.
Parameters: Location (int) – Calendar entry to delete Returns: None Return type: None
-
DeleteFile
(FileID)¶ Deletes file from filesystem.
Parameters: FileID (string) – File to delete Returns: None Return type: None
-
DeleteFolder
(FolderID)¶ Deletes folder on filesystem.
Parameters: FolderID (string) – Folder to delete Returns: None Return type: None
-
DeleteMemory
(Type, Location)¶ Deletes memory (phonebooks or calls) entry.
Parameters: - Type (string) – Memory type, one of
ME
,SM
,ON
,DC
,RC
,MC
,MT
,FD
,VM
- Location (int) – Location of entry to delete
Returns: None
Return type: - Type (string) – Memory type, one of
-
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.
Parameters: ID (int) – Index of folder to delete Returns: None Return type: None
-
DeleteToDo
(Location)¶ Deletes ToDo entry in phone.
Parameters: Location (int) – Location of entry to delete Returns: None Return type: None
-
DialService
(Number)¶ Dials number and starts voice call.
Parameters: Number (string) – Number to dial Returns: None Return type: None
-
DialVoice
(Number, ShowNumber)¶ Dials number and starts voice call.
Parameters: Returns: None
Return type:
-
EnterSecurityCode
(Type, Code, NewPIN)¶ Enters security code.
Parameters: - Type (string) – What code to enter, one of
PIN
,PUK
,PIN2
,PUK2
,Phone
. - Code (string) – Code value
- NewPIN (string) – New PIN value in case entering PUK
Returns: None
Return type: - Type (string) – What code to enter, one of
-
GetAlarm
(Location)¶ Reads alarm set in phone.
Parameters: Location (int) – Which alarm to read. Many phone support only one alarm. Default is 1. Returns: Alarm dict Return type: dict
-
GetBatteryCharge
()¶ Gets information about battery charge and phone charging state.
Returns: Dictionary containing information about battery state (BatteryPercent and ChargeState) Return type: dict
-
GetCalendar
(Location)¶ Retrieves calendar entry.
Parameters: Location (int) – Calendar entry to read Returns: Dictionary with calendar values, see Calendar Object Return type: dict
-
GetCalendarStatus
()¶ Retrieves calendar status (number of used entries).
Returns: Dictionary with calendar status (Used) Return type: dict
-
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.
Parameters: - Type (string) – Type of category to read, one of
ToDo
,Phonebook
- Location (int) – Location of category to read
Returns: Category name as string
Return type: string
- Type (string) – Type of category to read, one of
-
GetCategoryStatus
(Type)¶ Reads category status (number of used entries) from phone.
Parameters: Type (string) – Type of category to read, one of ToDo
,Phonebook
Returns: Dictionary containing information about category status (Used) Return type: dict
-
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
Parameters: Section (int) – Index of config section to read. Defaults to 0. Returns: Dictionary containing configuration Return type: dict
-
GetDateTime
()¶ Reads date and time from phone.
Returns: Date and time from phone as datetime.datetime object. Return type: datetime.datetime
-
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: dict
-
GetFileSystemStatus
()¶ Acquires filesystem status.
Returns: Dictionary containing filesystem status (Used and Free) Return type: dict
-
GetFirmware
()¶ Reads firmware information from phone.
Returns: Tuple from version, date and numeric version. Return type: tuple
-
GetFolderListing
(Folder, Start)¶ Gets next filename from filesystem folder.
Parameters: - Folder (string) – Folder to list
- Start (bool) – Whether we’re starting listing. Defaults to False.
Returns: File data as dict, see File Object
Return type:
-
GetHardware
()¶ Gets hardware information about device.
Returns: Hardware information as string. Return type: string
-
GetIMEI
()¶ Reads IMEI/serial number from phone.
Returns: IMEI of phone as string. Return type: string
-
GetLocale
()¶ Gets locale information from phone.
Returns: Dictionary of locale settings. SetLocale()
lists them all.Return type: dict
-
GetManufactureMonth
()¶ Gets month when device was manufactured.
Returns: Month of manufacture as string. Return type: string
-
GetManufacturer
()¶ Reads manufacturer from phone.
Returns: String with manufacturer name Return type: string
-
GetMemory
(Type, Location)¶ Reads entry from memory (phonebooks or calls). Which entry should be read is defined in entry.
Parameters: Type (string) – Memory type, one of ME
,SM
,ON
,DC
,RC
,MC
,MT
,FD
,VM
Returns: Memory entry as dict, see Phonebook Object Return type: dict
-
GetMemoryStatus
(Type)¶ Gets memory (phonebooks or calls) status (eg. number of used and free entries).
Parameters: Type (string) – Memory type, one of ME
,SM
,ON
,DC
,RC
,MC
,MT
,FD
,VM
Returns: Dictionary with information about memory (Used and Free) Return type: dict
-
GetModel
()¶ Reads model from phone.
Returns: Tuple containing gammu identification and real model returned by phone. Return type: tuple
-
GetNetworkInfo
()¶ Gets network information.
Returns: Dictionary with information about network (NetworkName, State, NetworkCode, CID and LAC) Return type: dict
-
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: dict
-
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 (string) – 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: string
-
GetPPM
()¶ Gets PPM (Post Programmable Memory) from phone.
Returns: PPM as string Return type: string
-
GetProductCode
()¶ Gets product code of device. :return: Product code as string. :rtype: string
-
GetSIMIMSI
()¶ Gets SIM IMSI from phone.
Returns: SIM IMSI as string Return type: string
-
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: dict
-
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: dict
-
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: string
-
GetSignalQuality
()¶ Reads signal quality (strength and error rate).
Returns: Dictionary containing information about signal state (SignalStrength, SignalPercent and BitErrorRate) Return type: dict
-
GetSpeedDial
(Location)¶ Gets speed dial.
Parameters: Location (int) – Location of entry to read Returns: Dictionary with speed dial (Location, MemoryLocation, MemoryNumberID, MemoryType) Return type: dict
-
GetToDo
(Location)¶ Reads ToDo from phone.
Parameters: Location (int) – Location of entry to read Returns: Dictionary with ToDo values, see Todo Object Return type: dict
-
GetToDoStatus
()¶ Gets status of ToDos (count of used entries).
Returns: Dictionary of status (Used) Return type: dict
-
Init
(Replies)¶ Initialises the connection with phone.
Parameters: Replies (int) – Number of replies to wait for on each request. Defaults to 1. Higher value makes sense only on unreliable links. Returns: None Return type: None
-
PressKey
(Key, Press)¶ Emulates key press.
Parameters: - Key (string) – What key to press
- Press (bool) – Whether to emulate press or release.
Returns: None
Return type:
-
ReadConfig
(Section, Configuration, Filename)¶ Reads specified section of gammurc
Parameters: Returns: None
Return type:
-
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.
Parameters: Wait (bool) – Whether to wait, default is not to wait. Returns: Number of bytes read Return type: int
-
Reset
(Hard)¶ Performs phone reset.
Parameters: Hard (bool) – Whether to make hard reset Returns: None Return type: None
-
ResetPhoneSettings
(Type)¶ Resets phone settings.
Parameters: Type (string) – What to reset, one of PHONE
,UIF
,ALL
,DEV
,FACTORY
Returns: None Return type: None
-
SendDTMF
(Number)¶ Sends DTMF (Dual Tone Multi Frequency) tone.
Parameters: Number (string) – Number to dial Returns: None Return type: None
-
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: dict
-
SendSMS
(Value)¶ Sends SMS.
Parameters: Value (dict) – SMS data, see SMS Object Returns: Message reference as int Return type: int
-
SendSavedSMS
(Folder, Location)¶ Sends SMS saved in phone.
Parameters: Returns: Message reference as int
Return type:
-
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 (string) – 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: int
-
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 (string) – 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: None
-
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: - File (mixed) – File where to write debug stuff (as configured by
-
SetDebugLevel
(Level)¶ Sets state machine debug level accorting to passed string. You need to configure output file using
SetDebugFile()
to activate it.Parameters: Level (string) – name of debug level to use, currently one of: - nothing - text - textall - binary - errors - textdate - textalldate - errorsdate Returns: None Return type: None
-
SetFileAttributes
(Filename, ReadOnly, Protected, System, Hidden)¶ Sets file attributes.
Parameters: Returns: None
Return type:
-
SetIncomingCB
(Enable)¶ Gets network information from phone.
Parameters: Enable (bool) – Whether to enable notifications, default is True Returns: None Return type: None
-
SetIncomingCall
(Enable)¶ Activates/deactivates noticing about incoming calls.
Parameters: Enable (bool) – Whether to enable notifications, default is True Returns: None Return type: None
-
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: None
-
SetIncomingSMS
(Enable)¶ Enable/disable notification on incoming SMS.
Parameters: Enable (bool) – Whether to enable notifications, default is True Returns: None Return type: None
-
SetIncomingUSSD
(Enable)¶ Activates/deactivates noticing about incoming USSDs (UnStructured Supplementary Services).
Parameters: Enable (bool) – Whether to enable notifications, default is True Returns: None Return type: None
-
SetLocale
(DateSeparator, DateFormat, AMPMTime)¶ Sets locale of phone.
Parameters: - DateSeparator (string) – Date separator.
- DateFormat (string) – Date format, one of
DDMMYYYY
,MMDDYYYY
,YYYYMMDD
- AMPMTime (bool) – Whether to use AM/PM time.
Returns: None
Return type:
-
SetMemory
(Value)¶ Sets memory (phonebooks or calls) entry.
Parameters: Value (dict) – Memory entry, see Phonebook Object Returns: Location of created entry Return type: int
-
SetSMS
(Value)¶ Sets SMS.
Parameters: Value (dict) – SMS data, see SMS Object Returns: Tuple for location and folder. Return type: tuple
-
SetSMSC
(Value)¶ Sets SMS Service Center number and SMS settings.
Parameters: Value (dict) – SMSC information, see SMSC Object Returns: None Return type: None
-
SetSpeedDial
(Value)¶ Sets speed dial.
Parameters: Value (dict) – Speed dial data, see GetSpeedDial()
for listing.Returns: None Return type: None
-
SetToDo
(Value)¶ Sets ToDo in phone.
Parameters: Value (dict) – ToDo data, see Todo Object Returns: Location of created entry Return type: int
-
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: None
-
gammu.
SetDebugLevel
(Level)¶ Sets global debug level accorting to passed string. You need to configure output file using
SetDebugFile()
to activate it.Parameters: Level (string) – name of debug level to use, currently one of:
- nothing
- text
- textall
- binary
- errors
- textdate
- textalldate
- errorsdate
Returns: None Return type: None
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: - Text (string) – Message text
- UDH (string) – Message UDH
- Coding (string) – Message coding (eg. Unicode or Default)
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: dict
-
gammu.
DecodePDU
(Data, SMSC = False)¶ Parses PDU packet.
Parameters: - Data (string) – PDU data, need to be binary not hex encoded
- SMSC (bool) – Whether PDU includes SMSC.
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 (string) – Layout (one of Submit, Deliver, StatusReport), Submit is default
Returns: Message data
Return type: string
New in version 1.27.93.
Encoding and decoding entries¶
-
gammu.
DecodeVCARD
(Text)¶ Decodes memory entry v from a string.
Parameters: Text (string) – String to decode Returns: Memory entry, see Phonebook Object Return type: dict
-
gammu.
EncodeVCARD
(Entry)¶ Encodes memory entry to a vCard.
Parameters: Entry (dict) – Memory entry, see Phonebook Object Returns: String with vCard Return type: string
-
gammu.
DecodeVCS
(Text)¶ Decodes todo/calendar entry v from a string.
Parameters: Text (string) – String to decode Returns: Calendar or todo entry (whatever one was included in string), see Calendar Object, Todo Object Return type: dict
-
gammu.
DecodeICS
(Text)¶ Decodes todo/calendar entry v from a string.
Parameters: Text (string) – String to decode Returns: Calendar or todo entry (whatever one was included in string), see Calendar Object, Todo Object Return type: dict
-
gammu.
EncodeVCALENDAR
(Entry)¶ Encodes calendar entry to a vCalendar.
Parameters: Entry (dict) – Calendar entry, see Calendar Object Returns: String with vCalendar Return type: string
-
gammu.
EncodeICALENDAR
(Entry)¶ Encodes calendar entry to a iCalendar.
Parameters: Entry (dict) – Calendar entry, see Calendar Object Returns: String with iCalendar Return type: string
-
gammu.
EncodeVTODO
(Entry)¶ Encodes todo entry to a vTodo.
Parameters: Entry (dict) – Todo entry, see Todo Object Returns: String with vTodo Return type: string
-
gammu.
EncodeITODO
(Entry)¶ Encodes todo entry to a iTodo.
Parameters: Entry (dict) – Todo entry, see Todo Object Returns: String with vCard Return type: string
Backup reading and writing¶
-
gammu.
SaveRingtone
(Filename, Ringtone, Format)¶ Saves ringtone into file.
Parameters: - Filename (string) – Name of file where ringote will be saved
- Ringtone (dict) – Ringtone to save
- Format (string) – One of
ott
,mid
,rng
,imy
,wav
,rttl
Returns: None
Return type:
-
gammu.
SaveBackup
(Filename, Backup, Format)¶ Saves backup into file.
Parameters: - Filename (string) – Name of file to read backup from
- Backup (dict) – Backup data, see
ReadBackup()
for description - Format (string) – 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: - Filename (string) – Name of file where backup is stored
- Format (string) – File format to use (
Auto
,AutoUnicode
,LMB
,VCalendar
,VCard
,LDIF
,ICS
,Gammu
,GammuUnicode
, the default isAutoUnicode
)
Returns: Dictionary of read entries, it contains following keys, each might be empty:
- IMEI
- Model
- Creator
- PhonePhonebook
- SIMPhonebook
- Calendar
- ToDo
- DateTime
Return type: