Serial Communication

Name

Serial Communication -- 

Synopsis


#include <serial.h>


int         canon_serial_change_speed       (GPPort *gdev,
                                             int speed);
unsigned char* canon_serial_dialogue        (Camera *camera,
                                             GPContext *context,
                                             unsigned char mtype,
                                             unsigned char dir,
                                             int *len,
                                             ...);
void        canon_serial_error_type         (Camera *camera);
int         canon_serial_get_byte           (GPPort *gdev);
int         canon_serial_get_cts            (GPPort *gdev);
int         canon_serial_get_dirents        (Camera *camera,
                                             unsigned char **dirent_data,
                                             unsigned int *dirents_length,
                                             const char *path,
                                             GPContext *context);
unsigned char* canon_serial_get_file        (Camera *camera,
                                             const char *name,
                                             int *length,
                                             GPContext *context);
int         canon_serial_get_thumbnail      (Camera *camera,
                                             const char *name,
                                             unsigned char **data,
                                             int *length,
                                             GPContext *context);
int         canon_serial_init               (Camera *camera);
int         canon_serial_put_file           (Camera *camera,
                                             CameraFile *file,
                                             char *destname,
                                             char *destpath,
                                             GPContext *context);
int         canon_serial_ready              (Camera *camera,
                                             GPContext *context);
unsigned char* canon_serial_recv_frame      (Camera *camera,
                                             int *len);
unsigned char* canon_serial_recv_msg        (Camera *camera,
                                             unsigned char mtype,
                                             unsigned char dir,
                                             int *total,
                                             GPContext *context);
unsigned char* canon_serial_recv_packet     (Camera *camera,
                                             unsigned char *type,
                                             unsigned char *seq,
                                             int *len);
int         canon_serial_send               (Camera *camera,
                                             unsigned char *buf,
                                             int len,
                                             int sleep);
int         canon_serial_send_frame         (Camera *camera,
                                             unsigned char *pkt,
                                             int len);
int         canon_serial_send_packet        (Camera *camera,
                                             unsigned char type,
                                             unsigned char seq,
                                             unsigned char *pkt,
                                             int len);
int         canon_serial_wait_for_ack       (Camera *camera);
int         canon_psa50_chk_crc             (unsigned char *pkt,
                                             int len,
                                             unsigned short crc);
unsigned short canon_psa50_gen_crc          (unsigned char *pkt,
                                             int len);
void        serial_flush_input              (GPPort *gdev);
void        serial_flush_output             (GPPort *gdev);
void        serial_set_timeout              (GPPort *gdev,
                                             int to);
#define     MAX_TRIES
#define     USLEEP1
#define     USLEEP2
#define     HDR_FIXED_LEN
#define     DATA_BLOCK

#define     ERROR_ADDRESSED
#define     ERROR_LOWBATT
#define     ERROR_RECEIVED
#define     FATAL_ERROR
#define     NOERROR

#define     CANON_FBEG
#define     CANON_FEND
#define     CANON_ESC
#define     CANON_XOR

#define     MAX_PKT_PAYLOAD
#define     PKT_HDR_LEN
#define     PKT_SEQ
#define     PKT_TYPE
#define     PKT_LEN_LSB
#define     PKT_LEN_MSB
#define     PKT_MSG
#define     PKT_EOT
#define     PKT_ACK
#define     PKT_NACK
#define     PKTACK_NACK
#define     PKT_UPLOAD_EOT

#define     MAX_MSG_SIZE
#define     MSG_HDR_LEN
#define     MSG_02
#define     MSG_MTYPE
#define     MSG_DIR
#define     MSG_LEN_LSB
#define     MSG_LEN_MSB
#define     DIR_REVERSE
#define     UPLOAD_DATA_BLOCK

#define     SPEED_9600
#define     SPEED_19200
#define     SPEED_38400
#define     SPEED_57600
#define     SPEED_115200

#define     MAX_PKT_SIZE
#define     FRAG_NUM
#define     FRAG_LEN_LSB
#define     FRAG_LEN_MSB

Description

Details

canon_serial_change_speed ()

int         canon_serial_change_speed       (GPPort *gdev,
                                             int speed);

Changes the speed of the communication.

gdev :

serial port to use

speed :

the new speed

Returns :

1 on success. 0 on any error.


canon_serial_dialogue ()

unsigned char* canon_serial_dialogue        (Camera *camera,
                                             GPContext *context,
                                             unsigned char mtype,
                                             unsigned char dir,
                                             int *len,
                                             ...);

Higher level function: sends a message and waits for a reply from the camera.

Payload: each argument after "len" goes by 2: the variable itself, and the next argument has to be its length. You also have to finish the list by a "NULL".

Example: To send a string called "name" : canon_serial_dialogue(0x05,0x12,&len,name,strlen(name)+1,NULL);

camera :

camera with which to communicate

context :

context for error reporting

mtype :

type

dir :

direction

len :

length of the received payload

... :

The rest of the arguments will be put together to fill up the payload of the request message.

Returns :

buffer received from canon_serial_recv_msg(), NULL if failure


