• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 #ifndef __CHDK_PTP_H
2 #define __CHDK_PTP_H
3 
4 // CHDK PTP protocol interface (can also be used in client PTP programs)
5 
6 // Note: used in modules and platform independent code.
7 // Do not add platform dependent stuff in here (#ifdef/#endif compile options or camera dependent values)
8 
9 #define PTP_CHDK_VERSION_MAJOR 2  // increase only with backwards incompatible changes (and reset minor)
10 #define PTP_CHDK_VERSION_MINOR 6  // increase with extensions of functionality
11                                   // minor > 1000 for development versions
12 
13 /*
14 protocol version history
15 0.1 - initial proposal from mweerden, + luar
16 0.2 - Added ScriptStatus and ScriptSupport, based on work by ultimA
17 1.0 - removed old script result code (luar), replace with message system
18 2.0 - return PTP_CHDK_TYPE_TABLE for tables instead of TYPE_STRING, allow return of empty strings
19 2.1 - experimental live view, not formally released
20 2.2 - live view (work in progress)
21 2.3 - live view - released in 1.1
22 2.4 - live view protocol 2.1
23 2.5 - remote capture
24 2.6 - script execution flags
25 */
26 
27 #define PTP_OC_CHDK 0x9999
28 
29 // N.B.: unused parameters should be set to 0
30 //enum ptp_chdk_command {
31 enum PTP_CHDK_Command {
32   PTP_CHDK_Version = 0,     // return param1 is major version number
33                             // return param2 is minor version number
34   PTP_CHDK_GetMemory,       // param2 is base address (not NULL; circumvent by taking 0xFFFFFFFF and size+1)
35                             // param3 is size (in bytes)
36                             // return data is memory block
37   PTP_CHDK_SetMemory,       // param2 is address
38                             // param3 is size (in bytes)
39                             // data is new memory block
40   PTP_CHDK_CallFunction,    // data is array of function pointer and 32 bit int arguments (max: 10 args prior to protocol 2.5)
41                             // return param1 is return value
42   PTP_CHDK_TempData,        // data is data to be stored for later
43                             // param2 is for the TD flags below
44   PTP_CHDK_UploadFile,      // data is 4-byte length of filename, followed by filename and contents
45   PTP_CHDK_DownloadFile,    // preceded by PTP_CHDK_TempData with filename
46                             // return data are file contents
47   PTP_CHDK_ExecuteScript,   // data is script to be executed
48                             // param2 is language of script
49                             //  in proto 2.6 and later, language is the lower byte, rest is used for PTP_CHDK_SCRIPT_FL* flags
50                             // return param1 is script id, like a process id
51                             // return param2 is status from ptp_chdk_script_error_type
52   PTP_CHDK_ScriptStatus,    // Script execution status
53                             // return param1 bits
54                             // PTP_CHDK_SCRIPT_STATUS_RUN is set if a script running, cleared if not
55                             // PTP_CHDK_SCRIPT_STATUS_MSG is set if script messages from script waiting to be read
56                             // all other bits and params are reserved for future use
57   PTP_CHDK_ScriptSupport,   // Which scripting interfaces are supported in this build
58                             // param1 CHDK_PTP_SUPPORT_LUA is set if lua is supported, cleared if not
59                             // all other bits and params are reserved for future use
60   PTP_CHDK_ReadScriptMsg,   // read next message from camera script system
61                             // return param1 is chdk_ptp_s_msg_type
62                             // return param2 is message subtype:
63                             //   for script return and users this is ptp_chdk_script_data_type
64                             //   for error ptp_chdk_script_error_type
65                             // return param3 is script id of script that generated the message
66                             // return param4 is length of the message data.
67                             // return data is message.
68                             // A minimum of 1 bytes of zeros is returned if the message has no data (empty string or type NONE)
69   PTP_CHDK_WriteScriptMsg,  // write a message for scripts running on camera
70                             // input param2 is target script id, 0=don't care. Messages for a non-running script will be discarded
71                             // data length is handled by ptp data phase
72                             // input messages do not have type or subtype, they are always a string destined for the script (similar to USER/string)
73                             // output param1 is ptp_chdk_script_msg_status
74   PTP_CHDK_GetDisplayData,  // Return camera display data
75                             // This is defined as separate sub protocol in live_view.h
76                             // Changes to the sub-protocol will always be considered a minor change to the main protocol
77                             //  param2 bitmask of data
78                             //  output param1 = total size of data
79                             //  return data is protocol information, frame buffer descriptions and selected display data
80                             //  Currently a data phase is always returned. Future versions may define other behavior
81                             //  for values in currently unused parameters.
82   // Direct image capture over USB.
83   // Use lua get_usb_capture_support for available data types, lua init_usb_capture for setup
84   PTP_CHDK_RemoteCaptureIsReady, // Check if data is available
85                                  // return param1 is status
86                                  //  0 = not ready
87                                  //  0x10000000 = remote capture not initialized
88                                  //  otherwise bitmask of PTP_CHDK_CAPTURE_* datatypes
89                                  // return param2 is image number
90   PTP_CHDK_RemoteCaptureGetData  // retrieve data
91                                  // param2 is bit indicating data type to get
92                                  // return param1 is length
93                                  // return param2 more chunks available?
94                                  //  0 = no more chunks of selected format
95                                  // return param3 seek required to pos (-1 = no seek)
96 };
97 
98 // data types as used by ReadScriptMessage
99 enum ptp_chdk_script_data_type {
100   PTP_CHDK_TYPE_UNSUPPORTED = 0, // type name will be returned in data
101   PTP_CHDK_TYPE_NIL,
102   PTP_CHDK_TYPE_BOOLEAN,
103   PTP_CHDK_TYPE_INTEGER,
104   PTP_CHDK_TYPE_STRING, // Empty strings are returned with length=0
105   PTP_CHDK_TYPE_TABLE,  // tables are converted to a string by usb_msg_table_to_string,
106                         // this function can be overridden in lua to change the format
107                         // the string may be empty for an empty table
108 };
109 
110 // TempData flags
111 #define PTP_CHDK_TD_DOWNLOAD  0x1  // download data instead of upload
112 #define PTP_CHDK_TD_CLEAR     0x2  // clear the stored data; with DOWNLOAD this
113                                    // means first download, then clear and
114                                    // without DOWNLOAD this means no uploading,
115                                    // just clear
116 
117 // Script Languages - for execution only lua is supported for now
118 #define PTP_CHDK_SL_LUA    0
119 #define PTP_CHDK_SL_UBASIC 1
120 #define PTP_CHDK_SL_MASK 0xFF
121 
122 /* standard message chdkptp sends */
123 #define PTP_CHDK_LUA_SERIALIZE "\n\
124 serialize_r = function(v,opts,r,seen,depth)\n\
125         local vt = type(v)\n\
126         if vt == 'nil' or  vt == 'boolean' or vt == 'number' then\n\
127                 table.insert(r,tostring(v))\n\
128                 return\n\
129         end\n\
130         if vt == 'string' then\n\
131                 table.insert(r,string.format('%q',v))\n\
132                 return\n\
133         end\n\
134         if vt == 'table' then\n\
135                 if not depth then\n\
136                         depth = 1\n\
137                 end\n\
138                 if depth >= opts.maxdepth then\n\
139                         error('serialize: max depth')\n\
140                 end\n\
141                 if not seen then\n\
142                         seen={}\n\
143                 elseif seen[v] then\n\
144                         if opts.err_cycle then\n\
145                                 error('serialize: cycle')\n\
146                         else\n\
147                                 table.insert(r,'\"cycle:'..tostring(v)..'\"')\n\
148                                 return\n\
149                         end\n\
150                 end\n\
151                 seen[v] = true;\n\
152                 table.insert(r,'{')\n\
153                 for k,v1 in pairs(v) do\n\
154                         if opts.pretty then\n\
155                                 table.insert(r,'\\n'..string.rep(' ',depth))\n\
156                         end\n\
157                         if type(k) == 'string' and string.match(k,'^[_%a][%a%d_]*$') then\n\
158                                 table.insert(r,k)\n\
159                         else\n\
160                                 table.insert(r,'[')\n\
161                                 serialize_r(k,opts,r,seen,depth+1)\n\
162                                 table.insert(r,']')\n\
163                         end\n\
164                         table.insert(r,'=')\n\
165                         serialize_r(v1,opts,r,seen,depth+1)\n\
166                         table.insert(r,',')\n\
167                 end\n\
168                 if opts.pretty then\n\
169                         table.insert(r,'\\n'..string.rep(' ',depth-1))\n\
170                 end\n\
171                 table.insert(r,'}')\n\
172                 return\n\
173         end\n\
174         if opts.err_type then\n\
175                 error('serialize: unsupported type ' .. vt, 2)\n\
176         else\n\
177                 table.insert(r,'\"'..tostring(v)..'\"')\n\
178         end\n\
179 end\n\
180 serialize_defaults = {\n\
181         maxdepth=10,\n\
182         err_type=true,\n\
183         err_cycle=true,\n\
184         pretty=false,\n\
185 }\n\
186 function serialize(v,opts)\n\
187         if opts then\n\
188                 for k,v in pairs(serialize_defaults) do\n\
189                         if not opts[k] then\n\
190                                 opts[k]=v\n\
191                         end\n\
192                 end\n\
193         else\n\
194                 opts=serialize_defaults\n\
195         end\n\
196         local r={}\n\
197         serialize_r(v,opts,r)\n\
198         return table.concat(r)\n\
199 end\n\
200 \n\
201 usb_msg_table_to_string=serialize\n"
202 
203 
204 // bit flags for script start
205 #define PTP_CHDK_SCRIPT_FL_NOKILL           0x100 // if script is running return error instead of killing
206 #define PTP_CHDK_SCRIPT_FL_FLUSH_CAM_MSGS   0x200 // discard existing cam->host messages before starting
207 #define PTP_CHDK_SCRIPT_FL_FLUSH_HOST_MSGS  0x400 // discard existing host->cam messages before starting
208 
209 // bit flags for script status
210 #define PTP_CHDK_SCRIPT_STATUS_RUN   0x1 // script running
211 #define PTP_CHDK_SCRIPT_STATUS_MSG   0x2 // messages waiting
212 // bit flags for scripting support
213 #define PTP_CHDK_SCRIPT_SUPPORT_LUA  0x1
214 
215 
216 // bit flags for remote capture
217 // used to select and also to indicate available data in PTP_CHDK_RemoteCaptureIsReady
218 /*
219 Full jpeg file. Note supported on all cameras, use Lua get_usb_capture_support to check
220 */
221 #define PTP_CHDK_CAPTURE_JPG    0x1
222 
223 /*
224 Raw framebuffer data, in camera native format.
225 A subset of rows may be requested in init_usb_capture.
226 */
227 #define PTP_CHDK_CAPTURE_RAW    0x2
228 
229 /*
230 DNG header.
231 The header will be DNG version 1.3
232 Does not include image data, clients wanting to create a DNG file should also request RAW
233 Raw data for all known cameras will be packed, little endian. Client is responsible for
234 reversing the byte order if creating a DNG.
235 Can requested without RAW to get sensor dimensions, exif values etc.
236 
237 ifd 0 specifies a 128x96 RGB thumbnail, 4 byte aligned following the header
238 client is responsible for generating thumbnail data.
239 
240 ifd 0 subifd 0 specifies the main image
241 The image dimensions always contain the full sensor dimensions, if a sub-image was requested
242 with init_usb_capture, the client is responsible for padding the data to the full image or
243 adjusting dimensions.
244 
245 Bad pixels will not be patched, but DNG opcodes will specify how to patch them
246 */
247 #define PTP_CHDK_CAPTURE_DNGHDR 0x4
248 
249 // status from PTP_CHDK_RemoteCaptureIsReady if capture not enabled
250 #define PTP_CHDK_CAPTURE_NOTSET 0x10000000
251 
252 // message types
253 enum ptp_chdk_script_msg_type {
254     PTP_CHDK_S_MSGTYPE_NONE = 0, // no messages waiting
255     PTP_CHDK_S_MSGTYPE_ERR,      // error message
256     PTP_CHDK_S_MSGTYPE_RET,      // script return value
257     PTP_CHDK_S_MSGTYPE_USER,     // message queued by script
258 // TODO chdk console data ?
259 };
260 
261 // error subtypes for PTP_CHDK_S_MSGTYPE_ERR and script startup status
262 enum ptp_chdk_script_error_type {
263     PTP_CHDK_S_ERRTYPE_NONE = 0,
264     PTP_CHDK_S_ERRTYPE_COMPILE,
265     PTP_CHDK_S_ERRTYPE_RUN,
266     // the following are for ExecuteScript status only, not message types
267     PTP_CHDK_S_ERR_SCRIPTRUNNING = 0x1000, // script already running with NOKILL
268 };
269 
270 // message status
271 enum ptp_chdk_script_msg_status {
272     PTP_CHDK_S_MSGSTATUS_OK = 0, // queued ok
273     PTP_CHDK_S_MSGSTATUS_NOTRUN, // no script is running
274     PTP_CHDK_S_MSGSTATUS_QFULL,  // queue is full
275     PTP_CHDK_S_MSGSTATUS_BADID,  // specified ID is not running
276 };
277 
278 #endif // __CHDK_PTP_H
279