WWCSetterAlternativeByEmail
From SecondSailing
Protocols for sailing
PAGE IS OBSOLETE, see SLSA Protocols for Sailing
Status of this document:
Under review and commentation by CC and JT.
1/9/2008 MD: altered the cruise wind protocol by adding a broadcast from the WWC setter instead of the boat. Altered the race wind by adding the RcBoat messsage type. some enhancements for better security.
4/9/2008 MD: added chapters for communication between start and finish line. Added communication between buoys and boats. Changed fixed broadcast channels to secret channels. Added the Tako ping for all types of wind. Added min and max limits for settings. Replaced UUID keys with names, because llKey2Name only works if the person is in the same sim.
This document contains a series of guidelines for boat builders to follow if they want their boats to be compatible with the SLSA racing system and be able to communicate with other boats on the water.
We identify communication between:
- racedirector/sailor and wind/wave/current setter
- boat and wind/wave/current setter
- racedirector/sailor and startline
- boat and start/finishline
- startline and finishline
- boat and buoys
- 2 or more boats
- boat and external systems
Design goals
The following issues shall be covered by this specification:
- The communication shall be extendable, i.e. when new parameters turn out to be important for new boats/applications it shall be possible to add these parameters
- The communication shall allow to implement distributed systems, ie. a set of devices located in several objects which are not necessarily in the neighbourhood of each other (e.g. a race course with buoys on the course that report a passing boat).
- The communication shall allow independant systems which don't interfere, e.g. race wind that only acts on boats "logged in" to that race. This also includes indepedant systems of the same type (e.g. two race winds for two start lines close together)
- the system should be open to every serious boat builder and for every serious builder of racing equipment but it should include a few "secrets" that make it necessary to ask for those. The reason behind that is to disallow anonymous usage of these specifications to discourage griefers.
- explicitely excluded (and not forgotten) cryptographic and similar means to obscure or verify the content of sent messages. This specification assumes that cheating and griefing will not be done by serious members of the sailing community.
Communication between racedirector/sailor and wind/wave/current setter
See WWC Setter help notecard for this.
Communication between boat and wind/wave/current setter
The WWC setter precedes every broadcast it does by a "ping" message on a fixed secret channel channel. Boats use this signal to compute the secret channels for receiving old style wind, cruise settings and race settings.
The WWC setter broadcasts its cruise wind settings 3 seconds after the ping on a secret channel that is calculated according to the rules defined by Kanker Greenacre. The data strings send are also defined by Kanker Greenacre. These broadcasts are for backward compatibility only and ensure that older boats like the Tako can use race wind.
- Cruise wind/waves/current
The WWC setter broadcasts a notification of its presence on a computed channel by using llRegionSay 3 seconds after the ping. The computation of this channel is not published here for security reasons. The message send is build up as follows:
message type (value="WwcSetter")
The boats in this region that have not yet received any winds (or that wish to keep listening for other WWC setters) will pick up the notification and send an email to the WWC setter (the key of the setter has been retrieved from the incoming chat message). The email subject will contain the message type, which has the value "CrWwcReq". The body of the email is empty.
Example: llEmail("a311ce4d-e755-f148-7999-56f289ca3f3b@lsl.secondlife.com", "CrWwcReq", "");
The WWC setter will check for email every 3 seconds and picks up the request from the boat. The WWC setter retrieves the boat's UUID key and sends an email back that stores all the wwc information for cruising. The subject of the email will contain the value "CrWwc"
The message body contains several records with WWC information, that are each comma separated value lists. Individual records are separated by "\n". The message body contains the following records:
wind message:
message type, (value = "CrWnd") wind direction (direction where the wind is coming from in degrees (range 0-359)), wind speed (in m/s (range: 1.0 - 12.0)), wind gusts (max. extra strength of gusts/lulls in m/s (range: 0.0 - wind speed)), wind shifts (max. angle in degrees (range 0 - 180)), wind change rate (rate at which the gusts and shifts come 1.0 = default (range 0.1 - 5.0)), wind external system (name of the external system to use instead)
If the parameter with the name of the external system is used, all other parameters are to be ignored by the boat.
waves message:
message type, (value = "CrWav") wave height (max height in meters (range 0.0 - 5.0)), wave length (in meters (range 5.0 - 50.0)) wave speed (in m/s (range 3.0 - 15.0)) wave height variance (0.0 = all waves the same, 1.0 = waves vary from 0.0 meters to 2x max wave height, 2.0 = waves can get up to 3x wave height (range 0.0 - 2.0)), wave length variance (0.0 = all waves the same, 0.5 = wave length varies from 0.0 meters to 1.5x max wave length (range 0.0 - 0.75)), wave origin X (origin in global cooridinates where the wavers originate from, this is to let waves hit boats in sync), wave origin Y (origin in global coordinates where the wavers originate from, this is to let waves hit boats in sync), water depth (default water depth for current and waves) wave external system (name of the external system to use instead)
If the parameter with the name of the external system is used, all other parameters are to be ignored by the boat.
current message:
message type, (value = "CrCrt") current direction (direction where current is going to in degrees (note: works opposit to wind dir) (range 0 - 359)), current speed (strength of the current in m/s (range 0.0 - 3.0)), water depth (default water depth for current and waves) current external system (name of the external system to use instead)
If the parameter with the name of the external system is used, all other parameters are to be ignored by the boat.
Also contained in the email body are the local variances to the WWC settings (if present in the WWC setter). For each local variance setting there is one separate line.
message type, (value = "CrWwcLoc") global x coordinate, global y coordinate, 100% effect radius in meters (range 0 - 200) 0% effect radius in meters (range: 100% effect radius - 255) wind speed multiplier (range 0.0 - 3.0), extra wind angle (range -180 - 180), wave height multiplier (range 0.0 - 3.0), current speed multiplier (range 0.0 - 3.0), extra current angle (range -180 - 180)
The decay works as follows: the effect is full in a circle with a radius of "100% effect radius" and gradually decays to 0% at a distance of "0% effect radius".
Example:
100% effect radius = 50
0% effect radius = 100
At 40 meters from the specified global coordinates the effect will be 100%, at 75 meters from the coordinates the effect will be 50%, at 90 meters from the coordinates, the effect is 20%.
The boat checks for emails coming in from only the WWC setter because it remembered its key and only messages that contain the right subject.
Example: llGetNextEmail("a311ce4d-e755-f148-7999-56f289ca3f3b@lsl.secondlife.com", "CrWwc");
Every boat builder is free to implement handlers for only a subset of these messages and to ignore the others.
The boat now prompts the helmsman if he wants to accept the wwc settings just received. It would be good practise to display a summary of the settings, to prevent accepting very strong wind or any other unwelcome settings. It is always possible for people to use a fake WWC setter, a copy of a real WWC setter or to simply set the real WWC setter to values that are of the scale, like for instance a wind of 50 m/s. It is not possible to prevent this, but by letting the boat prompt the sailor with the settings that are received, he or she can decide to ignore the received values.
The boat can stop listening for other WWC setters now and stop checking for incoming emails. But this is up to the boatbuilder.
Security: The boats are unlikely to receive emails from any other than the WWC setter, because no other object will know it's key. (at least from this protocol, it is possible to retrieve the key of a boat by listening to other messages send out). But the boat only checks for email send out by the WWC setter, ignoring anything else.
The WWC setter checks only for emails with the correct subject, ignoring anything else. A possible weakness here is to bombard it with emails with the correct format, making the WWC setter stall because it constantly tries to send out emails to all (fake) boats) and after each email the script is paused for 20 seconds by SL. This is difficult, because people need to know the key of the WWC setter. It is possible to retrieve the key by listening to the ping or to informational chat messages on channel 0 that are send out by the WWC setter during configuration of the parameters. A possible remedy might be to check for all emails but after receiving multiple emails from the same sender in a few seconds it could add the sender to a temporary blacklist and send out a warning on channel 0 for all to hear what is going on.
- Race wind/waves/current
The WWC setter broadcasts a race notification 3 seconds after the ping on a computed channel by using llRegionSay. The computation of this channel is not published here for security reasons. The message send is build up as follows:
message type, (value = "Rc") race id (randomly generated number), race name (f.i. SAILON), class name (f.i.: Flying Fizz, Tako, Tradewind), sailing mode (0,1,2,3 meaning: no requirement, novice, competition, expert), crew size (0 if no requirements, 1, 2, 3, etc), name of race director
Note that these parameters are only for prompting the sailor if he/she wishes to compete in the race, The "official" parameters are send through email.
The boats pick up this chat message and ask the helmsman if he/she would want to subscribe to this race. If the helmsman confirms, a request is send from the boat to the WWC setter using email. The email subject will contain the message type, which has the value "RcWwcReq". The body of the email contains:
message type (value="RcWwcReq"), race id
Example: llEmail("a311ce4d-e755-f148-7999-56f289ca3f3b@lsl.secondlife.com", "RcWwcReq", "RcWwcReq,1234");
The WWC setter will pick up the request, retrieve the UUID key of the boat and send an email back to the boat with all requested information. The boat checks for any emails coming in from only the WWC setter because it remembered its key and only if they contain the right subject.
The subject of the email send by the WWC setter to the boat will be "RcWwc". The message body contains several records with WWC information, that are each comma separated value lists. Individual records are separated by "\n". The message body contains the following records:
message type, (value = "Rc"), race id, race name, class name (f.i.: Flying Fizz, Tako, Tradewind), boat version (version number of the boat that is required or a seed to check the version numbers of the internal scripts of the boat (to ensure all boats are of the same version, have not been tampered with and are equally fast)), nr of avatars (nr of avatars needed to sail the boat during the race including the helmsman), skills level (0-9, depends on boat type, on a fizz: 0-fun mode, 1-novice mode, 2-competition mode, 3-expert mode), extra value 1 (value depends on the type of boat used), extra value 2 (value depends on the type of boat used)
message type, (value = "RcWnd"), race id, wind direction (direction where the wind is coming from in degrees (range 0-359)), wind speed (in m/s (range: 1.0 - 15.0)), wind gusts (max. extra strength of gusts/lulls in m/s (range: 0.0 - wind speed)), wind shifts (max. angle in degrees (range 0 - 180)), wind change rate (rate at which the gusts and shifts come 1.0 = default (range 0.1 - 5.0)), wind external system (name of the external system to use instead)
If the parameter with the name of the external system is used, all other parameters are to be ignored.
message type, (value = "RcWav") race id, wave height (max height in meters (range 0.0 - 5.0)), wave length (in meters (range 5.0 - 50.0)) wave speed (in m/s (range 3.0 - 15.0)) wave height variance (0.0 = all waves the same, 1.0 = waves vary from 0.0 meters to 2x max wave height, 2.0 = waves can get up to 3x wave height (range 0.0 - 2.0)), wave length variance (0.0 = all waves the same, 0.5 = wave length varies from 0.0 meters to 1.5x max wave length (range 0.0 - 0.75)), wave origin X (origin in global cooridinates where the wavers originate from, this is to let waves hit boats in sync), wave origin Y (origin in global cooridinates where the wavers originate from, this is to let waves hit boats in sync), water depth (default water depth for current and waves) wave external system (name of the external system to use instead)
If the parameter with the name of the external system is used, all other parameters are to be ignored.
message type, (value = "RcCrt") race id, current direction (direction where current is going to in degrees (note: works opposit to wind dir) (range 0 - 359)), current speed (strength of the current in m/s (range 0.0 - 3.0)), water depth (default water depth for current and waves) current external system (name of the external system to use instead)
If the parameter with the name of the external system is used, all other parameters are to be ignored.
Also contained in the email body are the local variances to the WWC settings (if present in the WWC setter). For each local variance setting there is one separate line.
message type, (value = "RcWwcLoc") race id, (the integer number assigned to the race) global x coordinate, global y coordinate, 100% effect radius in meters (range 0 - 200) 0% effect radius in meters (range: 100% effect radius - 255) wind speed multiplier (range 0.0 - 3.0), extra wind angle (range -180 - 180), wave height multiplier (range 0.0 - 3.0), current speed multiplier (range 0.0 - 3.0), extra current angle (range -180 - 180)
The decay works as follows: the effect is full in a circle with a radius of "100% effect radius" and gradually decays to 0% at a distance of "0% effect radius".
Example:
100% effect radius = 50
0% effect radius = 100
At 40 meters from the specified global coordinates the effect will be 100%, at 75 meters from the coordinates the effect will be 50%, at 90 meters from the coordinates, the effect is 20%.
The boat checks for emails coming in from only the WWC setter because it remembered its key and only messages that contain the right subject.
Example: llGetNextEmail("a311ce4d-e755-f148-7999-56f289ca3f3b@lsl.secondlife.com", "RcWwc");
Every boat builder is free to implement handlers for only a subset of these messages and to ignore the others.
If the boat has succesfully received the settings, it sends an email back with the value "RcSub" as subject and a message body in this format:
message type, (value = "RcSub") race id, name of skipper, name of crew member 1, (if present) name of crew member 2, (if present) name of crew member 3, etc.
The UUID key of the boat itself is not necessary, because this is transferred automatically by SL.
It would be good practice to show the name of the race in the boat's display some form, so the race director and other competitors can see if a boat has entered or not. An other good practise would be to show that initials or first name of the sailor in the sails or on the id box.
The boat will continue to check for email, because a race director can always decide to change the conditions for a race. The race director might even do so during a race while the boats are sailing to simulate a sudden weather change. The WWC setter will send out an email to every boat that has subscribed to the race. The message send is the same as the "RcWwc" email, but it does not necessarily contains all record times in its message body. The boats should keep any previous settings and only replace the parts that are received.
Security: Nothing is more fun for some people than to disturb a race. This protocol has some prevention for this build in. The boats are unlikely to receive emails from any other than the WWC setter, because no other object will know it's key. (at least from this protocol, it is possible to retrieve the key of a boat by listening to other messages send out). But the boat only checks for email send out by the WWC setter, ignoring anything else.
The WWC setter checks only for emails with the correct subject, ignoring anything else. A possible weakness here is to bombard it with emails with the correct format, making the WWC setter stall because it constantly tries to send out emails to all (fake) boats) and after each email the script is paused for 20 seconds by SL. This is difficult, because people need to know the key of the WWC setter. It is possible to retrieve the key by listening to the ping or to informational chat messages on channel 0 that are send out by the WWC setter during configuration of the parameters. A possible remedy might be to check for all emails but after receiving multiple emails from the same sender in a few seconds it could add the sender to a temporary blacklist and send out a warning on channel 0 for all to hear what is going on.
It is always possible for people to use a fake WWC setter, a copy of a real WWC setter or to simply set the real WWC setter to values that are of the scale, like for instance a wind of 50 m/s. It is not possible to prevent this, but the person would need to know how to compute the secret channel.
Communication between racedirector/sailor and startline
Each startline in SL should use channel 0 for this type of communication. But the startline should only listen after being touched and should only listen to the avatar that clicked it.
MD: Will follow shortly
Communication between boat and startline
To be defined.
Communication between startline and finishline
To be defined.
Communication between boats
Two boats that are near eachother will have an effect on eachother. For instance:
They can cover the other boat by blocking the wind.
If they sail closely behind each other, the wind is disturbed and full of turbulence.
One of them will have Right of Way (ROW)
To notify other boats of a boats position each boat should transmit its position and heading at regular intervals. This is done on channel -7001 for cruising and -8001 for racing by using llRegionSay. There are different channels for cruising and racing. This way cruisers will not interfere with races that are being held. Also, race wind and cruise wind are already different, which would make it strange to have wo boats shadowing each other with the wind coming from oposit directions.
The message format is:
message type, (value = "BtPos") x coordinate (global x coordinate), y coordinate (global y coordinate), sail area (sail area in M2), tack the boat is sailing on (P=port tack so the sail is on starboard, S=starboard tack with the sail on port), boat size from root prim to bow (in meters used to determine side by side situations for ROW computation), boat size from root prim to stern (in meters used to determine side by side situations for ROW computation), speed in x direction (in m/s (including any tidal current)), speed in y direction (in m/s (including any tidal current))
The speed is used to interpolate the boats position in between broadcasts. The tack, heading and boatsize can be used to establish simple ROW indications. (leeward boat and port/starboard rules)
Example:
vector pos = llGetPos()+llGetRegionCorner();
string tack = "S";
integer sailArea = 25;
if(gennakerRaised) sailArea+=20;
if(relativeWindDir<0) tack = "P";
llSay(-7001,(string)((integer)pos.x)+","+
(string)((integer)pos.y)+","+
(string)sailArea+","+
tack+
",1.8,2.5,"+ // these are always fixed values
llGetSubstring((string)(llGetVel().x),0,2)+","+ // llGetSubstring is used to shorten the message
llGetSubstring((string)(llGetVel().y),0,2)
);
However, if all boats would broadcast this every second or so, sailing would become very laggy. Builders are advised to reduce this interval to every 3 seconds.
Also, do not use llShout or llRegionSay for this!
Communication between boat and buoys
Each mark should broadcast its position to all boats in the neighbourhood using llShout on channel -8001 every 3 seconds. This way, boats that are competing in a race can use this information together with their own position and the positions of the other boats to implement ROW indication within the 2 shiplengths zone.
The message format is:
message type, (value = "Buoy") x coordinate (global x coordinate), y coordinate (global y coordinate)
Mooring protocol
This protocol describes how a boat could "dock" to a mooring buoy or similar device. Still to be defined.
