JYMAG Files

This is the README file for JYMAG (Java Your Music and Graphics), a program
 for communicating with mobile phones.
JYMAG's main functionality is retrieving and sending multimedia and other
 objects from and to a Sagem mobile phone (tested on Linux with a
 "Sagem MY X5-2").
JYMAG can also be used with other phones and devices (modems) and serve as
 a general-purpose serial port terminal or a Java library for programmers.

========================= Running

Requirements:
- RxTx Java Transmission package from either:
	* http://www.rxtx.org
	* http://rxtx.qbang.org
	* http://users.frii.com/jarvi/rxtx/download.html
	* http://mfizz.com/oss/rxtx-for-java
  or any equivalent
- JRE, the Java SE Runtime Environment >= (1.)6.0
- permissions to use the serial ports
- port locking permissions may be required by RxTx. On Un*x, adding the user
  running JYMAG to the "uucp" and "lock" user groups should be enough. If not,
  add write permissions to the /var/lock directory.

Using NetBeans: open the JYMAG directory as a NetBeans Project
 and click "Run" (or press F6).

By hand (after unpacking):
	double-click the JYMAG\dist\JYMAG.jar file (works on MS Windows)
		or
	run.bat	(on MS Windows)
		or
	run.sh	(on Un*x)
		or
	java -jar JYMAG/dist/JYMAG.jar	(on Un*x)
		or
	java -jar JYMAG\dist\JYMAG.jar	(on MS Windows)

Read the "INSTALL" file.

========================= Running in the default language (no translations)

Requirements:
- RxTx Java Transmission package from either:
	* http://www.rxtx.org
	* http://rxtx.qbang.org
	* http://users.frii.com/jarvi/rxtx/download.html
	* http://mfizz.com/oss/rxtx-for-java
  or any equivalent
- JRE, the Java Runtime Environment >= (1.)6.0
- permissions to use the serial ports
- port locking permissions may be required by RxTx. On Un*x, adding the user
  running JYMAG to the "uucp" and "lock" user groups should be enough. If not,
  add write permissions to the /var/lock directory.

Using NetBeans: open the JYMAG folder as a NetBeans Project,
 right-click the project's root element in the project's tree on the
 left side of the window (the "Projects" sub-window), then click "Properties".
 Click "Run" in the tree and put
	-Duser.language=en -Duser.country=US
 in the "VM Options" field. Click OK and click "Run" (or press F6).

By hand (after unpacking):
	run-en.bat	(on MS Windows)
		or
	run-en.sh	(on Un*x)
		or	(on Un*x)
	java -jar -Duser.language=en -Duser.country=US JYMAG/dist/JYMAG.jar
		or	(on MS Windows)
	java -jar -Duser.language=en -Duser.country=US JYMAG\dist\JYMAG.jar

Read the "INSTALL" file.

========================= Usage (GUI)

Phone setup: connect it to the computer using a cable or IrDA or
 whatever works. Switch the transmission on in the phone, if necessary.
 If using a cable, select "Automatic speed" in the configuration.

No need to connect to the phone. Start by selecting the tab you're
 interested in (photos, ringtones, ...). Click on "Get list" to connect
 to the phone and get the list of elements. Select the elements you wish
 to download and click "Download selected". Choose the destination directory.
 The downloaded files will show up in selected location.
To upload an element, simply click the "Upload" button. Getting the
 list isn't necessary. You can also drag&drop the files you want to upload
 on any of the tables (except the alarms and SMS messages).
To edit an alarm, double click the cell in the table. Keep the format
 unchanged.
To read an SMS message, select it in the table and choose "Download selected".
 A new window will appear allowing you to read the message.
To send an SMS message, click the "Upload" button. A new window will appear allowing
 you to type the phone number and the message body.

========================= Usage (command line)

