# python-gammu

## A taste of python-gammu

Python-gammu allows you to easily access the phone. Following code will connect to phone based on your Gammu configuration (usually stored in `~/.gammurc`) and gets network information from it:

    import gammu
    import sys

    # Create state machine object
    sm = gammu.StateMachine()

    # Read ~/.gammurc
    sm.ReadConfig()

    # Connect to phone
    sm.Init()

    # Reads network information from phone
    netinfo = sm.GetNetworkInfo()

    # Print information
    print 'Network name: %s' % netinfo['NetworkName']
    print 'Network code: %s' % netinfo['NetworkCode']
    print 'LAC: %s' % netinfo['LAC']
    print 'CID: %s' % netinfo['CID']

## API documentation

- `gammu` – Mobile phone access
  - `gammu.StateMachine`
    - `StateMachine`
  - Generic functions
    - `Version()`
  - Debugging configuration
    - `SetDebugFile()`
    - `SetDebugLevel()`
  - Message processing
    - `LinkSMS()`
    - `SMSCounter()`
    - `DecodeSMS()`
    - `EncodeSMS()`
    - `DecodePDU()`
    - `EncodePDU()`
  - Encoding and decoding entries
    - `DecodeVCARD()`
    - `EncodeVCARD()`
    - `DecodeVCS()`
    - `DecodeICS()`
    - `EncodeVCALENDAR()`
    - `EncodeICALENDAR()`
    - `EncodeVTODO()`
    - `EncodeITODO()`
  - Backup reading and writing
    - `SaveRingtone()`
    - `SaveBackup()`
    - `ReadBackup()`
    - `SaveSMSBackup()`
    - `ReadSMSBackup()`
  - Various data
    - `GSMNetworks`
    - `GSMCountries`
- `gammu.smsd` – SMSD access
  - `SMSD`
    - `SMSD`
- `gammu.data` – Generic data usable with Gammu
  - `Connections`
  - `MemoryValueTypes`
  - `CalendarTypes`
  - `CalendarValueTypes`
  - `TodoPriorities`
  - `TodoValueTypes`
  - `InternationalPrefixes`
  - `Errors`
  - `ErrorNumbers`
- `gammu.worker` - Asynchronous communication to phone.
  - `GammuCommand`
    - `GammuCommand.get_command()`
    - `GammuCommand.get_params()`
    - `GammuCommand.get_percentage()`
  - `GammuTask`
    - `GammuTask.get_name()`
    - `GammuTask.get_next()`
  - `GammuThread`
    - `GammuThread.join()`
    - `GammuThread.kill()`
    - `GammuThread.run()`
  - `GammuWorker`
    - `GammuWorker.abort()`
    - `GammuWorker.configure()`
    - `GammuWorker.enqueue()`
    - `GammuWorker.enqueue_command()`
    - `GammuWorker.enqueue_task()`
    - `GammuWorker.initiate()`
    - `GammuWorker.terminate()`
  - `InvalidCommand`
  - `check_worker_command()`
