SDK - CAMAPI Legacy challenges

Like all software protocol definitions, CAMAPI has grown over time. And like all reasonable software protocol definitions, CAMAPI attempted to add new capabilities that don't cause current users to have to touch code that talks to the camera via CAMAPI.

Some customer software may also read the video metadata file. If you created a reasonable metadata file parser, it should work well as new lines are added to the metadata file.

Occasionally when you investigate how to add a new feature to an existing protocol, you end up doing a head slap and wonder why you picked such a limited initial definition done in a way that is hard or impossible to extend cleanly. This purpose of this document is to record those head slap moments.

What CAMAPI features does my software release support

Every camera ships with the file hcamapi.py, which can be retrieved from http://10.11.12.13/static/host/hcamapi.py. Even if you are not using Python, you should take a look at hcamapi.py. This file is updated as new camera features are added, then included when the camera ships. It is the only documentation that matches the CAMAPI features supported by the camera you are controlling. Each CAMAPI method is documented. If you find the information unclear, please let us know. When a software release is created, a HTML pydoc web page is updated; which you can find on the edgertronic wiki.

Changing just one camera setting

To change a camera setting, you first need to retrieve the camera's current settings, made the modification, then invoke run() with the new settings. The reason why is the camera start out with the factory default settings, then overrides those setting with the values you provide via run(). This is why you have to send every setting with every call to run(), otherwise the factory default values will be used for unspecified settings. A much better approach would have been for the camera to start with the current settings, then override those settings with the values you provide.

Single frame rate capture extended to multi frame rate capture

The frame count and frame timing for a single frame rate capture is specified by 3 values: frame rate, duration, and percentage of frames captured before the trigger occurs. There were other options, such as frame rate, number of pretrigger frames and the number of post trigger frames. Or yet another option was frame rate, pretrigger duration and post trigger duration. There are probably several more as well. What they all have in common in the need for 3 values.

When multi frame rate capture was added, the design choice was for a user experience in (frame rate / duration) value pairs. We could have chosen frame rate / frame count value instead. Unfortunately, the initial camera implementation using frame rate, duration, and pretrigger percentage does not extend well to a frame rate / duration model.

This means the camera checks the settings passed to run() to see if any multi frame rate value are specified, and if so, operates in mrc (multirate capture) mode. Otherwise it operates in backwards compatibility mode. This is horrible and as you update you host applications that control the camera, you should switch to using the set of 6 multi frame rate capture settings.