camera1394: document trigger support for Indigo release

[jack-oquin]

This implies defining an API for the various trigger configuration parameters. We may choose to change the semantics slightly to make things simpler and easy to explain.

• Hardware triggering: which parameters are required? Which are optional?
• Software triggering: which parameters are required? Which are optional?
• Do users have to set both ~external_trigger and ~software_trigger to do S/W triggering? Why?
• What do the different ~auto_trigger options mean?
• Make sure terminology is clear: does "external" triggering mean the same as "hardware" triggering?
• Should we expose S/W triggering to users before adding the polled_camera interface (camera1394: add polled_camera interface, the standard ROS software triggering service #13)?
• Identify sections of the wiki documentation that need updating, like the Road Map and Limitations sections.
• Update the parameters list. Make sure new parameters' descriptions are clear to non-experts.
• Add a tutorial describing how to configure a camera for external H/W triggering.

@bgromov: any other doc requirements?

See also: #9, #12, #14, #16,

[jack-oquin]

Right now, the minimum set of parameters I can discover for S/W triggering is:

  <!-- run the driver with software triggering enabled -->
  <node pkg="camera1394" type="camera1394_node" name="camera1394_node">
    <param name="external_trigger" value="true" />
    <param name="software_trigger" value="true" />
    <param name="trigger_source" value="source_software" />
  </node>

From an external user perspective, that seems somewhat redundant and confusing.

• Should setting ~trigger_source to source_software set the others as a side-effect?
• Why is it source_software and not just software?
• Why is ~external_trigger also required? What does it mean, exactly? External to the camera, rather than internally clocked?
• Should users explicitly set ~auto_trigger to some state to ensure that feature is available and powered on? If so, what?

[jack-oquin]

I suppose ~auto_trigger reflects different states of the camera hardware:

• Off: the camera supports triggering with separate power control for that feature, and it is currently powered off.
• Query: the user (or driver) wants to determine the current trigger feature mode of the device.
• Auto: what does this mean? Why would a user set it?
• Manual: what does this mean?
• OneShot: does any camera support this mode? What would it mean?
• None: the camera does not support triggering of any kind.

[jack-oquin]

From the way it's used, "external" triggering does not necessarily imply "hardware". It seems to mean triggering from some clock source external to the camera, either H/W or S/W. Is that correct?

[bgromov]

Jack, thank you for composing the list.

Explaining trigger modes would be helpful. The descriptions are available in libdc1394 API docs (section Trigger Modes). As I understand some of the modes require additional data that can be set as feature value (ex. Mode 2). So we need to clearly mention that.

The S/W triggering is not much different from H/W triggering in terms of hanging the driver. Thus I see no problems to release S/W trigger feature together with the rest of changes. Though we definitely have to put a caution at the beginning of Trigger documentation about that.

The minimum set of parameters for H/W triggering in my case is just external_trigger: true. Not sure about other cameras.

From the way it's used, "external" triggering does not necessarily imply "hardware". It seems to mean triggering from some clock source external to the camera, either H/W or S/W. Is that correct?

Yes, I think it is correct.

[jack-oquin]

The minimum for S/W triggering on my Sony camera seems to be what I listed above.

That raises the question: why have the ~software_trigger parameter? Isn't it equivalent to ~external_trigger: true and ~trigger_source: source_software?

[jack-oquin]

We need to expose trigger source software in the configuration API, for unit test purposes.

We only need to tell users that a polled_camera interface is planned (#13) for future release.