The following command-line (case-insensitive) options are supported:

	    --conf <file>		- read configuration from <file>
	    --databits <5,6,7,8>	- sets the number of data bits
					  (default: 8)
	    --delete-after-download     - delete the downloaded elements if
					  downloaded successfully
	    --delete-alarm <N>          - delete the alarm number N
	    --delete-element <ID>	- delete the element (file) with the
					  given ID
	    --delete-sms <N>		- delete the SMS message with ID=N
	    --dial-data <number>	- dials the given number for a data
					  connection
	    --dial-voice <number>	- dials the given number for a voice
					  connection
	    --download-all-animations	- downloads all animations/videos
					  from the phone and exits
	    --download-all-events	- downloads all events from the phone
					  and exits
	    --download-all-photos	- downloads all photos from the phone
					  and exits
	    --download-all-ringtones	- downloads all ringtones from the
	    				  phone and exits
	    --download-all-todo		- downloads all to-do tasks from the
					  phone and exits
	    --download-all-vcards	- downloads all addressbook entries
					  from the phone and exits
	    --download-all		- combines all "download" options
					  and exits
	    --download-dir <dir>	- sets the default download directory
	    --flow <none,soft,hard,soft+hard>	- sets the flow control mode
					  (default: none)
	    --hangup			- stops the current call, if any
	    --help			- display help
	    --lang LL_CC_VV		- select the language to use by JYMAG:
	    				  "LL" is the language, "CC" is the
	    				  country code, "VV" is the variant.
	    				  Separate them using underscores.
					  Only LL is required.
	    --license, --licence	- display license information
	    --list-alarms		- list the alarms set in the phone
	    --list-elements		- list phone elements (files)
	    --list-sms			- display the SMS messages in the phone
	    --parity <none, even, odd, space, mark>	- sets the parity mode
					  (default: none)
	    --port <filename>		- sets the default port
	    --scan			- scans available ports for "OK"
	    				  answers and exits the program
	    --send-cmd-file <file>	- sends the contents of the given file
					  (as commands or data or mix of these)
	    --send-sms <number> <msg>	- send the given <msg> message as an
					  SMS to the given recipient <number>
	    --speed <1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200,
		230400, 460800, 500000, 576000, 921600, 1000000, 1152000,
		1500000, 2000000, 2500000, 3000000, 3500000, 4000000>
					- sets the port speed
					  (default: 115200)
	    --stopbits <1,1.5,2>	- sets the number of stop bits
					  (default: 1)
	    --update-alarm "DD/MM/YY,HH:MM:SS",N,"days"	- updates the given
					  alarm in the phone. N is the alarm
					  number. Days are comma-separated
					  numbers (1-Monday) or 0 for all days
	    --upload <filename>		- uploads the given file to the phone
					  and exits
	    --version, -v		- display program version

========================= Currently supported operations:

1) Getting lists of: pictures, ringtones, addressbook entries,
   to-do tasks, events, animations/videos, alarms and SMS messages
2) Downloading:
   a) pictures: JPG (both Sagem and non-Sagem), GIF, BMP, PNG, WBMP,
      unverified: TIFF, PICT, EPS, PS, SVG, SVG+GZIP, SVG+ZIP, WMF, CGM, PMB
   b) ringtones: MIDI, AMR, WAV, unverified: AIFF, IMY, AAC, MP3
   c) addressbook entries (vCards)
   d) to-do tasks
   e) events (reminders, ...)
   f) animation/videos: MNG, GIF, unverified: WMV, MP4, MPEG
3) Uploading/updating/sending:
   a) pictures: JPG, GIF, BMP, PNG, WBMP, unverified: EMS_GR, TIFF, PICT, AI,
      EPS, PS
   b) ringtones: MIDI, WAV (IMA ADPCM, 8000Hz 16bit Mono?), AMR,
      unverified: IMY, ASG1, ASG2, MP3, MFI, AAC, AWB
   c) addressbook entries (vCards)
   d) to-do tasks
   e) events (reminders, ...)
   f) animation/videos: MNG, GIF, unverified: EMS_AN, MJPG, AVI, MP4, MPEG,
      3GP, 3GP2, SG1, SG2, SSA
   g) Java files: unverified: JAR, JAD, JAM
   h) alarms
   i) SMS messages
4) Deleting pictures, ringtones, addressbook entries,
   to-do tasks, events, animations/videos, alarms and SMS messages
5) Dialing numbers

========================= Converting ringtones

Some ringtones received from the phone may be in AMR format. You can
 convert those to other formats using other software, like the free
 "Mobile Media Converter". If it doesn't work, use the FFMPEG program
 attached to the "Mobile Media Converter" like this:

 ffmpeg -i Ring.amr -ar 44100 Ring.wav

To convert a ringtone to a WAV format accepted by the phone, use the
 following command:

 ffmpeg -i <ringtone file> -ar 8000 -t 10 -ac 1
	-acodec adpcm_ima_wav <output file>.wav

(the number after "-t" is the ringtone duration in seconds). I've only been
able to upload ringtones created with the above command. It may be possible
to upload longer ringtones, in greater sampling rates, stereo, ..., but
I haven't tried all that (my 30-second ringtones are rejected).