canon_serial_error_type ()

void        canon_serial_error_type         (Camera *camera);

logs a debug message corresponding to the error encountered

camera :

Camera object to work with


canon_serial_get_byte ()

int         canon_serial_get_byte           (GPPort *gdev);

Gets the next byte from the serial line. Actually the function reads chunks of data and keeps them in a cache. Only one byte per call will be returned.

gdev :

serial port to use

Returns :

the byte on success, -1 on error.


canon_serial_get_cts ()

int         canon_serial_get_cts            (GPPort *gdev);

Gets the status of the CTS (Clear To Send) line on the serial port.

CTS is "1" when the camera is ON, and "0" when it is OFF.

gdev :

serial port to use

Returns :

1 on CTS high. 0 on CTS low.


canon_serial_get_dirents ()

int         canon_serial_get_dirents        (Camera *camera,
                                             unsigned char **dirent_data,
                                             unsigned int *dirents_length,
                                             const char *path,
                                             GPContext *context);

Lists a directory.

camera :

camera to initialize

dirent_data :

to receive directory data

dirents_length :

to receive length of dirent_data

path :

pathname of directory to list

context :

context for error reporting

Returns :

gphoto2 error code


canon_serial_get_file ()

unsigned char* canon_serial_get_file        (Camera *camera,
                                             const char *name,
                                             int *length,
                                             GPContext *context);

Get a file from a USB_connected Canon camera.

camera :

camera to lock keys on

name :

name of file to fetch

length :

to receive length of image data

context :

context for error reporting

Returns :

buffer containing file data (or NULL on failure); length in length.


canon_serial_get_thumbnail ()

int         canon_serial_get_thumbnail      (Camera *camera,
                                             const char *name,
                                             unsigned char **data,
                                             int *length,
                                             GPContext *context);

This is just the serial specific part extracted from the older canon_get_thumbnail() routine.

camera :

camera to work on

name :

file name (complete canon path) of file to get thumbnail for

data :

pointer to data pointer

length :

pointer to data length

context :

context for error reporting

Returns :

gphoto2 error code


canon_serial_init ()

int         canon_serial_init               (Camera *camera);

Initializes the given serial device by setting speed, parity, etc.

camera :

Camera object to initialize

Returns :

GP_OK


canon_serial_put_file ()

int         canon_serial_put_file           (Camera *camera,
                                             CameraFile *file,
                                             char *destname,
                                             char *destpath,
                                             GPContext *context);

Uploads file to camera via serial port

camera :

Camera object to work with

file :

CameraFile object to upload

destname :

name file should have on camera

destpath :

pathname for directory to put file

context :

context for error reporting

Returns :

gphoto2 error code


canon_serial_ready ()

int         canon_serial_ready              (Camera *camera,
                                             GPContext *context);

serial part of canon_int_ready

camera :

camera to get ready

context :

context for error reporting

Returns :

gphoto2 error code


canon_serial_recv_frame ()

unsigned char* canon_serial_recv_frame      (Camera *camera,
                                             int *len);

Receive a frame from the camera

camera :

Camera object to work with

len :

to receive the length of the buffer

Returns :

a buffer containing a frame from the camera, or NULL on error. On success, len will contain the length of the buffer.


canon_serial_recv_msg ()

unsigned char* canon_serial_recv_msg        (Camera *camera,
                                             unsigned char mtype,
                                             unsigned char dir,
                                             int *total,
                                             GPContext *context);

Receives a message from the camera.

See the "Protocol" file for an explanation of the various elements needed to handle a message.

camera :

Camera object to work with

mtype :

message type.

dir :

direction.

total :

payload length (set by this function).

context :

context for error reporting

Returns :

char* pointer to the message payload; NULL on failure.


canon_serial_recv_packet ()

unsigned char* canon_serial_recv_packet     (Camera *camera,
                                             unsigned char *type,
                                             unsigned char *seq,
                                             int *len);

Receives a packet from the serial port using canon_serial_send_frame(), decodes frame information (type, sequence number, and length), and returns it stripped of frame information.

camera :

Camera object to work with

type :

Type of packet

seq :

Sequence number of packet

len :

length of data received

Returns :

packet data (or NULL if failure). Type in type, sequence number in seq, and length in len.


canon_serial_send ()

int         canon_serial_send               (Camera *camera,
                                             unsigned char *buf,
                                             int len,
                                             int sleep);

Send the given buffer with given length over the serial line.

camera :

Camera object to work with

buf :

the raw data buffer to send

len :

the length of the buffer

sleep :

time in usec to wait between characters

Returns :

0 on success, -1 on error.


canon_serial_send_frame ()

int         canon_serial_send_frame         (Camera *camera,
                                             unsigned char *pkt,
                                             int len);

Sends a frame of data to camera

camera :

Camera object to work with

pkt :

Data to send to camera

len :

Length of packet

Returns :

1 if canon_serial_send() succeeds, 0 if it fails


canon_serial_send_packet ()

