Iphone Serial Port Tutorial

steprun

iPhone/iPod Touch Serial Port Tutorial By Collin Meyer (TheRain) 12-09-2007

DISCLAIMER: Interfacing electronically to the Iphone has the potential to cause severe damage to your Iphone or cause your Iphone to become non-functional. By following this tutorial you take sole responsibility and understand the risks of what you are doing.

Summary
This tutorial will explain how to use the serial RX and TX lines on the Iphone as a standard UART serial port. Software on the Iphone can access the UART using the same libraries and functions as in any UNIX software. This tutorial was created to explain how to get past this issue. This tutorial will explain some of the basic parts and code needed to use the UART.

Tools

1. Jailbroken Iphone with BSD Subsystem installed (Search the web for jailbreak tutorials)
2. Iphone development toolchain for Mac OSX, Linux, Windows (Cygwin) or other OS. I use this http://code.google.com/p/winchain/ in Windows.
3. Sparkfun Ipod connector or breakout board see http://www.sparkfun.com/commerce/product_info.php?products_id=633 or http://www.sparkfun.com/commerce/product_info.php?products_id=8295
4. PC USB UART - optional, but used in this tutorial. You will need either a 3.3V level UART for PC (see http://www.sparkfun.com/commerce/product_info.php?products_id=718) or you will need an old style 12V level serial cable with a level converter like this one http://www.compsys1.com/workbench/On_top_of_the_Bench/Max233_Adapter/max233_adapter.html (see warning below)
5. A soldering iron will help you out :)
6. Microsoft Visual Studio - optional, but used in the source code examples for the PC serial port communication.

WARNING! Do not try to use a 12V level RS232 port for this without a level converter to ~3V, it will severely damage your Iphone or render it non-functional.
The Dock Port
In the Ipod/Iphone dock port, the pins we are concerned with are as follows

Pin 1	Ground
Pin 18	3.3V Power (+)
Pin 12	TX also known as Serial Transmit
Pin 13	RX also known as Serial Receive

To see a full description of all of the pins in the dock connector, see here: http://pinouts.ru/Devices/ipod_pinout.shtml

Connections: iPhone/iPod Touch RX should connect to TX of the connected device, TX to RX of the connected device, and Ground to the Ground of the connected device. If your device can be powered by a low amperage, 3.3V power source you may chose to connect PIN 18 as well and power your device directly from the iPhone/iPod Touch.

On the software end the Serial RX and TX lines of the Iphone can be accessed just like a standard serial port on any other UNIX-like system. See below for source example.

A Source Code Example
-Overview
In this example I will use a PC serial port to communicate with the Iphone. Initially, only the Iphone can talk over serial to whatever serial device it is talking to, a PC or other types of devices. Since this is the case, it makes sense for our Iphone application to send out a "handshaking" message to the connected device. Then the connected device can do the hardware trick mentioned above, and the Iphone will then allow data to be sent to it over serial. Since our Iphone software doesn't know when the receiving has been enabled, the connected device can send back a "handshaking" message to tell the Iphone program that it can send data to it. So our software flow looks something like this:

Iphone Code - On the Iphone we open the device tty.iap, this is the serial port device. The code works like standard Unix serial device access code. Here is an example of opening the tty.iap serial port, setting it as no hardware flow control, 8 bit data, 19200 baud rate, and BLOCKING I/O.

1. #include <stdio.h> /* Standard input/output definitions */
   
2. #include <string.h> /* String function definitions */
   
3. #include <unistd.h> /* UNIX standard function definitions */
   
4. #include <fcntl.h> /* File control definitions */
   
5. #include <errno.h> /* Error number definitions */
   
6. #include <termios.h> /* POSIX terminal control definitions */
   
7.  
   
8. static struct termios gOriginalTTYAttrs;
   
9.  
   
10. static int OpenSerialPort()
    
