hokuyo_node/Reviews/Jan 11 2010 Doc Review

Reviewer:

Instructions for doing a doc review

See DocReviewProcess for more instructions

1. Does the documentation define the Users of your Package, i.e. for the expected usages of your Stack, which APIs will users engage with?
2. Are all of these APIs documented?
3. Do relevant usages have associated tutorials? (you can ignore this if a Stack-level tutorial covers the relevant usage), and are the indexed in the right places?
4. If there are hardware dependencies of the Package, are these documented?
5. Is it clear to an outside user what the roadmap is for the Package?
6. Is it clear to an outside user what the stability is for the Package?
7. Are concepts introduced by the Package well illustrated?

Concerns / issues

• Eitan
  • What exactly does the hokuyo self test do?

    • Fixed.

  • The calibrate_time parameter could use a little lengthier description. Its not really clear what calibrating the hokuyo's time offset entails.

    • Fixed.

  • What does setting the model_04LX parameter change about the way the laser is configured, what parameters can be used, etc.

    • Fixed.

  • How does the cluster parameter merge range measurements when set to a value other than 1?

    • Fixed.

  • Given that we know there are many problems with different parameter configurations, we should probably mention them. For example, if intensity is set to true and skip is set to zero, it is likely that the laser will drop scans. I think there's also a problem if intensity is turned on and the min and max angle values are outside of -70 to 70 degrees. We can mention that these issues are caused by the hardware, but we should still alert people to them.

    • Fixed.

  • It might be nice to add information on known error codes to the troubleshooting page as well as instructions on how to get the device to recover. For example, we might list error code 33 as the laser getting dazzled and state that a power cycle of the hokuyo is the only way to recover. I know that the firmware for the laser is supposed to get a fix, but it would still be nice to have a place to check if an error is known or not.
  • The troubleshooting page could also contain some more information about common solutions to errors reported by diagnostics. You have 2 listed, but there are a lot more. I think this is important since we've had so much trouble with these lasers in the past and its likely that even after we ship with "no problems" people will struggle with these lasers.

Conclusion