- `gammu.exception` – Gammu exception handling
  - `gammu.GSMError`
  - `gammu.ERR_ABORTED`
  - `gammu.ERR_BADFEATURE`
  - `gammu.ERR_BUG`
  - `gammu.ERR_BUSY`
  - `gammu.ERR_CANCELED`
  - `gammu.ERR_CANTOPENFILE`
  - `gammu.ERR_CORRUPTED`
  - `gammu.ERR_COULDNT_CONNECT`
  - `gammu.ERR_COULDNT_RESOLVE`
  - `gammu.ERR_DATACONVERTED`
  - `gammu.ERR_DEVICEBUSY`
  - `gammu.ERR_DEVICECHANGESPEEDERROR`
  - `gammu.ERR_DEVICEDTRRTSERROR`
  - `gammu.ERR_DEVICELOCKED`
  - `gammu.ERR_DEVICENODRIVER`
  - `gammu.ERR_DEVICENOPERMISSION`
  - `gammu.ERR_DEVICENOTEXIST`
  - `gammu.ERR_DEVICENOTWORK`
  - `gammu.ERR_DEVICEOPENERROR`
  - `gammu.ERR_DEVICEPARITYERROR`
  - `gammu.ERR_DEVICEREADERROR`
  - `gammu.ERR_DEVICEWRITEERROR`
  - `gammu.ERR_DISABLED`
  - `gammu.ERR_EMPTY`
  - `gammu.ERR_EMPTYSMSC`
  - `gammu.ERR_FILEALREADYEXIST`
  - `gammu.ERR_FILENOTEXIST`
  - `gammu.ERR_FILENOTSUPPORTED`
  - `gammu.ERR_FOLDERNOTEMPTY`
  - `gammu.ERR_FOLDERPART`
  - `gammu.ERR_FRAMENOTREQUESTED`
  - `gammu.ERR_FULL`
  - `gammu.ERR_GETTING_SMSC`
  - `gammu.ERR_GNAPPLETWRONG`
  - `gammu.ERR_INSIDEPHONEMENU`
  - `gammu.ERR_INSTALL_NOT_FOUND`
  - `gammu.ERR_INVALIDDATA`
  - `gammu.ERR_INVALIDDATETIME`
  - `gammu.ERR_INVALIDLOCATION`
  - `gammu.ERR_MEMORY`
  - `gammu.ERR_MOREMEMORY`
  - `gammu.ERR_NEEDANOTHERANSWER`
  - `gammu.ERR_NETWORK_ERROR`
  - `gammu.ERR_NONE`
  - `gammu.ERR_NONE_SECTION`
  - `gammu.ERR_NOSERVICE`
  - `gammu.ERR_NOSIM`
  - `gammu.ERR_NOTCONNECTED`
  - `gammu.ERR_NOTIMPLEMENTED`
  - `gammu.ERR_NOTRUNNING`
  - `gammu.ERR_NOTSUPPORTED`
  - `gammu.ERR_OTHERCONNECTIONREQUIRED`
  - `gammu.ERR_PERMISSION`
  - `gammu.ERR_PHONEOFF`
  - `gammu.ERR_PHONE_INTERNAL`
  - `gammu.ERR_READ_ONLY`
  - `gammu.ERR_SECURITYERROR`
  - `gammu.ERR_SHOULDBEFILE`
  - `gammu.ERR_SHOULDBEFOLDER`
  - `gammu.ERR_SOURCENOTAVAILABLE`
  - `gammu.ERR_SPECIFYCHANNEL`
  - `gammu.ERR_TIMEOUT`
  - `gammu.ERR_UNCONFIGURED`
  - `gammu.ERR_UNKNOWN`
  - `gammu.ERR_UNKNOWNCONNECTIONTYPESTRING`
  - `gammu.ERR_UNKNOWNFRAME`
  - `gammu.ERR_UNKNOWNMODELSTRING`
  - `gammu.ERR_UNKNOWNRESPONSE`
  - `gammu.ERR_USING_DEFAULTS`
  - `gammu.ERR_WORKINPROGRESS`
  - `gammu.ERR_WRITING_FILE`
  - `gammu.ERR_WRONGCRC`
  - `gammu.ERR_WRONGFOLDER`
- Objects
  - SMS Object
  - UDH Object
  - SMSC Object
  - SMS Info Object
  - SMS Info Part Object
  - Todo Object
  - Todo Entries Object
  - Calendar Object
  - Calendar Entries Object
  - Phonebook Object
  - Phonebook Entries Object
  - File Object
  - Divert Type
  - Call Type
  - Call Divert Objects

## python-gammu Examples

See also

Many examples are available in /examples directory in the python-gammu git repository.