int         canon_serial_send_packet        (Camera *camera,
                                             unsigned char type,
                                             unsigned char seq,
                                             unsigned char *pkt,
                                             int len);

frames a packet (generates CRC, packs with sequence number and length) and sends it to the camera through the serial port using canon_serial_send_frame().

camera :

Camera object to work with

type :

seq :

pkt :

data to send to camera

len :

length of data

Returns :

status from canon_serial_send_frame()


canon_serial_wait_for_ack ()

int         canon_serial_wait_for_ack       (Camera *camera);

Waits for an "ACK" from the camera.

camera :

Camera object to work with

Returns :

1 : ACK received 0 : communication error (no reply received for example) -1 : NACK received.


canon_psa50_chk_crc ()

int         canon_psa50_chk_crc             (unsigned char *pkt,
                                             int len,
                                             unsigned short crc);

Calculate a new checksum for the packet and compare it with an existing checksum to detect transmission errors.

pkt :

packet

len :

length of pkt

Param3 :

Returns :

1 on success or if checksum calculation would fail 0 if checksums don't match


canon_psa50_gen_crc ()

unsigned short canon_psa50_gen_crc          (unsigned char *pkt,
                                             int len);

Calculate a CRC on a Canon packet

pkt :

packet data on which to calculate checksum

len :

length of pkt

Returns :

CRC value. On error doesn't return at all but exits program with a message to stderr.


serial_flush_input ()

void        serial_flush_input              (GPPort *gdev);

Dummy function.

gdev :

serial port to use


serial_flush_output ()

void        serial_flush_output             (GPPort *gdev);

Dummy function.

gdev :

serial port to use


serial_set_timeout ()

void        serial_set_timeout              (GPPort *gdev,
                                             int to);

Sets the timeout, in miliseconds.

gdev :

serial port to use

to :

timeout in milliseconds


MAX_TRIES

#define MAX_TRIES 10


USLEEP1

#define USLEEP1 0


USLEEP2

#define USLEEP2 1


HDR_FIXED_LEN

#define HDR_FIXED_LEN 30


DATA_BLOCK

#define DATA_BLOCK 1536


ERROR_ADDRESSED

#define ERROR_ADDRESSED	2


ERROR_LOWBATT

#define ERROR_LOWBATT	4


ERROR_RECEIVED

#define ERROR_RECEIVED	1


FATAL_ERROR

#define FATAL_ERROR	3


NOERROR

#define NOERROR		0


CANON_FBEG

#define CANON_FBEG      0xc0


CANON_FEND

#define CANON_FEND      0xc1


CANON_ESC

#define CANON_ESC       0x7e


CANON_XOR

#define CANON_XOR       0x20


MAX_PKT_PAYLOAD

#define MAX_PKT_PAYLOAD 65535


PKT_HDR_LEN

#define PKT_HDR_LEN     4


PKT_SEQ

#define PKT_SEQ         0


PKT_TYPE

#define PKT_TYPE        1


PKT_LEN_LSB

#define PKT_LEN_LSB     2


PKT_LEN_MSB

#define PKT_LEN_MSB     3


PKT_MSG

#define PKT_MSG         0


PKT_EOT

#define PKT_EOT         4


PKT_ACK

#define PKT_ACK         5


PKT_NACK

#define PKT_NACK        255


PKTACK_NACK

#define PKTACK_NACK     0x01


PKT_UPLOAD_EOT

#define PKT_UPLOAD_EOT  3


MAX_MSG_SIZE

#define MAX_MSG_SIZE    (MAX_PKT_PAYLOAD-12)


MSG_HDR_LEN

#define MSG_HDR_LEN     16


MSG_02

#define MSG_02          0


MSG_MTYPE

#define MSG_MTYPE       4


MSG_DIR

#define MSG_DIR         7


MSG_LEN_LSB

#define MSG_LEN_LSB     8


MSG_LEN_MSB

#define MSG_LEN_MSB     9


DIR_REVERSE

#define DIR_REVERSE     0x30


UPLOAD_DATA_BLOCK

#define UPLOAD_DATA_BLOCK 900


SPEED_9600

#define SPEED_9600   "\x00\x03\x02\x02\x01\x10\x00\x00\x00\x00\xc0\x39"


SPEED_19200

#define SPEED_19200  "\x00\x03\x08\x02\x01\x10\x00\x00\x00\x00\x13\x1f"


SPEED_38400

#define SPEED_38400  "\x00\x03\x20\x02\x01\x10\x00\x00\x00\x00\x5f\x84"


SPEED_57600

#define SPEED_57600  "\x00\x03\x40\x02\x01\x10\x00\x00\x00\x00\x5e\x57"


SPEED_115200

#define SPEED_115200 "\x00\x03\x80\x02\x01\x10\x00\x00\x00\x00\x4d\xf9"


MAX_PKT_SIZE

#define MAX_PKT_SIZE    (MAX_PKT_PAYLOAD+4)


FRAG_NUM

#define FRAG_NUM                0


FRAG_LEN_LSB

#define FRAG_LEN_LSB    2


FRAG_LEN_MSB

#define FRAG_LEN_MSB    3