11. {
    
12.     int fileDescriptor = -1;
    
13.     int handshake;
    
14.     struct termios options;
    
15.  
    
16.     // Open the serial port read/write, with no controlling terminal, and don't wait for a connection.
    
17.     // The O_NONBLOCK flag also causes subsequent I/O on the device to be non-blocking.
    
18.     // See open(2) ("man 2 open") for details.
    
19.  
    
20.     fileDescriptor = open("/dev/tty.iap", O_RDWR | O_NOCTTY | O_NONBLOCK);
    
21.     if (fileDescriptor == -1)
    
22.     {
    
23.         printf("Error opening serial port %s - %s(%d).\n",
    
24.                "/dev/tty.iap", strerror(errno), errno);
    
25.         goto error;
    
26.     }
    
27.  
    
28.     // Note that open() follows POSIX semantics: multiple open() calls to the same file will succeed
    
29.     // unless the TIOCEXCL ioctl is issued. This will prevent additional opens except by root-owned
    
30.     // processes.
    
31.     // See tty(4) ("man 4 tty") and ioctl(2) ("man 2 ioctl") for details.
    
32.  
    
33.     if (ioctl(fileDescriptor, TIOCEXCL) == -1)
    
34.     {
    
35.         printf("Error setting TIOCEXCL on %s - %s(%d).\n",
    
36.             "/dev/tty.iap", strerror(errno), errno);
    
37.         goto error;
    
38.     }
    
39.  
    
40.     // Now that the device is open, clear the O_NONBLOCK flag so subsequent I/O will block.
    
41.     // See fcntl(2) ("man 2 fcntl") for details.
    
42.  
    
43.     if (fcntl(fileDescriptor, F_SETFL, 0) == -1)
    
44.     {
    
45.         printf("Error clearing O_NONBLOCK %s - %s(%d).\n",
    
46.             "/dev/tty.iap", strerror(errno), errno);
    
47.         goto error;
    
48.     }
    
49.  
    
50.     // Get the current options and save them so we can restore the default settings later.
    
51.     if (tcgetattr(fileDescriptor, &gOriginalTTYAttrs) == -1)
    
52.     {
    
53.         printf("Error getting tty attributes %s - %s(%d).\n",
    
54.             "/dev/tty.iap", strerror(errno), errno);
    
55.         goto error;
    
56.     }
    
57.  
    
58.     // The serial port attributes such as timeouts and baud rate are set by modifying the termios
    
59.     // structure and then calling tcsetattr() to cause the changes to take effect. Note that the
    
60.     // changes will not become effective without the tcsetattr() call.
    
61.     // See tcsetattr(4) ("man 4 tcsetattr") for details.
    
62.  
    
63.     options = gOriginalTTYAttrs;
    
64.  
    
65.     // Print the current input and output baud rates.
    
66.     // See tcsetattr(4) ("man 4 tcsetattr") for details.
    
67.  
    
68.     printf("Current input baud rate is %d\n", (int) cfgetispeed(&options));
    
69.     printf("Current output baud rate is %d\n", (int) cfgetospeed(&options));
    
70.  
    
71.     // Set raw input (non-canonical) mode, with reads blocking until either a single character
    
72.     // has been received or a one second timeout expires.
    
73.     // See tcsetattr(4) ("man 4 tcsetattr") and termios(4) ("man 4 termios") for details.
    
74.  
    
75.     cfmakeraw(&options);
    
76.     options.c_cc[VMIN] = 1;
    
77.     options.c_cc[VTIME] = 10;
    
78.  
    
79.     // The baud rate, word length, and handshake options can be set as follows:
    
80.  
    
81.     cfsetspeed(&options, B19200); // Set 19200 baud
    
82.     options.c_cflag |= (CS8); // RTS flow control of input
    
83.  
    
84.  
    
85.     printf("Input baud rate changed to %d\n", (int) cfgetispeed(&options));
    
86.     printf("Output baud rate changed to %d\n", (int) cfgetospeed(&options));
    
87.  
    
88.     // Cause the new options to take effect immediately.
    
89.     if (tcsetattr(fileDescriptor, TCSANOW, &options) == -1)
    
90.     {
    
91.         printf("Error setting tty attributes %s - %s(%d).\n",
    
92.             "/dev/tty.iap", strerror(errno), errno);
    
93.         goto error;
    
94.     }
    
95.     // Success
    
96.     return fileDescriptor;
    
97.  
    
98.     // Failure "/dev/tty.iap"
    
99. error:
    
100.     if (fileDescriptor != -1)
     
101.     {
     
102.         close(fileDescriptor);
     
103.     }
     
104.  
     
105.     return -1;
     
106. }

In our main application, we impliment the handshaking method I described above.

1. int main(int args, char *argv[])
   
2. {
   
3.     int fd;
   
4.     char somechar[8];
   
5.     fd=OpenSerialPort(); // Open tty.iap with no hardware control, 8 bit, BLOCKING and at 19200 baud
   
6.     if(fd>-1)
   
7.     {
   
8.         write(fd,"*",1); // Write handshaking message over serial
   
9.         ///////////////////////////////////////////////////////////////////////////////////////////////////
   
10.         // After this, our device or our PC program should be strobing serial ground to gain access to the
    
11. Iphone Serial Line
    
12.         //////////////////////////////////////////////////////////////////////////////////////////////////
    
13.         read(fd,&somechar[0],1); // Read 1 byte over serial. This will block (wait) untill the byte has been
    
14. received
    
15.         if(somechar[0]=='*') // Check if this byte is a "handshaking" message
    
16.         {
    
17.             printf("Serial connection established!\n"); // If it is, we have established a connection to the
    
18. device and can freely read/write over
    
19.             while(1) // Do this forever or untill someone presses CTRL+C
    
20.             {
    
21.                 read(fd,&somechar[0],1); // Read a character over
    
22.                 putchar(somechar[0]); // Write the character to the
    
23.             }
    
24.         }
    
25.     }
    
26.     return 0;
    
27. }

The Connected Device in this case is simulated by a Windows program written in C#. The C# program receives the Handshaking message from the Iphone. It then sends the '*' handshaking message back to the Iphone to let it know that it can safely send data back and forth now. After this, you can click the "Hello Iphone!" button in the Windows program to send a string to the Iphone. The Iphone will output this string to the terminal.

Iphone Code package:  Serial.zip
Windows C# code package (Connected device simulation):  IphoneSerialDemoWINR3.zip -updated 12/11/2007

http://devdot.wikispaces.com/Iphone+Serial+Port+Tutorial