Adding some non-trivial examples to docs

[yck011522]

This is not really an issue but more of a friendly feature that could be added to reduce new-comer learning curve. I believe adding some non-trivial examples to the ReadTheDocs would help a lot of new comers start with their production code.

There are recurring themes that have been asked / discussed in this Issue Tracker in the past weeks and I realized those conversations could have been summarized into some examples files that can be shared to users. The following are some examples I have in mind:

Connect, disconnect and reconnect to ROS
Some confusion between client.close() and client.terminate() and when to use them. As discussed in #56.

How to check message round trip latency.
The publisher and listener node testing code used by @gonzalocasas to diagnose #41

Non-blocking subscription of messages that requires long processing time.
A multi-thread example where each received messages needs to be processed for a long time. Requiring the use of Threading for processing.

Handshake between publisher / nodes to ensure each other is connected and responsive.

Subscribing to but only keeping the latest messages:
The use case / behaviour described by @HWiese1980 in #41 (comment) and answered by #41 (comment)

Examples of all standard message types that ROS support.
For example how to take advantage of std_msgs/String for transmitting json-serialized Python Dictionary. Usage of std_msgs/Header. Transmitting a python time stamp using std_msgs/Time, and different *MultiArray types to hold a Python list.

I believe each of these samples deserves a short page to describe the case and also provide with the actual file that can be executed. I personally like the layout of the index page and grouping strategy used by Rhino Python Samples.

[gonzalocasas]

@yck011522 thanks for the suggestion! I added several advanced examples here and also details about disconnection and reconnection. I did not (yet) add an example of using json with std_msgs/String because it's debatable if that's a usage we should encourage (since it is basically double-encoding in JSON, because the underlying transport of rosbridge is json already).

Does that look good?

[yck011522]

Thanks @gonzalocasas
LGTM

More discussion on the dictionary to string hack: So I suppose the preferred way is to use custom messages. But that requires rebuilding ROS. What if a user do not have access to building their own ROS? Any alternative solutions?

[WasabiFan]

I'd just like to give a major 👍 for additional+clarified samples, indexed by core needs. After "how do I connect?" and "how to I create a topic?", which are covered reasonably in the docs, the next question I had was "how do I send a message?". That's covered in general, until you hit nested message types. It's not immediately obvious that the correct approach is nested dictionaries.

Once I figured that out, the next hurdle was the values of those types -- and I think Header is a pretty common type. The only example I can find in this repo or on the site is in a file called 03_slow_consumer.py, which isn't likely to be found by someone trying to publish a header. This sample shows that the computation for secs and nsecs is non-obvious; again, could probably be figured out by hand, with significant frustration.

Edit: it also appears that the sample code computes nsecs as a float and doesn't cast it like it does with secs; this causes errors on the bridge side, since that field is specified to be an integer.

[jajberni]

I am trying to decode sensor_msgs/PointCloud2 messages without much success. The data is encoded pretty much like an image, but it is necessary to decode the PointField[] fields to determine the structure, etc.

I am considering using ros_numpy: e.g https://github.com/eric-wieser/ros_numpy/blob/master/src/ros_numpy/point_cloud2.py but it relies on the original ROS libraries.