### Sending a message

    #!/usr/bin/env python
    # Sample script to show how to send SMS

    from __future__ import print_function
    import gammu
    import sys

    # Create object for talking with phone
    state_machine = gammu.StateMachine()

    # Optionally load config file as defined by first parameter
    if len(sys.argv) > 2:
        # Read the configuration from given file
        state_machine.ReadConfig(Filename=sys.argv[1])
        # Remove file name from args list
        del sys.argv[1]
    else:
        # Read the configuration (~/.gammurc)
        state_machine.ReadConfig()

    # Check parameters
    if len(sys.argv) != 2:
        print("Usage: sendsms.py [configfile] RECIPIENT_NUMBER")
        sys.exit(1)

    # Connect to the phone
    state_machine.Init()

    # Prepare message data
    # We tell that we want to use first SMSC number stored in phone
    message = {
        "Text": "python-gammu testing message",
        "SMSC": {"Location": 1},
        "Number": sys.argv[1],
    }

    # Actually send the message
    state_machine.SendSMS(message)

### Sending a long message

    #!/usr/bin/env python
    # Sample script to show how to send long (multipart) SMS

    from __future__ import print_function
    import gammu
    import sys

    # Create object for talking with phone
    state_machine = gammu.StateMachine()

    # Optionally load config file as defined by first parameter
    if len(sys.argv) > 2:
        # Read the configuration from given file
        state_machine.ReadConfig(Filename=sys.argv[1])
        # Remove file name from args list
        del sys.argv[1]
    else:
        # Read the configuration (~/.gammurc)
        state_machine.ReadConfig()

    # Check parameters
    if len(sys.argv) != 2:
        print("Usage: sendlongsms.py [configfile] RECIPIENT_NUMBER")
        sys.exit(1)

    # Connect to the phone
    state_machine.Init()

    # Create SMS info structure
    smsinfo = {
        "Class": -1,
        "Unicode": False,
        "Entries": [
            {
                "ID": "ConcatenatedTextLong",
                "Buffer": "Very long python-gammu testing message "
                "sent from example python script. "
                "Very long python-gammu testing message "
                "sent from example python script. "
                "Very long python-gammu testing message "
                "sent from example python script. ",
            }
        ],
    }

    # Encode messages
    encoded = gammu.EncodeSMS(smsinfo)

    # Send messages
    for message in encoded:
        # Fill in numbers
        message["SMSC"] = {"Location": 1}
        message["Number"] = sys.argv[1]

        # Actually send the message
        state_machine.SendSMS(message)

### Initiating a voice call

    #!/usr/bin/env python

    from __future__ import print_function
    import gammu
    import sys

    # Create object for talking with phone
    state_machine = gammu.StateMachine()

    # Read the configuration (~/.gammurc or from command line)
    if len(sys.argv) > 2:
        state_machine.ReadConfig(Filename=sys.argv[1])
        del sys.argv[1]
    else:
        state_machine.ReadConfig()

    # Connect to the phone
    state_machine.Init()

    # Check whether we have a number to dial
    if len(sys.argv) != 2:
        print("Usage: dialvoice.py NUMBER")
        sys.exit(1)

    # Dial a number
    state_machine.DialVoice(sys.argv[1])

### Reading calendar from phone

    #!/usr/bin/env python
    # Example for reading calendar from phone

    from __future__ import print_function
    import gammu

    # Create object for talking with phone
    state_machine = gammu.StateMachine()

    # Read the configuration (~/.gammurc)
    state_machine.ReadConfig()

    # Connect to the phone
    state_machine.Init()

    # Get number of calendar entries
    status = state_machine.GetCalendarStatus()

    remain = status["Used"]

    start = True

    while remain > 0:
        # Read the entry
        if start:
            entry = state_machine.GetNextCalendar(Start=True)
            start = False
        else:
            entry = state_machine.GetNextCalendar(Location=entry["Location"])
        remain = remain - 1

        # Display it
        print()
        print("%-20s: %d" % ("Location", entry["Location"]))
        print("%-20s: %s" % ("Type", entry["Type"]))
        for v in entry["Entries"]:
            print("%-20s: %s" % (v["Type"], str(v["Value"])))