docs/manual/gammu/index.rst

   1 .. _gammu:
   2
   3 Gammu Utility
   4 =============
   5
   6 .. program:: gammu
   7
   8 Synopsis
   9 ++++++++
  10
  11
  12 .. code-block:: text
  13
  14     gammu [parameters] <command> [options]
  15
  16 Commands actually indicate which operation should Gammu perform. They can be
  17 specified with or without leading ``--``.
  18
  19 Description
  20 +++++++++++
  21
  22 This program is a tool for mobile phones. Many vendors and phones
  23 are supported, for actual listing see `Gammu Phones Database <http://wammu.eu/phones/>`_.
  24
  25
  26 Options
  27 -------
  28
  29 Parameters before command configure gammu behaviour:
  30
  31 .. option:: -c, --config <filename>
  32
  33     name of configuration file
  34
  35 .. option:: -s, --section <confign>
  36
  37    section of config file to use, eg. 42
  38
  39 .. option:: -d, --debug <level>
  40
  41    debug level (see :config:option:`LogFormat` in :ref:`gammurc` for possible values)
  42
  43 .. option:: -f, --debug-file <filename>
  44
  45    file for logging debug messages
  46
  47
  48 Call commands
  49 -------------
  50
  51 .. option:: answercall [id]
  52
  53    Answer incoming call.
  54
  55 .. option:: cancelcall [id]
  56
  57     Cancel incoming call
  58
  59 .. option:: canceldiverts
  60
  61     Cancel all existing call diverts.
  62
  63 .. option:: conferencecall id
  64
  65     Initiates a conference call.
  66
  67 .. option:: dialvoice number [show|hide]
  68
  69     Make voice call from SIM card line set in phone.
  70
  71     ``show|hide`` - optional parameter whether to disable call number indication.
  72
  73 .. option:: divert get|set all|busy|noans|outofreach all|voice|fax|data [number timeout]
  74
  75     Manage or display call diverts.
  76
  77     ``get`` or ``set``
  78         whether to get divert information or to set it.
  79     ``all`` or ``busy`` or ``noans`` or ``outofreach``
  80         condition when apply divert
  81     ``all`` or ``voice`` or ``fax`` or ``data``
  82         call type when apply divert
  83     number
  84         number where to divert
  85     timeout
  86         timeout when the diversion will happen
  87
  88 .. option:: getussd code
  89
  90     Retrieves USSD information - dials a service number and reads response.
  91
  92 .. option:: holdcall id
  93
  94     Holds call.
  95
  96 .. option:: maketerminatedcall number length [show|hide]
  97
  98     Make voice call from SIM card line set in phone which will
  99     be terminated after ``length`` seconds.
 100
 101 .. option:: senddtmf sequence
 102
 103     Plays DTMF sequence. In some phones available only during calls
 104
 105 .. option:: splitcall id
 106
 107     Splits call.
 108
 109 .. option:: switchcall [id]
 110
 111     Switches call.
 112
 113 .. option:: transfercall [id]
 114
 115     Transfers call.
 116
 117 .. option:: unholdcall id
 118
 119     Unholds call.
 120
 121 .. _gammu-sms:
 122
 123 SMS and EMS commands
 124 --------------------
 125
 126 Sending messages might look a bit complicated on first attempt to use.
 127 But be patient, the command line has been written in order to allow
 128 almost every usage. See EXAMPLE section for some hints on usage.
 129
 130 There is also an option to use :ref:`gammu-smsd` when you want to send or
 131 receive more messages and process them automatically.
 132
 133 Introduction to SMS formats
 134 ___________________________
 135
 136 Gammu has support for many SMS formats like:
 137
 138 Nokia Smart Messaging
 139     used for monochromatic picture images, downloadable profiles, monochromatic operator logos, monochromatic caller logos and monophonic ringtones
 140 Linked SMS
 141     both with 8 and 16-bit identification numbers in headers
 142 EMS
 143     this is SMS format used for saving monochromatic images, monophonic ringtones, animations, text formatting and others
 144 MMS notifications
 145     contains links where phone should download MMS
 146 Alcatel logo messages
 147     proprietary format for logos
 148
 149
 150 You need to ensure that the target phone supports message type you want to
 151 send. Otherwise the phone will not be able to display it or will even crash,
 152 because firmware of phone did not expect this possibility.
 153
 154 Encoding chars in SMS text
 155 __________________________
 156
 157 Text in SMS can be coded using two ways:
 158
 159 GSM Default Alphabet
 160 ~~~~~~~~~~~~~~~~~~~~
 161
 162 With `GSM Default Alphabet` you can fit at most 160 chars into single SMS
 163 (Gammu doesn't support compressing such texts according to GSM standards, but
 164 it isn't big limit, because there are no phones supporting them), but they're
 165 from limited set:
 166
 167 * all Latin small and large
 168 * all digits
 169 * some Greek
 170 * some other national
 171 * some symbols like  @ ! " # & / ( ) % * + = - , . : ; < > ?
 172 * few others
 173
 174 Unicode
 175 ~~~~~~~
 176
 177 With `Unicode` single SMS can contain at most 70 chars, but these can be
 178 any chars including all national and special ones.
 179
 180 .. warning::
 181
 182    Please note, that some older phones might have problems displaying such
 183    message.
 184
 185 Conversion
 186 ~~~~~~~~~~
 187
 188 Gammu tries to do the best to handle non ASCII characters in your message.
 189 Everything is internally handled in Unicode (the input is converted depending
 190 on your locales configuration) and in case message uses Unicode the text will
 191 be given as such to the message.
 192
 193 Should the message be sent in GSM Default Alphabet, Gammu will try to convert
 194 all characters to keep message readable. Gammu does support multi byte
 195 encoding for some characters in GSM Default Alphabet (it is needed for ``^`` ``{`` ``}``
 196 ``\`` ``[`` ``]`` ``~`` ``|``). The characters which are not present in GSM Default Alphabet
 197 are transliterated to closest ASCII equivalent (accents are removed).
 198 Remaining not known characters are replaced by question mark.
 199
 200 SMS commands
 201 ____________
 202
 203 .. option:: addsmsfolder name
 204
 205 .. option:: deleteallsms folder
 206
 207     Delete all SMS from specified SMS folder.
 208
 209 .. option:: deletesms folder start [stop]
 210
 211     Delete SMS from phone. See description for :option:`gammu getsms` for info about
 212     sms folders naming convention.
 213
 214     Locations are numerated from 1.
 215
 216 .. option:: displaysms ... (options like in sendsms)
 217
 218     Displays PDU data of encoded SMS messages. It accepts same parameters and
 219     behaves same like sendsms.
 220
 221 .. option:: getallsms -pbk
 222
 223     Get all SMS from phone. In some phones you will have also SMS templates
 224     and info about locations used to save Picture Images. With each sms you
 225     will see location. If you want to get such sms from phone alone, use
 226     :option:`gammu getsms`.
 227
 228 .. option:: geteachsms -pbk
 229
 230     Similiary to :option:`gammu getallsms`. Difference is, that
 231     links all concatenated sms
 232
 233 .. option:: getsms folder start [stop]
 234
 235     Get SMS.
 236
 237     Locations are numerated from 1.
 238
 239     Folder 0 means that sms is being read from "flat" memory (all sms from all
 240     folders have unique numbers). It's sometimes emulated by Gammu. You
 241     can use it with all phones.
 242
 243     Other folders like 1, 2, etc. match folders in phone such as Inbox, Outbox, etc.
 244     and each sms has unique number in his folder. Name of folders can
 245     depend on your phone (the most often 1="Inbox", 2="Outbox", etc.).
 246     This method is not supported by all phones (for example, not supported
 247     by Nokia 3310, 5110, 6110). If work with your phone, use
 248     :option:`gammu getsmsfolders` to get folders list.
 249
 250 .. option:: getsmsc [start [stop]]
 251
 252     Get SMSC settings from SIM card.
 253
 254     Locations are numerated from 1.
 255
 256 .. option:: getsmsfolders
 257
 258     Get names for SMS folders in phone
 259
 260 .. option:: savesms TYPE [type parameters] [type options] [-folder id] [-unread] [-read] [-unsent] [-sent] [-sender number] [-smsname name] [-smscset number] [-smscnumber number] [-reply] [-maxsms num]
 261
 262    Saves SMS to phone, see bellow for ``TYPE`` options.
 263
 264     .. option:: -smscset number
 265
 266         SMSC number will be taken from phone stored SMSC configuration ``number``.
 267
 268         Default: 1
 269
 270     .. option:: -smscnumber number
 271
 272         SMSC number
 273
 274     .. option:: -reply
 275
 276         reply SMSC is set
 277
 278     .. option:: -folder number
 279
 280         save to specified folder.
 281
 282         Folders are numerated from 1.
 283
 284         The most often folder 1 = "Inbox", 2 = "Outbox",etc. Use :option:`gammu getsmsfolders` to get folder list.
 285
 286     .. option:: -unread
 287
 288         makes message unread. In some phones (like 6210) you won't see
 289         unread sms envelope after saving such sms. In some phones with internal
 290         SMS memory (like 6210) after using it with folder 1 SIM SMS memory will be used
 291
 292     .. option:: -read
 293
 294         makes message read. In some phones with internal
 295         SMS memory (like 6210) after using it with folder 1 SIM SMS memory will be used
 296
 297     .. option:: -unsent
 298
 299         makes message unsent
 300
 301     .. option:: -sent
 302
 303         makes message sent
 304
 305     .. option:: -smsname name
 306
 307         set message name
 308
 309     .. option:: -sender number
 310
 311         set sender number (default: ``Gammu``)
 312
 313     .. option:: -maxsms num
 314
 315         Limit maximal number of messages which will be
 316         created. If there are more messages, Gammu will terminate with failure.
 317
 318     Types of messages:
 319
 320     .. option:: ANIMATION frames file1 file2...
 321
 322         Save an animation as a SMS. You need to give
 323         number of frames and picture for each frame. Each picture can be in any
 324         picture format which Gammu supports (B/W bmp, gif, wbmp, nol, nlm...).
 325
 326     .. option:: BOOKMARK file location
 327
 328         Read WAP bookmark from file created by :option:`gammu backup` command and saves in
 329         Nokia format as SMS
 330
 331
 332     .. option:: CALENDAR file location
 333
 334         Read calendar note from file created by :option:`gammu backup` command and saves in
 335         VCALENDAR 1.0 format as SMS. The location identifies position of calendar item
 336         to be read in backup file (usually 1, but can be useful in case the backup contains
 337         more items).
 338
 339
 340     .. option:: CALLER file
 341
 342         Save caller logo as sms in Nokia (Smart Messaging)
 343         format - size 72x14, two colors.
 344
 345         .. warning::
 346
 347            Please note, that it isn't designed for colour logos available for
 348            example in DCT4/TIKU - you need to put bitmap file there inside
 349            phone using filesystem commands.
 350
 351
 352
 353     .. option:: EMS [-unicode] [-16bit] [-format lcrasbiut] [-text text] [-unicodefiletext file] [-defsound ID] [-defanimation ID] [-tone10 file] [-tone10long file] [-tone12 file] [-tone12long file] [-toneSE file] [-toneSElong file] [-fixedbitmap file] [-variablebitmap file] [-variablebitmaplong file] [-animation frames file1 ...] [-protected number]
 354
 355         Saves EMS sequence. All format specific parameters (like :option:`-defsound`) can be used few times.
 356
 357         .. option:: -text
 358
 359             adds text
 360
 361         .. option:: -unicodefiletext
 362
 363             adds text from Unicode file
 364
 365         .. option:: -defanimation
 366
 367             adds default animation with ID specified by user. ID for different phones are different.
 368
 369         .. option:: -animation
 370
 371             adds "frames" frames read from file1, file2, etc.
 372
 373         .. option:: -defsound
 374
 375             adds default sound with ID specified by user. ID for different phones are different.
 376
 377         .. option:: -tone10
 378
 379             adds IMelody version 1.0 read from RTTL or other compatible file
 380
 381         .. option:: -tone10long
 382
 383             IMelody version 1.0 saved in one of few SMS with UPI. Phones
 384             compatible with UPI (like Sony-Ericsson phones) will read such
 385             ringtone as one
 386
 387         .. option:: -tone12
 388
 389             adds IMelody version 1.2 read from RTTL or other compatible file
 390
 391         .. option:: -tone12long
 392
 393             IMelody version 1.2 saved in one of few SMS with UPI. Phones
 394             compatible with UPI (like Sony-Ericsson phones) will read such
 395             ringtone as one
 396
 397         .. option:: -toneSE
 398
 399             adds IMelody in "short" form supported by Sony-Ericsson phones
 400
 401         .. option:: -toneSElong
 402
 403             add Sony-Ericsson IMelody saved in one or few SMS with UPI
 404
 405         .. option:: -variablebitmap
 406
 407             bitmap in any size saved in one SMS
 408
 409         .. option:: -variablebitmaplong
 410
 411             bitmap with maximal size 96x128 saved in one or few sms
 412
 413         .. option:: -fixedbitmap
 414
 415             bitmap 16x16 or 32x32
 416
 417         .. option:: -protected
 418
 419             all ringtones and bitmaps after this parameter (excluding default
 420             ringtones and logos) will be "protected" (in phones compatible with
 421             ODI like SonyEricsson products it won't be possible to forward them
 422             from phone menu)
 423
 424         .. option:: -16bit
 425
 426             Gammu uses SMS headers with 16-bit numbers for saving linking info
 427             in SMS (it means less chars available for user in each SMS)
 428
 429         .. option:: -format lcrasbiut
 430
 431             last text will be formatted. You can use combinations of chars:
 432
 433             =========  ==================
 434             Character  Formating
 435             =========  ==================
 436             ``l``      left aligned
 437             ``c``      centered
 438             ``r``      right aligned
 439             ``a``      large font
 440             ``s``      small font
 441             ``b``      bold font
 442             ``i``      italic font
 443             ``u``      underlined font
 444             ``t``      strikethrough font
 445             =========  ==================
 446
 447
 448     .. option:: MMSINDICATOR URL Title Sender
 449
 450         Creates a MMS indication SMS. It contains URL where the actual MMS
 451         payload is stored which needs to be SMIL encoded. The phone usually
 452         downloads the MMS data using special APN, which does not count to
 453         transmitted data, however there might be limitations which URLs can
 454         be accessed.
 455
 456     .. option:: MMSSETTINGS file location
 457
 458         Saves a message with MMS configuration. The
 459         configuration will be read from Gammu backup file from given location.
 460
 461     .. option:: OPERATOR file  [-netcode netcode] [-biglogo]
 462
 463         Save operator logo as sms in Nokia (Smart Messaging) format - size
 464         72x14 in two colors.
 465
 466         .. option:: -biglogo
 467
 468             Use 78x21 formatted logo instead of standard 72x14.
 469
 470         .. note::
 471
 472            This isn't designed for colour logos available for example in newer
 473            phones - you need to put bitmap file there inside phone using
 474            filesystem commands.
 475
 476
 477     .. option:: PICTURE file  [-text text] [-unicode] [-alcatelbmmi]
 478
 479         Read bitmap from 2 colors file (bmp, nlm, nsl, ngg, nol, wbmp, etc.), format
 480         into bitmap in Smart Messaging (72x28, 2 colors, called often Picture Image
 481         and saved with text) or Alcatel format and send/save over SMS.
 482
 483
 484     .. option:: PROFILE  [-name name] [-bitmap bitmap] [-ringtone ringtone]
 485
 486         Read ringtone (RTTL) format, bitmap (Picture Image size) and name, format into
 487         Smart Messaging profile and send/save as SMS.
 488
 489         .. warning::
 490
 491            Please note, that this format is abandoned by Nokia and supported
 492            by some (older) devices only like Nokia 3310.
 493
 494
 495     .. option:: RINGTONE file  [-long] [-scale]
 496
 497         Read RTTL ringtone from file and save as SMS
 498         into SIM/phone memory. Ringtone is saved in Nokia (Smart Messaging) format.
 499
 500         .. option:: -long
 501
 502             ringtone is saved using Profile style. It can be longer (and saved
 503             in 2 SMS), but decoded only by newer phones (like 33xx)
 504
 505         .. option:: -scale
 506
 507             ringtone will have Scale info for each note. It will allow one to edit
 508             it correctly later in phone composer (for example, in 33xx)
 509
 510
 511     .. option:: SMSTEMPLATE  [-unicode] [-text text] [-unicodefiletext file] [-defsound ID] [-defanimation ID] [-tone10 file] [-tone10long file] [-tone12 file] [-tone12long file] [-toneSE file] [-toneSElong file] [-variablebitmap file] [-variablebitmaplong file] [-animation frames file1 ...]
 512
 513         Saves a SMS template (for Alcatel phones).
 514
 515
 516     .. option:: TEXT  [-inputunicode] [-16bit] [-flash] [-len len] [-autolen len] [-unicode] [-enablevoice] [-disablevoice] [-enablefax] [-disablefax] [-enableemail] [-disableemail] [-voidsms] [-replacemessages ID] [-replacefile file] [-text msgtext] [-textutf8 msgtext]
 517
 518         Take text from stdin (or commandline if -text
 519         specified) and save as text SMS into SIM/phone memory.
 520
 521         .. option:: -flash
 522
 523             Class 0 SMS (should be displayed after receiving on recipients' phone display after receiving without entering Inbox)
 524
 525         .. option:: -len len
 526
 527             specify, how many chars will be read. When use this option and text
 528             will be longer than 1 SMS, will be split into more linked SMS
 529
 530         .. option:: -autolen len
 531
 532             specify, how many chars will be read. When use this option and text
 533             will be longer than 1 SMS, will be split into more linked
 534             SMS.Coding type (SMS default alphabet/Unicode) is set according to
 535             input text
 536
 537         .. option:: -enablevoice
 538
 539             sms will set voice mail indicator. Text will be cut to 1 sms.
 540
 541         .. option:: -disablevoice
 542
 543             sms will not set voice mail indicator. Text will be cut to 1 sms.
 544
 545         .. option:: -enablefax
 546
 547             sms will set fax indicator. Text will be cut to 1 sms.
 548
 549         .. option:: -disablefax
 550
 551             sms will not set fax indicator. Text will be cut to 1 sms.
 552
 553         .. option:: -enableemail
 554
 555             sms will set email indicator. Text will be cut to 1 sms.
 556
 557         .. option:: -disableemail
 558
 559             sms will not set email indicator. Text will be cut to 1 sms.
 560
 561         .. option:: -voidsms
 562
 563             many phones after receiving it won't display anything, only beep,
 564             vibrate or turn on light. Text will be cut to 1 sms.
 565
 566         .. option:: -unicode
 567
 568             SMS will be saved in Unicode format
 569
 570             .. note::
 571
 572                 The ``~`` char in SMS text and :option:`-unicode` option
 573                 (Unicode coding required) can cause text of SMS after ``~``
 574                 char  blink in some phones (like Nokia 33xx).
 575
 576         .. option:: -inputunicode
 577
 578             input text is in Unicode.
 579
 580             .. note::
 581
 582                 You can create Unicode file using WordPad in Windows (during
 583                 saving select "Unicode Text Document" format). In Unix can use
 584                 for example YUdit or vim.
 585
 586         .. option:: -text
 587
 588             get text from command line instead of stdin.
 589
 590         .. option:: -textutf8
 591
 592             get text in UTF-8 from command line instead of stdin.
 593
 594             .. note::
 595
 596                 Gammu detects your locales and uses by default encoding based
 597                 on this. Use this option only when you know the input will be
 598                 in UTF-8 in all cases.
 599
 600         .. option:: -16bit
 601
 602             Gammu uses SMS headers with 16-bit numbers for saving linking info
 603             in SMS (it means less chars available for user in each SMS)
 604
 605         .. option:: -replacemessages ID
 606
 607             ``ID`` can be 1..7. When you will use option and send more single
 608             SMS to one recipient with the same ID, each another SMS will
 609             replace each previous with the same ID
 610
 611         .. option:: -replacefile file
 612
 613             File with replacement table in unicode (UCS-2), preferably with
 614             byte order mark (BOM). It contains pairs of chars, first one is to
 615             replace, second is replacement one. The replacement is done after
 616             reading text for the message.
 617
 618             For example replacement ``1`` (0x0061) with ``a`` (0x0031) would
 619             be done by file with following content (hex dump, first two bytes
 620             is BOM)::
 621
 622                 ff fe 61 00 31 00
 623
 624     .. option:: TODO file location
 625
 626         Saves a message with a todo entry. The content will
 627         be read from any backup format which Gammu supports and from given location.
 628
 629     .. option:: VCARD10|VCARD21 file SM|ME location [-nokia]
 630
 631         Read phonebook entry from file created by :option:`gammu backup`
 632         command and saves in VCARD 1.0 (only name and default number) or VCARD
 633         2.1 (all entry details with all numbers, text and name) format as SMS.
 634         The location identifies position of contact item to be read in backup
 635         file (usually 1, but can be useful in case the backup contains more
 636         items).
 637
 638
 639     .. option:: WAPINDICATOR URL Title
 640
 641         Saves a SMS with a WAP indication for given
 642         URL and title.
 643
 644
 645     .. option:: WAPSETTINGS file location DATA|GPRS
 646
 647         Read WAP settings from file created by :option:`gammu backup` command
 648         and saves in Nokia format as SMS
 649
 650
 651 .. option:: sendsms TYPE destination [type parameters] [type options] [-smscset number] [-smscnumber number] [-reply] [-report] [-validity HOUR|6HOURS|DAY|3DAYS|WEEK|MAX] [-save [-folder number]]
 652
 653     Sends a message to a ``destination`` number, most parameters are same as for :option:`gammu savesms`.
 654
 655     .. option:: -save
 656
 657         will also save message which is being sent
 658
 659     .. option:: -report
 660
 661         request delivery report for message
 662
 663     .. option:: -validity HOUR|6HOURS|DAY|3DAYS|WEEK|MAX
 664
 665         sets how long will be the
 666         message valid (SMSC will the discard the message after this time if it could
 667         not deliver it).
 668
 669 .. option:: setsmsc location number
 670
 671     Set SMSC settings on SIM card. This keeps all SMSC configuration
 672     intact, it just changes the SMSC number.
 673
 674     Locations are numerated from 1.
 675
 676
 677 Memory (phonebooks and calls) commands
 678 --------------------------------------
 679
 680 .. _memory types:
 681
 682 Memory types
 683 ____________
 684
 685 Gammu recognizes following memory types:
 686
 687 ``DC``
 688      Dialled calls
 689 ``MC``
 690      Missed calls
 691 ``RC``
 692      Received calls
 693 ``ON``
 694      Own numbers
 695 ``VM``
 696      voice mailbox
 697 ``SM``
 698      SIM phonebook
 699 ``ME``
 700      phone internal phonebook
 701 ``FD``
 702      fixed dialling
 703 ``SL``
 704      sent SMS log
 705
 706
 707 Memory commands
 708 _______________
 709
 710 .. option:: deleteallmemory DC|MC|RC|ON|VM|SM|ME|MT|FD|SL
 711
 712     Deletes all entries from specified memory type.
 713
 714     For memory types description see :ref:`memory types`.
 715
 716 .. option:: deletememory DC|MC|RC|ON|VM|SM|ME|MT|FD|SL start [stop]
 717
 718     Deletes entries in specified range from specified memory type.
 719
 720     For memory types description see :ref:`memory types`.
 721
 722 .. option:: getallmemory DC|MC|RC|ON|VM|SM|ME|MT|FD|SL
 723
 724     Get all memory locations from phone.
 725
 726     For memory types description see :ref:`memory types`.
 727
 728 .. option:: getmemory DC|MC|RC|ON|VM|SM|ME|MT|FD|SL start [stop [-nonempty]]
 729
 730     Get memory location from phone.
 731
 732     For memory types description see :ref:`memory types`.
 733
 734     Locations are numerated from 1.
 735
 736 .. option:: getspeeddial start [stop]
 737
 738     Gets speed dial choices.
 739
 740 .. option:: searchmemory text
 741
 742     Scans all memory entries for given text. It performs
 743     case insensitive substring lookup. You can interrupt searching by pressing
 744     :kbd:`Ctrl+C`.
 745
 746 Filesystem commands
 747 -------------------
 748
 749 Gammu allows one to access phones using native protocol (Nokias) or OBEX. Your
 750 phone can also support usb storage, which is handled on the operating system
 751 level and Gammu does not use that.
 752
 753 .. option:: addfile folderID name [-type JAR|BMP|PNG|GIF|JPG|MIDI|WBMP|AMR|3GP|NRT] [-readonly] [-protected] [-system] [-hidden] [-newtime]
 754
 755     Add file with specified name to folder with specified folder ID.
 756
 757     .. option:: -type
 758
 759        File type was required for filesystem 1 in Nokia phones (current filesystem 2 doesn't need this).
 760
 761     .. option:: -readonly
 762
 763        Sets the read only attribute.
 764
 765     .. option:: -protected
 766
 767        Sets the protected attribute (file can't be for example forwarded
 768        from phone menu).
 769
 770     .. option:: -system
 771
 772        Sets the system attribute.
 773
 774     .. option:: -hidden
 775
 776        Sets the hidden attribute (file is hidden from phone menu).
 777
 778     .. option:: -newtime
 779
 780         After using it date/time of file modification will be set to moment of uploading.
 781
 782 .. option:: addfolder parentfolderID name
 783
 784     Create a folder in phone with specified name in a
 785     folder with specified folder ID.
 786
 787 .. option:: deletefiles fileID
 788
 789     Delete files with given IDs.
 790
 791 .. option:: deletefolder name
 792
 793     Delete folder with given ID.
 794
 795 .. option:: getfilefolder fileID, fileID, ...
 796
 797     Retrieve files or all files from folder with given IDs from a phone filesytem.
 798
 799 .. option:: getfiles fileID, fileID, ...
 800
 801     Retrieve files with given IDs from a phone filesytem.
 802
 803 .. option:: getfilesystem [-flatall|-flat]
 804
 805     Display info about all folders and files in phone memory/memory card. By default there is tree displayed, you can change it:
 806
 807     .. option:: -flatall
 808
 809         there are displayed full file/folder details like ID (first parameter in line)
 810
 811     .. option:: -flat
 812
 813     .. note:: In some phones (like N6230) content of some folders (with more files) can be cut (only part of files will be displayed) for example on infrared connection. This is not Gammu issue, but phone firmware problem.
 814
 815 .. option:: getfilesystemstatus
 816
 817     Display info filesystem status - number of
 818     bytes available, used or used by some specific content.
 819
 820 .. option:: getfolderlisting folderID
 821
 822     Display files and folders available in folder with given folder ID. You can get ID's using getfilesystem -flatall.
 823
 824     .. warning::
 825
 826        Please note, that in some phones (like N6230) content of some folders
 827        (with more files) can be cut (only part of files will be displayed) for
 828        example on infrared connection. This is not Gammu issue, but phone
 829        firmware problem.
 830
 831 .. option:: getrootfolders
 832
 833     Display info about drives available in phone/memory card.
 834
 835 .. option:: sendfile name
 836
 837     Sends file to a phone. It's up to phone to decide where
 838     to store this file and how to handle it (for example when you send vCard or
 839     vCalendar, most of phones will offer you to import it.
 840
 841 .. option:: setfileattrib folderID [-system] [-readonly] [-hidden] [-protected]
 842
 843
 844 Logo and pictures commands
 845 --------------------------
 846
 847 These options are mainly (there are few exceptions) for monochromatic logos and
 848 images available in older phones. Recognized file formats: xpm (only saving),
 849 2-colors bmp, nlm, nsl, ngg, nol, wbmp, gif (for Samsung).
 850
 851 In new models all bitmaps are saved in filesystem and should go into filesystem section
 852
 853 .. option:: copybitmap inputfile [outputfile [OPERATOR|PICTURE|STARTUP|CALLER]]
 854
 855     Allow one to convert logos files to another. When give ONLY inputfile, output will
 856     be written to stdout using ASCII art. When give output file and format, in
 857     some file formats (like NLM) will be set indicator informing about logo type
 858     to given.
 859
 860 .. option:: getbitmap TYPE [type options]
 861
 862     Reads bitmap from phone, following types are supported:
 863
 864     .. option:: CALLER location [file]
 865
 866         Get caller group logo from phone. Locations 1-5.
 867
 868     .. option:: DEALER
 869
 870         In some models it's possible to save dealer welcome note - text displayed
 871         during enabling phone, which can't be edited from phone menu.  Here you can
 872         get it.
 873
 874     .. option:: OPERATOR [file]
 875
 876         Get operator logo (picture displayed instead of operator name) from phone.
 877
 878     .. option:: PICTURE location [file]
 879
 880         Get Picture Image from phone.
 881
 882     .. option:: STARTUP [file]
 883
 884         Get static startup logo from phone. Allow one to save it in file.
 885
 886     .. option:: TEXT
 887
 888         Get startup text from phone.
 889
 890 .. option:: setbitmap TYPE [type options]
 891
 892     Sets bitmap in phone, following types are supported:
 893
 894     .. option:: CALLER location [file]
 895
 896         Set caller logo.
 897
 898     .. option:: COLOUROPERATOR [fileID [netcode]]
 899
 900         Sets color operator logo in phone.
 901
 902     .. option:: COLOURSTARTUP [fileID]
 903
 904     .. option:: DEALER text
 905
 906         Sets welcome message configured by dealer, which usually can not be changed in phone menus.
 907
 908     .. option:: OPERATOR [file [netcode]]
 909
 910         Set operator logo in phone. When won't give file and netcode, operator logo
 911         will be removed from phone. When will give only filename, operator logo will
 912         be displayed for your current GSM operator. When you give additionally network
 913         code, it will be displayed for this operator.
 914
 915     .. option:: PICTURE file location [text]
 916
 917         Sets picture image in phone.
 918
 919     .. option:: STARTUP file|1|2|3
 920
 921         Set startup logo in phone. It can be static (then you will have to give file
 922         name) or one of predefined animated (only some phones like Nokia 3310 or 3330
 923         supports it, use location 1, 2 or 3 for these).
 924
 925     .. option:: TEXT text
 926
 927         Sets startup text in phone.
 928
 929     .. option:: WALLPAPER fileID
 930
 931         Sets wallpaper in phone.
 932
 933 Ringtones commands
 934 ------------------
 935
 936 Ringtones are mostly supported only for older phones. For recent phones you
 937 usually just upload them to some folder in phone filesystem.
 938
 939 There are recognized various file formats by options described below: rttl,
 940 binary format created for Gammu, mid (saving), re (reading), ott, communicator,
 941 ringtones format found in fkn.pl, wav (saving), ime/imy (saving), rng, mmf (for
 942 Samsung).
 943
 944
 945 .. option:: copyringtone source destination [RTTL|BINARY]
 946
 947     Copy source ringtone to destination.
 948
 949 .. option:: getphoneringtone location [file]
 950
 951     Get one of "default" ringtones and saves into file
 952
 953 .. option:: getringtone location [file]
 954
 955     Get ringtone from phone in RTTL or BINARY format.
 956
 957     Locations are numerated from 1.
 958
 959 .. option:: getringtoneslist
 960
 961 .. option:: playringtone file
 962
 963     Play aproximation of ringtone over phone buzzer. File can be in RTTL or BINARY (Nokia DCT3) format.
 964
 965 .. option:: playsavedringtone number
 966
 967     Play one of built-in ringtones. This option is available for DCT4 phones.
 968     For getting ringtones list use :option:`gammu getringtoneslist`.
 969
 970 .. option:: setringtone file [-location location] [-scale] [-name name]
 971
 972     Set ringtone in phone. When don't give location, it will be written
 973     "with preview" (in phones supporting this feature like 61xx or 6210).
 974
 975     .. option:: -scale
 976
 977         Scale information will be added to each note of RTTL ringtone. It will
 978         avoid scale problems available during editing ringtone in composer
 979         from phone menu (for example, in Nokia 33xx).
 980
 981     .. note::
 982
 983         When use ``~`` char in ringtone name, in some phones (like 33xx) name
 984         will blink later in phone menus.
 985
 986
 987 Calendar notes commands
 988 -----------------------
 989
 990 In Nokia 3310, 3315 and 3330 these are named "Reminders" and have some limitations (depending on phone firmware version).
 991
 992 .. option:: deletecalendar start [stop]
 993
 994     Deletes selected calendar entries in phone.
 995
 996 .. option:: getallcalendar
 997
 998     Retrieves all calendar entries from phone.
 999
1000 .. option:: getcalendar start [stop]
1001
1002     Retrieves selected calendar entries from phone.
1003
1004
1005 To do list commands
1006 -------------------
1007
1008 .. option:: deletetodo start [stop]
1009
1010     Deletes selected todo entries in phone.
1011
1012 .. option:: getalltodo
1013
1014     Retrieves all todo entries from phone.
1015
1016 .. option:: gettodo start [stop]
1017
1018     Retrieves selected todo entries from phone.
1019
1020 Notes commands
1021 --------------
1022
1023 .. option:: getallnotes
1024
1025     Reads all notes from the phone.
1026
1027     .. note::
1028
1029         Not all phones supports this function, especially most Sony Ericsson
1030         phones even if they have notes inside phone.
1031
1032
1033 Date, time and alarm commands
1034 -----------------------------
1035
1036 .. option:: getalarm [start]
1037
1038     Get alarm from phone, if no location is specified,
1039     1 is used.
1040
1041 .. option:: getdatetime
1042
1043     Get date and time from phone
1044
1045 .. option:: setalarm hour minute
1046
1047     Sets repeating alarm in phone on selected time.
1048
1049 .. option:: setdatetime [HH:MM[:SS]] [YYYY/MM/DD]
1050
1051     Set date and time in phone to date and time set in computer. Please
1052     note, that this option doesn't show clock on phone screen. It only set
1053     date and time.
1054
1055     .. note::
1056
1057        You can make such synchronization each time, when will connect your
1058        phone and use Gammu. See :config:option:`SynchronizeTime` in :ref:`gammurc` for details.
1059
1060
1061 Categories commands
1062 -------------------
1063
1064 .. note::
1065
1066     Categories are supported only on few phones (Alcatel).
1067
1068 .. option:: addcategory TODO|PHONEBOOK text
1069
1070 .. option:: getallcategory TODO|PHONEBOOK
1071
1072 .. option:: getcategory TODO|PHONEBOOK start [stop]
1073
1074 .. option:: listmemorycategory text|number
1075
1076 .. option:: listtodocategory text|number
1077
1078
1079 Backing up and restoring commands
1080 ---------------------------------
1081
1082 .. option:: addnew file [-yes] [-memory ME|SM|..]
1083
1084     Adds data written in file created using :option:`gammu backup` command. All things
1085     backed up :option:`gammu backup` can be restored (when made backup to Gammu text
1086     file).
1087
1088     Please note that this adds all content of backup file to phone and
1089     does not care about current data in the phone (no duplicates are
1090     detected).
1091
1092     Use -yes parameter to answer yes to all questions (you want to automatically
1093     restore all data).
1094
1095     Use -memory parameter to force usage of defined memory type for storing entries
1096     regardless what backu format says.
1097
1098 .. option:: addsms folder file [-yes]
1099
1100     Adds SMSes from file (format like :option:`gammu backupsms` uses) to
1101     selected folder in phone.
1102
1103 .. option:: backup file [-yes]
1104
1105     Backup your phone to file. It's possible to backup (depends on phone and backup format):
1106
1107     * phonebook from SIM and phone memory
1108     * calendar notes
1109     * SMSC settings
1110     * operator logo
1111     * startup (static) logo or startup text
1112     * WAP bookmarks
1113     * WAP settings
1114     * caller logos and groups
1115     * user ringtones
1116
1117     There are various backup formats supported and the backup format is guessed
1118     based on file extension:
1119
1120     * ``.lmb`` - Nokia backup, supports contacts, caller logos and startup logo.
1121     * ``.vcs`` - vCalendar, supports calendar and todo.
1122     * ``.vcf`` - vCard, supports contacts.
1123     * ``.ldif`` - LDAP import, supports contacts.
1124     * ``.ics`` - iCalendar, supports calendar and todo.
1125     * Any other extension is Gammu backup file and it supports all data mentioned above, see :ref:`gammu-backup` for more details.
1126
1127     By default this command is interactive and asks which items tou want to backup.
1128
1129     Use -yes for answering yes to all questions.
1130
1131 .. option:: backupsms file [-yes|-all]
1132
1133     Stores all SMSes from phone to file into :ref:`gammu-smsbackup`.
1134
1135     By default this command is interactive and asks which folders you want
1136     to backup and whether you want to remove messages from phone afterwards.
1137
1138     Use -yes for answering yes to all questions (backup all messages and
1139     delete them from phone), or -all to just backup all folders while keeping
1140     messages in phone.
1141
1142 .. option:: restore file [-yes]
1143
1144     .. warning::
1145
1146         Please note that restoring deletes all current content in phone. If you
1147         want only to add entries to phone, use :option:`gammu addnew`.
1148
1149     Restore settings written in file created using :option:`gammu backup` command.
1150
1151
1152     In some phones restoring calendar notes will not show error, but won't
1153     be done, when phone doesn't have set clock inside.
1154
1155 .. option:: restoresms file [-yes]
1156
1157     .. warning::
1158
1159        Please note that this overwrites existing messages in phone (if it supports it).
1160
1161     Restores SMSes from file (format like :option:`gammu backupsms` uses) to
1162     selected folder in phone.
1163
1164 .. option:: savefile TYPE [type options]
1165
1166     Converts between various file formats supported by Gammu, following types
1167     are supported:
1168
1169     .. option:: BOOKMARK target.url file location
1170
1171         Converts backup format supported by
1172         Gammu to vBookmark file.
1173
1174     .. option:: CALENDAR target.vcs file location
1175
1176         Allows one to convert between various backup formats which gammu
1177         supports for calendar events. The file type is guessed (for input file
1178         guess is based on extension and file content, for output solely on
1179         extension).
1180
1181     .. option:: TODO target.vcs file location
1182
1183         Allows one to convert between various backup formats which gammu
1184         supports for todo events. The file type is guessed (for input file
1185         guess is based on extension and file content, for output solely on
1186         extension).
1187
1188     .. option:: VCARD10|VCARD21 target.vcf file SM|ME location
1189
1190         Allows one to convert between various backup formats which gammu
1191         supports for phonebook events. The file type is guessed (for input file
1192         guess is based on extension and file content, for output solely on
1193         extension).
1194
1195     .. seealso:: :option:`gammu convertbackup`
1196
1197 .. option:: convertbackup source.file output.file
1198
1199     .. versionadded:: 1.28.94
1200
1201     Converts backup between formats supported by Gammu. Unlike
1202     :option:`gammu savefile`, this does not give you any options what to
1203     convert, it simply takes converts all what can be saved into output file.
1204
1205     .. seealso:: :option:`gammu savefile`
1206
1207
1208 Nokia specific commands
1209 -----------------------
1210
1211 .. option:: nokiaaddfile TYPE [type options]
1212
1213     Uploads file to phone to specific location for the type:
1214
1215     .. option:: APPLICATION|GAME file [-readonly] [-overwrite] [-overwriteall]
1216
1217         Install the ``*.jar/*.jad`` file pair of a midlet in the application or
1218         game menu of the phone. You need to specify filename without the jar/jad
1219         suffix, both will be added automatically.
1220
1221         .. option:: -overwrite
1222
1223             Delete the application's .jad and .jar files before installing, but
1224             doesn't delete the application data.
1225
1226         .. option:: -overwriteall
1227
1228             Delete the application (same as :option:`-overwrite`) and all it's
1229             data.
1230
1231         You can use :ref:`jadmaker` to generate a .jad file from a .jar file.
1232
1233     .. option:: GALLERY|GALLERY2|CAMERA|TONES|TONES2|RECORDS|VIDEO|PLAYLIST|MEMORYCARD file [-name name] [-protected] [-readonly] [-system] [-hidden] [-newtime]
1234
1235 .. option:: nokiaaddplaylists
1236
1237     Goes through phone memory and generated playlist for all music files found.
1238
1239     To manually manage playlists:
1240
1241     .. code-block:: sh
1242
1243         gammu addfile a:\\predefplaylist filename.m3u
1244
1245     Will add playlist filename.m3u
1246
1247     .. code-block:: sh
1248
1249         gammu getfilesystem
1250
1251     Will get list of all files (including names of files with playlists)
1252
1253     .. code-block:: sh
1254
1255         gammu deletefiles a:\\predefplaylist\\filename.m3u
1256
1257     Will delete playlist filename.m3u
1258
1259     Format of m3u playlist is easy (standard mp3 playlist):
1260
1261     First line is ``#EXTM3U``, next lines contain  names of files (``b:\file1.mp3``,
1262     ``b:\folder1\file2.mp3``, etc.). File needs t have ``\r\n`` terminated lines. So
1263     just run :program:`unix2dos` on the resulting file before uploading it your your phone.
1264
1265
1266 .. option:: nokiacomposer file
1267
1268     Show, how to enter RTTL ringtone in composer existing in many Nokia phones
1269     (and how should it look like).
1270
1271 .. option:: nokiadebug filename [[v11-22] [,v33-44]...]
1272
1273 .. option:: nokiadisplayoutput
1274
1275 .. option:: nokiadisplaytest number
1276
1277 .. option:: nokiagetadc
1278
1279 .. option:: nokiagetoperatorname
1280
1281     6110.c phones have place for name for one GSM network (of course, with flashing it's
1282     possible to change all names, but Gammu is not flasher ;-)). You can get this
1283     name using this option.
1284
1285 .. option:: nokiagetpbkfeatures memorytype
1286
1287 .. option:: nokiagett9
1288
1289     This option should display T9 dictionary content from
1290     DCT4 phones.
1291
1292 .. option:: nokiagetvoicerecord location
1293
1294     Get voice record from location and save to WAV file. File is
1295     coded using GSM 6.10 codec (available for example in win32). Name
1296     of file is like name of voice record in phone.
1297
1298     Created WAV files require GSM 6.10 codec to be played. In Win XP it's included
1299     by Microsoft. If you deleted it by accident in this operating system, make such
1300     steps:
1301
1302     1. Control Panel
1303     2. Add hardware
1304     3. click Next
1305     4. select "Yes. I have already connected the hardware
1306     5. select "Add a new hardware device
1307     6. select "Install the hardware that I manually select from a list
1308     7. select "Sound, video and game controllers
1309     8. select "Audio codecs
1310     9.  select "windows\\system32" directory and file "mmdriver.inf
1311     10. if You will be asked for file msgsm32.acm, it should unpacked from Windows CD
1312     11. now You can be asked if want to install unsigned driver (YES), about select codec configuration (select what you want) and rebotting PC (make it)
1313
1314 .. option:: nokiamakecamerashoot
1315
1316 .. option:: nokianetmonitor test
1317
1318     Takes output or set netmonitor for Nokia DCT3 phones.
1319
1320     .. seealso::
1321
1322         For more info about this option, please visit
1323         `Marcin's page <http://www.mwiacek.com/>`_ and read netmonitor manual
1324         there.
1325
1326     .. note::
1327
1328        test ``243`` enables all tests (after using command
1329        :command:`gammu nokianetmonitor 243` in some phones like 6210 or 9210 have to reboot
1330        them to see netmonitor menu)
1331
1332 .. option:: nokianetmonitor36
1333
1334     Reset counters from netmonitor test 36 in Nokia DCT3 phones.
1335
1336     .. seealso::
1337
1338         For more info about this option, please visit
1339         `Marcin's page <http://www.mwiacek.com/>`_ and read netmonitor manual
1340         there.
1341
1342 .. option:: nokiasecuritycode
1343
1344     Get/reset to "12345" security code
1345
1346 .. option:: nokiaselftests
1347
1348     Perform tests for Nokia DCT3 phones.
1349
1350     .. note::
1351
1352        EEPROM test can show an error when your phone has an EEPROM in flash
1353        (like 82xx/7110/62xx/33xx). The clock test will show an error when the
1354        phone doesn?t have an internal battery for the clock (like 3xxx).
1355
1356 .. option:: nokiasetlights keypad|display|torch on|off
1357
1358 .. option:: nokiasetoperatorname [networkcode name]
1359
1360 .. option:: nokiasetphonemenus
1361
1362     Enable all (?) possible menus for DCT3 Nokia phones:
1363
1364     1. ALS (Alternative Line Service) option menu
1365     2. vibra menu for 3210
1366     3. 3315 features in 3310 5.45 and higher
1367     4. two additional games (React and Logic) for 3210 5.31 and higher
1368     5. WellMate menu for 6150
1369     6. NetMonitor
1370
1371     and for DCT4:
1372
1373     1. ALS (Alternative Line Service) option menu
1374     2. Bluetooth, WAP bookmarks and settings menu, ... (6310i)
1375     3. GPRS Always Online
1376     4. and others...
1377
1378 .. option:: nokiasetvibralevel level
1379
1380     Set vibra power to "level" (given in percent)
1381
1382 .. option:: nokiatuneradio
1383
1384 .. option:: nokiavibratest
1385
1386
1387 Siemens specific commands
1388 -------------------------
1389
1390 .. option:: siemensnetmonact netmon_type
1391
1392     Enables network monitor in Siemens phone. Currently known values for type
1393     are 1 for full and 2 for simple mode.
1394
1395 .. option:: siemensnetmonitor test
1396
1397 .. option:: siemenssatnetmon
1398
1399 Network commands
1400 ----------------
1401
1402 .. option:: getgprspoint start [stop]
1403
1404 .. option:: listnetworks [country]
1405
1406     Show names/codes of GSM networks known for Gammu
1407
1408 .. option:: networkinfo
1409
1410     Show information about network status from the phone.
1411
1412 .. option:: setautonetworklogin
1413
1414 WAP settings and bookmarks commands
1415 -----------------------------------
1416
1417 .. option:: deletewapbookmark start [stop]
1418
1419     Delete WAP bookmarks from phone.
1420
1421     Locations are numerated from 1.
1422
1423 .. option:: getchatsettings start [stop]
1424
1425 .. option:: getsyncmlsettings start [stop]
1426
1427 .. option:: getwapbookmark start [stop]
1428
1429     Get WAP bookmarks from phone.
1430
1431     Locations are numerated from 1.
1432
1433 .. option:: getwapsettings start [stop]
1434
1435     Get WAP settings from phone.
1436
1437     Locations are numerated from 1.
1438
1439 MMS and MMS settings commands
1440 -----------------------------
1441
1442 .. option:: getallmms [-save]
1443
1444 .. option:: geteachmms [-save]
1445
1446 .. option:: getmmsfolders
1447
1448 .. option:: getmmssettings start [stop]
1449
1450 .. option:: readmmsfile file [-save]
1451
1452
1453 FM radio commands
1454 -----------------
1455
1456 .. option:: getfmstation start [stop]
1457
1458     Show info about FM stations in phone
1459
1460 Phone information commands
1461 --------------------------
1462
1463 .. option:: battery
1464
1465     Displays information about battery and power source.
1466
1467 .. option:: getdisplaystatus
1468
1469 .. option:: getlocation
1470
1471     Gets network information from phone (same as networkinfo)
1472     and prints location (latitude and longitude) based on information from
1473     `OpenCellID <http://opencellid.org>`_.
1474
1475 .. option:: getsecuritystatus
1476
1477     Show, if phone wait for security code (like PIN, PUK, etc.) or not
1478
1479 .. option:: identify
1480
1481     Show the most important phone data.
1482
1483 .. option:: monitor [times]
1484
1485     Retrieves phone status and writes it continuously to standard output. Press
1486     :kbd:`Ctrl+C` to interrupt this command.
1487
1488     If no parameter is given, the program runs until interrupted, otherwise
1489     only given number of iterations is performed.
1490
1491     This command outputs almost all information Gammu supports:
1492
1493     * Number of contacts, calendar and todo entries, messages, calls, etc.
1494     * Signal strength.
1495     * Battery state.
1496     * Currently used network.
1497     * Notifications of incoming messages and calls.
1498
1499
1500 Phone settings commands
1501 -----------------------
1502
1503 .. option:: getcalendarsettings
1504
1505     Displays calendar settings like first day of
1506     week or automatic deleting of old entries.
1507
1508 .. option:: getprofile start [stop]
1509
1510 .. option:: resetphonesettings PHONE|DEV|UIF|ALL|FACTORY
1511
1512     .. warning:: This will delete user data, be careful.
1513
1514     Reset phone settings.
1515
1516     ``PHONE``
1517         Clear phone settings.
1518
1519     ``DEV``
1520         Clear device settings.
1521
1522     ``ALL``
1523         Clear user settings.
1524
1525         * removes or set logos to default
1526         * set default phonebook and other menu settings
1527         * clear T9 words,
1528         * clear call register info
1529         * set default profiles settings
1530         * clear user ringtones
1531
1532     ``UIF``
1533         Clear user settings and disables hidden menus.
1534
1535         * changes like after ``ALL``
1536         * disables netmon and PPS (all "hidden" menus)
1537
1538     ``FACTORY``
1539         Reset to factory defaults.
1540
1541         * changes like after ``UIF``
1542         * clear date/time
1543
1544
1545 Dumps decoding commands
1546 -----------------------
1547
1548 .. note:: These commands are available only if Gammu was compiled with debugging options.
1549
1550 .. option:: decodebinarydump file [phonemodel]
1551
1552     Decodes a dump made by Gammu with
1553     :config:option:`LogFormat` set to ``binary``.
1554
1555 .. option:: decodesniff MBUS2|IRDA file [phonemodel]
1556
1557     Allows one to decode sniffs. See :ref:`Discovering protocol` for more details.
1558
1559 Other commands
1560 --------------
1561
1562 .. option:: entersecuritycode PIN|PUK|PIN2|PUK2|PHONE|NETWORK code|- [newpin|-]
1563
1564     Allow one to enter security code from PC. When code is ``-``, it is read from stdin.
1565
1566     In case entering PUK, some phones require you to set new PIN as well.
1567
1568 .. option:: presskeysequence mMnNpPuUdD+-123456789*0#gGrR<>[]hHcCjJfFoOmMdD@
1569
1570     Press specified key sequence on phone keyboard
1571
1572     ``mM``
1573         Menu
1574     ``nN``
1575         Names key
1576     ``pP``
1577         Power
1578     ``uU``
1579         Up
1580     ``dD``
1581         Down
1582     ``+-``
1583         +-
1584     ``gG``
1585         Green
1586     ``rR``
1587         Red
1588     ``123456789*0#``
1589         numeric keyboard
1590
1591 .. option:: reset SOFT|HARD
1592
1593     Make phone reset:
1594
1595     ``SOFT``
1596         without asking for PIN
1597     ``HARD``
1598         with asking for PIN
1599
1600     .. note:: Some phones will ask for PIN even with ``SOFT`` option.
1601     .. warning:: Some phones will reset user data on ``HARD`` reset.
1602
1603 .. option:: screenshot filename
1604
1605     Captures phone screenshot and saves it as filename. The extension is
1606     automatically appended to filename based on what data phone provides.
1607
1608 Batch mode commands
1609 -------------------
1610
1611 .. option:: batch [file]
1612
1613     Starts Gammu in a batch mode. In this mode you can issue
1614     several commands each on one line. Lines starting with # are treated as a
1615     comments.
1616
1617     By default, commands are read from standard input, but you can optionally
1618     specify a file from where they would be read (special case ``-`` means standard
1619     input).
1620
1621 Configuration commands
1622 ----------------------
1623
1624 .. option:: searchphone [-debug]
1625
1626     Attempts to search for a connected phone.
1627
1628     .. warning::
1629
1630        Please note that this can take a very long time, but in case you have
1631        no clue how to configure phone connection, this is a convenient way to
1632        find working setup for Gammu.
1633
1634 .. option:: install
1635
1636     Installs applet for currently configured connection to the phone.
1637
1638     You can configure search path for instllation files by
1639     :config:option:`DataPath`.
1640
1641 Gammu information commands
1642 --------------------------
1643
1644 .. option:: checkversion [STABLE]
1645
1646     Checks whether there is newer Gammu version
1647     available online (if Gammu has been compiled with CURL). If you pass
1648     additional parameter ``STABLE``, only stable versions will be checked.
1649
1650 .. option:: features
1651
1652     Print information about compiled in features.
1653
1654 .. option:: help [topic]
1655
1656     Print help. By default general help is printed, but you can
1657     also specify a help category to get more detailed help on some topic.
1658
1659 .. option:: version
1660
1661     Print version information and license.
1662
1663
1664 Return values
1665 +++++++++++++
1666
1667 gammu returns 0 on success. In case of failure non zero code is
1668 returned.
1669
1670 1
1671     Out of memory or other critical error.
1672 2
1673     Invalid command line parameters.
1674 3
1675     Failed to open file specified on command line.
1676 4
1677     Program was interrupted.
1678 98
1679     Gammu library version mismatch.
1680 99
1681     Functionality has been moved. For example to :ref:`gammu-smsd`.
1682
1683 Errors codes greater than 100 map to the GSM_Error
1684 values increased by 100:
1685
1686 101
1687     No error.
1688 102
1689     Error opening device. Unknown, busy or no permissions.
1690 103
1691     Error opening device, it is locked.
1692 104
1693     Error opening device, it doesn't exist.
1694 105
1695     Error opening device, it is already opened by other application.
1696 106
1697     Error opening device, you don't have permissions.
1698 107
1699     Error opening device. No required driver in operating system.
1700 108
1701     Error opening device. Some hardware not connected/wrongly configured.
1702 109
1703     Error setting device DTR or RTS.
1704 110
1705     Error setting device speed. Maybe speed not supported.
1706 111
1707     Error writing to the device.
1708 112
1709     Error during reading from the device.
1710 113
1711     Can't set parity on the device.
1712 114
1713     No response in specified timeout. Probably phone not connected.
1714 115
1715     Frame not requested right now. See <http://wammu.eu/support/bugs/> for information how to report it.
1716 116
1717     Unknown response from phone. See <http://wammu.eu/support/bugs/> for information how to report it.
1718 117
1719     Unknown frame. See <http://wammu.eu/support/bugs/> for information how to report it.
1720 118
1721     Unknown connection type string. Check config file.
1722 119
1723     Unknown model type string. Check config file.
1724 120
1725     Some functions not available for your system (disabled in config or not implemented).
1726 121
1727     Function not supported by phone.
1728 122
1729     Entry is empty.
1730 123
1731     Security error. Maybe no PIN?
1732 124
1733     Invalid location. Maybe too high?
1734 125
1735     Functionality not implemented. You are welcome to help authors with it.
1736 126
1737     Memory full.
1738 127
1739     Unknown error.
1740 128
1741     Can not open specified file.
1742 129
1743     More memory required...
1744 130
1745     Operation not allowed by phone.
1746 131
1747     No SMSC number given. Provide it manually or use the one configured in phone.
1748 132
1749     You're inside phone menu (maybe editing?). Leave it and try again.
1750 133
1751     Phone is not connected.
1752 134
1753     Function is currently being implemented. If you want to help, please contact authors.
1754 135
1755     Phone is disabled and connected to charger.
1756 136
1757     File format not supported by Gammu.
1758 137
1759     Nobody is perfect, some bug appeared in protocol implementation. Please contact authors.
1760 138
1761     Transfer was canceled by phone, maybe you pressed cancel on phone.
1762 139
1763     Phone module need to send another answer frame.
1764 140
1765     Current connection type doesn't support called function.
1766 141
1767     CRC error.
1768 142
1769     Invalid date or time specified.
1770 143
1771     Phone memory error, maybe it is read only.
1772 144
1773     Invalid data given to phone.
1774 145
1775     File with specified name already exists.
1776 146
1777     File with specified name doesn't exist.
1778 147
1779     You have to give folder name and not file name.
1780 148
1781     You have to give file name and not folder name.
1782 149
1783     Can not access SIM card.
1784 150
1785     Wrong GNAPPLET version in phone. Use version from currently used Gammu.
1786 151
1787     Only part of folder has been listed.
1788 152
1789     Folder must be empty.
1790 153
1791     Data were converted.
1792 154
1793     Gammu is not configured.
1794 155
1795     Wrong folder used.
1796 156
1797     Internal phone error.
1798 157
1799     Error writing file to disk.
1800 158
1801     No such section exists.
1802 159
1803     Using default values.
1804 160
1805     Corrupted data returned by phone.
1806 161
1807     Bad feature string in configuration.
1808 162
1809     Desired functionality has been disabled on compile time.
1810 163
1811     Bluetooth configuration requires channel option.
1812 164
1813     Service is not running.
1814 165
1815     Service configuration is missing.
1816 166
1817     Command rejected because device was busy. Wait and restart.
1818 167
1819     Could not connect to the server.
1820 168
1821     Could not resolve the host name.
1822 169
1823     Failed to get SMSC number from phone.
1824 170
1825     Operation aborted.
1826 171
1827     Installation data not found, please consult debug log and/or documentation for more details.
1828 172
1829     Entry is read only.
1830
1831
1832 Examples
1833 ++++++++
1834
1835 Configuration
1836 -------------
1837
1838 To check it out, you need to have configuration file for gammu, see
1839 :ref:`gammurc` for more details about it.
1840
1841 Sending messages
1842 ----------------
1843
1844 .. note::
1845
1846     All messages bellow are sent to number 123456, replace it with proper destination.
1847
1848 Send text message up to standard 160 chars:
1849
1850 .. code-block:: sh
1851
1852     echo "All your base are belong to us" | gammu sendsms TEXT 123456
1853
1854 or
1855
1856 .. code-block:: sh
1857
1858     gammu sendsms TEXT 123456 -text "All your base are belong to us"
1859
1860 Send long text message:
1861
1862 .. code-block:: sh
1863
1864     echo "All your base are belong to us" | gammu sendsms TEXT 123456 -len 400
1865
1866 or
1867
1868 .. code-block:: sh
1869
1870     gammu sendsms TEXT 123456 -len 400 -text "All your base are belong to us"
1871
1872 or
1873
1874 .. code-block:: sh
1875
1876     gammu sendsms EMS 123456 -text "All your base are belong to us"
1877
1878 Send some funky message with predefined sound and animation from 2 bitmaps:
1879
1880 .. code-block:: sh
1881
1882     gammu sendsms EMS 123456 -text "Greetings" -defsound 1 -text "from Gammu -tone10 axelf.txt -animation 2 file1.bmp file2.bmp
1883
1884 Send protected message with ringtone:
1885
1886 .. code-block:: sh
1887
1888     gammu sendsms EMS 123456 -protected 2 -variablebitmaplong ala.bmp -toneSElong axelf.txt -toneSE ring.txt
1889
1890
1891 Retrieving USSD replies
1892 -----------------------
1893
1894 For example for retrieving prepaid card status or retrieving various network info:
1895
1896 .. code-block:: sh
1897
1898     gammu getussd '#555#'
1899
1900 Uploading files to Nokia
1901 ------------------------
1902
1903 Add Alien to applications in your phone (you need to have files Alien.JAD and Alien.JAR in current directory):
1904
1905 .. code-block:: sh
1906
1907     gammu nokiaaddfile APPLICATION Alien
1908
1909 Add file.mid to ringtones folder:
1910
1911 .. code-block:: sh
1912
1913     gammu nokiaaddfile TONES file.mid
1914
1915 Setting operator logo
1916 ---------------------
1917
1918 Set logo for network ``230 03`` (Vodafone CZ):
1919
1920 .. code-block:: sh
1921
1922     gammu setbitmap OPERATOR ala.bmp "230 03"
1923
1924 .. _converting-formats:
1925
1926 Converting file formats
1927 -----------------------
1928
1929 The formats conversion can done using :option:`gammu savefile` or
1930 :option:`gammu convertbackup` commands.
1931
1932 Convert single entry (at position 260) from :ref:`gammu-backup` to vCalendar:
1933
1934 .. code-block:: sh
1935
1936     gammu savefile CALENDAR output.vcs myCalendar.backup 260
1937
1938 Convert first phonebook entry from :ref:`gammu-backup` to vCard:
1939
1940 .. code-block:: sh
1941
1942     gammu savefile VCARD21 output.vcf phone.backup ME 1
1943
1944 Convert all contacts from backup to vCard:
1945
1946 .. code-block:: sh
1947
1948     gammu convertbackup phone.backup output.vcf
1949
1950
1951 Reporting bugs
1952 --------------
1953
1954 There are definitely many bugs, reporting to author is welcome. Please include
1955 some useful information when sending bug reports (especially debug logs,
1956 operating system, it's version and phone information are needed).
1957
1958 To generate debug log, enable it in :ref:`gammurc`:
1959
1960 .. code-block:: ini
1961
1962     [gammu]
1963     YOUR CONNECTION SETTINGS
1964     logfile = /tmp/gammu.log
1965     logformat = textall
1966
1967 Alternatively you can specify logging on command line:
1968
1969 .. code-block:: sh
1970
1971    gammu -d textall -f /tmp/gammu.log ...
1972
1973 With this settings, Gammu generates /tmp/gammu.log on each connection to
1974 phone and stores dump of communication there. You can also find some
1975 hints for improving support for your phone in this log.
1976
1977 See <http://wammu.eu/support/bugs/> for more information on reporting bugs.
1978
1979 Please report bugs to `Gammu bug tracker <http://bugs.cihar.com/>`_.