Howto:Using mp broadcast.nas
| This article is a stub. You can help the wiki by expanding it. |
| Caution Developer information:
Some, and possibly most, of the details below are likely to be affected, or even deprecated, by the ongoing work on implementing and improving HLA support in FlightGear. For recent updates, please refer to HLA Timeline. |
Background
We don't have a dedicated "event channel" in MP, to deal with properties that change infrequently (Compared to position/velocity/surface positions/ etc).
The way the MP protocol is implemented at the moment (pre-HLA) you really really do not want to do that by creating a new MP enabled string property and put the flight-plan in it. Not only is the string encoding horribly inefficient (a 32bit word per character) but it would also be sent in each and every packet.
Well, it isn't ideal but it works for most purposes - without breaking MP compatibility.
It is a good idea to try to reduce what we send and mostly only send property values when they have changed. Currently every packet contains all (active) MP enabled properties - and many of them are constant or change very seldom. In that model a string property that rarely changes would not be a huge problem.
Perhaps some type of publish-subscribe model could also be useful - so the receivers only receive the properties they care about (usually position and velocities and those driving external animations if within visual distance).
Of course, this adds up to a rather sophisticated protocol so if some suitable existing middleware could be found that might be more preferable than trying to go our own way (certainly if one considers the current level of activity in this area:).
The approach I aimed for the last time I tried to mess with the MP subsystem was to send properties on change (perhaps repeated Y times) and every X seconds (to update newly joined users and cover lost packets). That seemed to be simple enough that it could even be backwards compatible - but unfortunately it caused occasional failures in the property interpolation code on the receiving side that I didn't manage to sort out. Going in that direction could be a feasible way to reduce the bandwidth consumption, though.
mp_broadcast.nas
mp_broadcast.nas is the communication layer of the WildFire feature (among other things). In addition, the dual-control feature makes use of it. If you rather use message passing, i.e. you want to send and receive your own data messages, you should look at Nasal/mp_broadcast.nas which provides an API for that. I see now that it might have a problem if you enable/disable MP at runtime - that feature did not exist when it was written. It shouldn't be not hard to fix, though (fixed in git).
Dual Control
The dual control system could certainly be more user friendly. I have some ideas for creating a wrapper where you just register the properties you want to have shared and it would create a configuration of the current building blocks internally. However, spare time and inspiration for this part is in short supply while I'm also hoping for HLA not being pie in the sky..
Currently the easiest component for listing up properties you want sent/recieved is the TDMEncode/TDMDecode components. The properties will propagate somewhat slowly since they share the same MP string property. ZLT-NT uses 4 TDMEncoder:s to propagate state to the copilot.
Be a bit careful with MP string properties - you can (or could?) easily overflow the maximum packet size...
To send a bunch of properties from the pilot to the copilot with TDM components you need to set up the pilot_connect_copilot() and copilot_connect_pilot() functions for your aircraft (typically in <your-aircraft>-dual-control.nas) as in the example below. ZLT-NT is a more full featured example.
What these two functions do is to set up the components that (on the pilot side here) monitor, encode and send the registered properties and (on the copilot side) receive, decode and write the updates into the property tree there. For this last step you specify a function func (v) { ... } that receives the new value and is responsible for writing it to the right property (which may or may not be the same as it originated from - animations normally look under the MP/AI entry available as "pilot" here).
The Dual Control system takes care of monitoring the registered properties (every frame) and encoding, decoding sending and receiving messages (which you don't have to care about) at a suitable rate.