Update attribute_observer examples and docs

[hamishwillee]

This updates the main examples and API ref for attribute observers and for message listeners. There are a couple of outstanding questions around listeners, and I understand @tcr3dr is going to rename some of the attribute observer methods.

This also updates the migration guide with information about attribute observers and message listeners (the information is "high level" and refers back to the relevant guide sections)

At time of writing it does not

• update drone_delivery

[hamishwillee]

Thanks for merging!

[mikerob]

I'm trying to run the example, but hit two snags:

1. I think there's a typo:
   def raw_imu_callback(self,rawimu):
   print self.raw_imu

I think the "def" should be "self,raw_imu", shouldn't it?

2. When I run it, it says "
   File "create_attribute.py", line 79, i n
   @vehicle.message_listener('RAW_IMU')
   AttributeError: 'Vehicle' object has no attribute 'message_listener'

3. Question: In this example, you created a new object (raw_imu) within vehicle, so you end up with vehicle.raw_imu.xacc etc, whereas other attributes are stored as _heartbeat, _mount_pitch etc.

Is the eventual intent to move to objects with Vehicle? I'm coding up RADIO_STATUS now, so would like to do it the "right" way.

[hamishwillee]

Hi @mikerob

'm trying to run the example, but hit two snags:

1. I think there's a typo:
   def raw_imu_callback(self,rawimu):
   print self.raw_imu

I think the "def" should be "self,raw_imu", shouldn't it?

No, this is an argument so it can be whatever you like. However in an example it should probably be attr_name to make it clear what this value will return with. I've pushed a change to #426 for this.

2. When I run it, it says "
   File "create_attribute.py", line 79, i n
   @vehicle.message_listener('RAW_IMU')
   AttributeError: 'Vehicle' object has no attribute 'message_listener'

I suspect that the API changed underneath you so that the examples no longer match the docs - the decorator is now on_message. This all builds against PR #426 following testing today. Sorry about that - lot of change going on as we improve the API coming up to our first "proper" DKPY2 release.

3. Question: In this example, you created a new object (raw_imu) within vehicle, so you end up with vehicle.raw_imu.xacc etc, whereas other attributes are stored as _heartbeat, _mount_pitch etc.

Is the eventual intent to move to objects with Vehicle? I'm coding up RADIO_STATUS now, so would like to do it the "right" way.

You should not take the example as "exactly" the same way as you implement something that is part of the API - instead you should copy the patterns in the existing init.py :-)

The reason the example is different is that

1. I wrote this without looking at the code internals.
2. I am trying to show how the API works, while the internal code is trying to create a proper separation of public and private interfaces.
3. I am not sure how much I can duplicate the internal process - for example whether I can create a private property in an external file.

@tcr3dr Depending on strategy discussions we probably should consider if we need to adopt the same sort of pattern for the example as we use internally (if that is possible - not sure you can declare the properly in the same way) even though it might not make so much sense. If only so that when people copy they copy the right thing. The obvious alternative is to write a "how to add an attribute "properly" doc..

[tcr3dr]

@hamishwillee I reworked the example until I came up with #437, similar to how internal initialization works. I think that should answer the above questions if you agree.

@mikerob Thanks for contributing. Can you open new issues or continue on #437 to continue discussion? I don't mind new issues being opened, I just want to make sure I don't overlook comments submitted into closed issues.

Is the eventual intent to move to objects with Vehicle? I'm coding up RADIO_STATUS now, so would like to do it the "right" way.

We have to make a judgement call for each attribute, but I imagine there's no reason not to merge it upstream.