RFC 1221
Host Access Protocol (HAP) specification: Version 2
Host Access Protocol (HAP) Specification - Version 2 🎀 by W. Edmond of BBN, published April 1991 as RFC 1221 ✨ It updates RFC 907 💅
Status of This Memo 💌
okay so this memo is all about the Host Access Protocol as it's used in the Terrestrial Wideband Network (TWBNET) 🌸 It obsoletes most but not all of RFC 907, and it's purely informational 🧚 It's for the Internet community, not an Internet standard, so nobody's being forced into anything here. Distribution is totally unlimited, so share it with everyone 💜
Preface 🦋
so this memo specifies the Host Access Protocol (HAP) 💖 HAP is a Network layer access protocol (OSI Layer 3 lower) that was first implemented about a decade ago for the DARPA/DCA sponsored Wideband Packet Satellite Network (WBNET), which is basically the grandparent of today's Terrestrial Wideband Network (TWBNET) 🌈 This version obsoletes references [1] and [2] as well as most of RFC 907, so it's a whole glow-up ✨
HAP is a developmental protocol, which means it keeps getting revised as new capabilities show up and unused features get eliminated or reworked 🔥 One big reason for the revision right now is that the original WBNET used a satellite channel, which is a broadcast medium, but the TWBNET's T1 fiber links are not a broadcast medium 🙈 That totally changes things, so the protocol got some tweaks that allow for greater efficiency in a mesh topology network. Another reason is that HAP needed to support more OSI layer 3 upper protocols, like DECNET Phase V, ST, and CLNP, when before only Internet Protocol (IP) was used 💅 Appendix B explains how backward compatibility with the older IP-only version of HAP is achieved, so no one gets left behind 🫶
A third reason for the changes is the desire to make things simpler for ST2 protocol (RFC 1190) agents interacting with the TWBNET 💜 This mostly affected how certain setup errors are handled. These changes are expected to be backward compatible, which is the important part 😭 Appendix A describes two capabilities that may be added to HAP in the future, so keep an eye on that ⭐
Now, one of the enhancements from reference [2], called "Group Streams", has been eliminated 💀 There are no known applications that use the feature, so it's gone. As Appendix A describes, a new mechanism called "shared streams" will be implemented if needed, and it's capable of providing equivalent capabilities 🦋 The changes from [2] that were kept include various query/reply control messages that let a host figure out what resources it owns, which is mostly useful for cleanup after a host reboots or crashes 🧹✨
This document assumes the reader is familiar with DoD internetworking terminology 🎀
1. Introduction 🌸
okay bestie, HAP is a network layer protocol, same as X.25 💅 Here "network layer" means ISO layer 3 lower, which is the protocol layer below the DoD Internet Protocol (IP) layer [3] and above any link layer protocol 🧚 HAP defines the different types of host-to-network control messages and host-to-host data messages that may be exchanged over the access link connecting a host and the network packet switch node. It also establishes the formats for these messages and describes the procedures for deciding when each type should be sent and what it means when one arrives 💖
HAP has been implemented in the wide-area network called the Terrestrial Wideband Network (TWBNET) [5] and in the routers and other hosts that connect to TWBNET 🌈 The packet switch nodes that make up the TWBNET are called Wideband Packet Switches (WPS) ✨
Here's the history tea ☕ The precursor to HAP was the Host/SATNET Protocol [6], used in the Atlantic Packet Satellite Network (SATNET) and the Mobile Access Terminal Network (MATNET [7]). HAP itself was used in the original Wideband Satellite Network (WBNET) [8]. Both were originally designed to give efficient access to the single satellite channel each network used to connect all sites, and the HAP designers reflected some of the peculiarities of that single satellite channel environment right in the protocol 🛰️ The current TWBNET uses T1-speed fiber connections between sites instead. Future networks and TWBNET may combine terrestrial and satellite connections, and may have more than one of each, so HAP has been changed to accommodate these extensions 🔥
Section 2 gives an overview of HAP. The details of HAP formats and message exchange procedures are in Sections 3 through 10 🍓 For more on some of the topics in this specification, check out reference [1] 📚
One last thing 👑 Any protocol used to provide sufficiently reliable message exchange over the Host-WPS link is assumed to be transparent to the protocol defined in this document. Examples of such link-level protocols are ARPANET 1822 local and distant host [9], ARPANET VDH protocol [9], and HDLC 🫶
2. Overview ✨
okay so HAP is giving full duplex vibes 💅 meaning messages flow at the same time in both directions between the WPS and the host. 🦋 The transmission is nonreliable, which means the protocol does NOT promise error-free, in-order delivery 😭. If the host's access link needs error-free delivery, the link layer protocol underneath HAP has to handle it. (Using link layer protocols for that is outside the scope of this doc, bestie 🫶.) HAP's flow control works separately in each direction, but you can only turn it on or off for both directions together 🎀.
HAP does host-to-host communication in two modes, matching its two kinds of data messages: datagram messages and stream messages 🌸. Each one can be up to 2048 octets long 💖. The basic service in the network is datagram service. Datagrams are variable length, unsequenced, and independent, and delivery is not guaranteed 🧚. The HAP header of each datagram decides how that message gets processed ⭐.
On top of datagrams, there's a "stream" service 👑. Streams give you network bandwidth guarantees, but you have to do an explicit setup and teardown to allocate and deallocate network resources 💅. Streams are best for continuous media traffic, though you can also use them to get the lowest possible network delay ✨. A host stream gets established with a setup message exchange between the host and the network before any data starts flowing 🫶. You can change a stream's characteristics with later setup messages while it's in use, but the fixed allocation of streams (compared to datagrams) is kind of strict on the traffic source 😭. Stream arrivals have to match the stream allocation in both interarrival time and message size if you want reasonable efficiency 🍓. The details of datagrams and streams are in Sections 3 and 4 of this document, so go read those next 🌈.
Both datagram and stream transmission use logical addressing in the network 🦋. Every host gets a permanent 16-bit logical address, and it doesn't depend on which physical port of the WPS the host is plugged into 💜. These 16-bit logical addresses show up in every Host-to-WPS and WPS-to-Host data message 🎀.
HAP does multicast addressing through "groups" 💖. Multicast is mainly there to support the multi-destination delivery that conferencing apps need 📞. Group addresses get created and deleted dynamically through setup messages exchanged between a host and the WPS 🌸. A group's membership can be any arbitrary subset of the network hosts 🧚. A message sent to a group address goes to every host in that group, except the sender 💅. Once a multicast address exists, any member host can use it, not just the one who created it 👑.
Now, even though HAP doesn't guarantee error-free delivery, error control is still a big deal in this protocol design 😭🔥. HAP error control covers both local transfers between a host and its local WPS and transfers through the network to the destination(s) ✨. The WPS gives users a choice of network error protection options, based on the network's ability to selectively send messages over its transmission media at different forward error correction (FEC) rates 🦋. These FEC options are called reliability levels 💜. There are four reliability levels: low, medium-low, medium-high, and high 🌈. The precise error rate each reliability level gives you is not specified 🙈.
The network uses various checksum and CRC mechanisms to provide error detection 🎀. When a host sends a message, it gets a chance to say whether the message should be delivered or discarded if the network detects a data error 💅. Every message a host receives from the network has a flag that says whether an error was detected in that particular message 🫶. A host can decide, message by message, whether it wants to accept or discard transmissions that contain data errors 🍓.
If a host and WPS are close together, error rates from external noise or hardware failures on the access circuit should be much smaller than the best network trunk circuit error rates 🌸. So in that case, not much is gained from error detection and retransmission on the access circuit 🙄. A 16-bit header checksum is still provided, though, to make sure WPSen don't act on incorrect control information 🧚. For longer distances or noisy connections, retransmissions over the access circuit might be needed to optimize performance for both low and high reliability traffic ⭐. Link layer error control procedures (such as HDLC with retransmission) are expected to be used for this, but a reliable link layer protocol is not within the scope of this document 👑.
Each datagram message a host submits to the WPS is marked as being in one of three priority classes, from priority 2 (highest) down to priority 0 (lowest) 💖. The WPS uses the priority class to arbitrate contention for scarce network resources, like link bandwidth 💅. So if the network can't deliver every offered message, high priority messages get delivered before low priority ones 😭. Priority level affects the order of access to intersite link bandwidth and the order of message delivery at the destination WPS 🦋.
Each stream message also has three priority classes, from priority 2 (highest) to priority 0 (lowest) 🌈. Streams themselves also have three precedence classes, from precedence 2 (highest) down to precedence 0 🎀. A stream with higher precedence can preempt a stream with lower precedence at setup time 👑. Stream message priority lets a low-bandwidth host receive a high-bandwidth stream and pick which messages to drop, based on what the sender marked as less important 🫶. Stream message priority does NOT change the order of delivery of stream messages between source and destination 🙈.
Datagram and stream messages that a host hands to the WPS might not be accepted, for several reasons: priority too low, destination dead, lack of buffers in the source WPS, and so on 😭. The host has a similar situation when it handles messages coming from the WPS 💜. So to let a message's receiver tell the sender what happened to the message locally, there's an acceptance/refusal (A/R) mechanism 💅. The A/R mechanism is the outside view of the WPS's (or host's) internal flow and congestion control algorithm 🧚. If A/Rs are enabled, the WPS sends back an explicit or implicit acceptance or refusal for each message to the host (and the other way around too) 🌸. That lets the host (or WPS) retry refused messages whenever it wants, and when the reason for refusals is included, it can help optimize sending later messages 🍓. You can turn off the A/R mechanism for a "pure discard" interface 🙈. Choosing to use the A/R mechanism or not doesn't limit a host's ability to send and receive messages to any other hosts 💖.
The A/R mechanism controls individual message transfers, but it doesn't handle regulation of priority flows 🦋. That job goes to advisory status information (GOPRI), which gets passed across the Host-WPS interface to say which priorities are currently being accepted 🌈. As long as this information, along with changes in priority status, is passed often enough, the sender can avoid originating messages that are sure to be refused ⭐.
HAP defines both data messages (datagram messages and stream messages) and link control messages 🎀. Data messages carry information between hosts on the network 💅. Link control messages get exchanged between a host and the WPS to manage the local access link 🫶.
Allocating network resources, like streams and groups, happens through an exchange of datagram messages called Setups 👑. Setups go between the user host and an agent inside the WPS called the "Service Agent" 🧚. Setups are used to reserve, allocate, modify, free, and deallocate network resources ✨. Every allocated resource has a unique identifier, and when you put it in the right field of a message header, that message can use the resource 💜. For example, after a Setup exchange creates a group address, you can send a message to the group by putting the group address in the destination field of that message 🌸. The Service Agent also lets a host ask about resources it owns 🍓.
Every HAP message is made of an integral number of 16-bit words (so an even number of octets) 💖. The first several words of a message always hold control information, and they're called the message header 😭. The first word of the message header tells you what type of message follows 🦋. The second word is a checksum that covers all header information 🔥. Any message whose received header checksum doesn't match the checksum computed on the received header information MUST be discarded 💀. The format of the rest of the header depends on the specific message type 🌈.
The formats and use of each message type are detailed in the sections that follow, and they all use one common format description 🎀. Words in a message are numbered starting at zero, so zero is the first word of a message header 👑. Bits within a word are numbered from zero (most significant) to fifteen (least significant) 🫶. Here's the notation used to identify a particular field location 🧚:
<WORD#>{-<WORD#>} [ <BIT#>{-<BIT#>} ] <description>In that notation, optional elements in {} specify the (inclusive) upper limit of a range 💅. You should look at these field identifiers for precise field size specs 🍓. Fields common to several message types are defined in the first section that uses them, and after that, descriptions in later sections usually show only the field name ✨.
Link-level protocols that support HAP can differ in the order they transmit the bits that make up HAP messages 🙈. But the words of the message always get transmitted from word 0 to word N 🌸.
3. Datagram Messages ✨
okay so datagrams are one of the two message types HAP gives us, which we just went over 🫶 Here's the tea: network resources aren't reserved in advance for datagram traffic, so datagrams can face bigger delivery delays and delay variance than stream traffic. They're also subject to flow and congestion controls. Lowkey a lot of stress 😭
Datagram priority decides which packets get delivered or discarded when the network can't handle all the traffic that's showing up. It's expected that datagram messages will be used to support the majority of computer-to-computer and terminal-to-computer traffic which is bursty in nature. Bursty traffic, main character energy 💅
The format of datagram messages and the purpose of each header control field is shown in Figure 1 🎀
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
0 | 0|LB|GOPRI| 0 | F| MESSAGE NUMBER |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
1 | HEADER CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
2 | A/R |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
3 | 0|IL| D| E| PRI | TTL | RLY | RLEN |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
4 | DESTINATION HOST ADDRESS |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
5 | SOURCE HOST ADDRESS |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
6 | PROTOCOL ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| |
7-N : DATA :
| |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
DATAGRAM MESSAGE
Figure 1Now let's go field by field, because each one is a little button with its own job 🧚
0[0] is Message Class ✨ It tells you if this is a data message or a control message:
0 = Data Message
1 = Control Message0[1] is the Loopback indicator 🔁 It lets the sender check if its own messages are getting looped back. The host and the WPS each use different settings for their transmissions. If a message shows up with the loopback bit equal to its outgoing value, then yep, it got looped:
0 = Sent by Host
1 = Sent by WPS0[2-3] is Go-Priority 💖 In WPS-to-Host messages, this tells you the lowest priority the WPS is currently accepting. It's advisory info, so the host may optionally send similar priority info back to the WPS:
0 = Low Priority
1 = Medium Priority
2 = High Priority
3 = (Reserved.)0[4-6] is Reserved 🙈 Must be zero.
0[7] is also Reserved 🙈 Must be zero. It used to be for WPS diagnostic purposes, but that's old news now.
0[8-15] is the Message Number 🍓 This is the identification of the message used by the acceptance/refusal (A/R) mechanism, when it's enabled. If the message number is zero, A/R is disabled for that specific message. Check out Section 5 for the full A/R deets.
1[0-15] is the Header Checksum 🧮 It's the 2's-complement of the 2's-complement sum of words 0-6, not counting the checksum word itself.
2[0-15] is the Piggybacked A/R 🦋 This field may carry an acceptance/refusal word giving A/R status for traffic going the opposite direction. Including it may eliminate the need for a separate A/R control message (see Section 5). A value of zero for this word means there's no piggybacked A/R info present.
3[0] is the Data Message Type 🌸 It tells you whether the message is a datagram message or a stream message:
0 = Datagram Message
1 = Stream Message3[1] is the IL flag 🪦 It's obsolete and must be zero. (See Appendix B.)
3[2] is the Discard Flag 🗑️ This one lets a source host tell the network (including the destination host) what to do with the message when data errors are detected, assuming the header checksum is correct:
0 = Discard message if data errors detected.
1 = Don't discard message if data errors detected.The source host sets this value, and it gets passed on to the destination host ✨
3[3] is the Data Error Flag 🚨 This works together with the Discard Flag to tell the destination host whether any data errors were detected in the message before it went over the destination's WPS-to-Host access link. It's only used if Discard Flag = 1. The source host should set it to zero:
0 = No Data Errors Detected
1 = Data Errors Detected3[4-5] is Priority 🏃♀️ The source host uses this to specify the priority the message should get within the network:
0 = Low Priority
1 = Medium Priority
2 = High Priority
3 = (Reserved.)The destination WPS passes each message's priority along to the destination host 💅
3[6-7] is the Time-to-Live Designator ⏳ The source host uses this to set the maximum time a message should be allowed to exist in the network before it gets deleted. The clock starts when the WPS receives the message from the source host (or when a WPS agent sends it), and it's last checked when the message is queued for transmission out the I/O interface to the destination host. If a message is multicast, each copy is treated separately:
0 = 1 seconds
1 = 2 seconds
2 = 5 seconds
3 = 10 seconds3[8-9] is Reliability 🛡️ The source host uses this to say what basic bit error rate it needs for the data portion of the message. The source WPS uses this field to figure out the trunk circuit transmission parameters and the forward error correction level needed to hit that bit error rate:
0 = Low Reliability
1 = Medium-Low Reliability
2 = Medium-High Reliability
3 = High Reliability3[10-15] is the Reliability Length 👑 The source host uses this to mark a portion of the user data that should go out at the highest reliability level (lowest bit error rate). The HAP message header words and the first 2*<Reliability Length> octets of user data get sent at high reliability, while the rest of the user data gets sent at whatever level is set in field 3[8-9]. This is how the user can send private header info, like IP and TCP headers, at a higher reliability level than the rest of the data. Iconic ✨
4[0-15] is the Destination Host Address 📍 It holds the network logical address of the destination host.
5[0-15] is the Source Host Address 📮 It holds the network logical address of the source host.
6[0-15] is the Protocol ID 🧩 It specifies the next higher level protocol. Protocol identifiers are assigned administratively, except 0, which is reserved. They aren't part of this specification, so see reference [10] 📚
7-N is the Data field 📦 It holds up to 16,384 bits (2048 octets) of user data, and it must be an even number of octets.
4. Stream Messages 🎀
Okay bestie, stream messages are the second message type HAP gives us, as we covered back in Section 2 💅. Streams are all about guaranteed bandwidth between the source and the destination(s), plus the minimum delivery delay and delay variance the network can offer 🦋. That makes them perfect for volatile traffic like speech, and for high duty cycle apps that need throughput guarantees. Main character energy, literally ✨
Streams must be created before stream messages can flow from host to host 🌸. The protocol for stream creation is in Section 6.1. Once a stream is up, it gets specific network resources, like bandwidth. Within its stream allocation, a host has a lot of freedom in how it uses the stream 🫶. The time to live, reliability, and reliability length of each stream message are fixed at stream setup time, but the destination logical address can change from one stream message to the next 👑
So a host can multiplex a bunch of logical flows onto one stream, as long as that stream was set up to reach all the destination hosts 🧚. The layout of stream messages is shown in Figure 2 💜
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
0 | 0|LB|GOPRI| 0 | MESSAGE NUMBER |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
1 | HEADER CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
2 | A/R |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
3 | 1|IL| D| E| PRI | HOST STREAM ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
4 | DESTINATION HOST ADDRESS |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
5 | SOURCE HOST ADDRESS |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
6 | PROTOCOL ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| |
7-N : DATA :
| |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
STREAM MESSAGE
Figure 2Now let's break down each field, because the details matter, bestie 🔥
0[0]Message Class = 0 (Data Message). 💖0[1]Loopback indicator. 🪞0[2-3]Go-Priority. ⭐0[4-7]Reserved. 🔒0[8-15]Message Number. This one does the same job as the message number field in the datagram message 💅. Plus, a single message number sequence is shared by both datagram and stream messages (see Section 5) 🌈1[0-15]Header Checksum. (See datagram checksum for the description 🧾)2[0-15]Piggybacked A/R. 🎁3[0]Data Message Type = 1 (Stream). 🦋3[1]IL flag. Obsolete. It must be zero 🙈3[2]Discard Flag. 🗑️3[3]Data Error Flag. ❌3[4-5]Stream message priority. Heads up, all stream messages have priority over any datagram message 🔥 Priority won't change the order in which stream messages get delivered 💀 The values are:
0 = Low priority
1 = Medium priority
2 = High priority
3 = Reserved3[6-15]Stream ID. The WPS uses this field to find the preallocated network resources (bandwidth allocations, queues, buffers, etc.) it should use to deliver the message 🎀 Streams and their identifying numbers (stream IDs) get set up through an explicit Create Stream request (see Section 6.1) 🧚4[0-15]Destination Host Address. 📍5[0-15]Source Host Address. 🏠6[0-15]Protocol ID. 🪪7-NData. This field holds up to 16,384 bits (2048 octets) of user data, and it must be an even number of octets 🍓✨
5. Flow Control Messages ✨
okay so flow control is where HAP gets its whole acceptance/refusal (A/R) vibe 💅 The WPS supports an A/R mechanism in each direction on the host access link, and the host turns it on by setting a bit in the Restart Complete control message (see Section 8) 🎀
Every datagram and stream message carries an 8-bit message number so the message can be tracked for flow control 🦋 When A/R is enabled, the number goes up by one each message, wraps around modulo 256, and skips zero. Zero is the special "A/R is off for this one" value 🙈 Up to 127 messages can be outstanding (waiting on an acceptance or refusal) in each direction. If the receiver can't take a message, it sends back a refusal with that message's number and the reason why 💀 The refusal can ride along on data going the other way, or it can go in its own control message if there's no reverse traffic.
Acceptances work the same way, either piggybacked or in a separate control message 🫶 An acceptance just means the receiver got that message from the host access link and didn't refuse it. ngl, this part is important: WPS acceptances are not end-to-end acknowledgements. They don't promise the destination host(s) got anything, and they don't even promise the network won't intentionally drop the message 😭 They're mainly there to help the host manage its buffers.
To save on A/R traffic, one A/R indication can cover a bunch of older unacknowledged messages at once 🧚 Accepting message N implicitly accepts the outstanding messages N-1, N-2, and so on, following the acceptance definition above. Same energy for refusals: a receiver can reject a whole group together when they're all refused for the same reason 🍓 HAP also lets you mash any mix of A/R indications into one A/R control message 💜 Like, you could reject a bunch of messages where each one has a different refusal code. iconic.
Sometimes the overhead of processing A/R messages is just not it. In that case you can turn the A/R mechanism off and run the HAP interface in pure discard mode 🌸 You can do that per link, which we already covered (see Sections 2 and 8). Also, messages with sequence number zero are treated as ones where A/R is selectively disabled. And even in discard mode, HAP still wants critical feedback getting through, so it defines an "Unnumbered Response" control message 🔥 Flow control info, plus anything else that can't go out as an A/R indication, rides in an Unnumbered Response control message. Its format is in Figure 5.
Figure 3's format is used for A/R indications piggybacked on data messages (word 2), and for aggregated A/R info inside A/R control messages 🎀 The A/R control message format is in Figure 4.
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|AR| REFUSAL CODE | A/R MESSAGE NUMBER |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
ACCEPTANCE/REFUSAL WORD
Figure 3[0] Acceptance/Refusal Type. This field tells you whether the A/R info is an acceptance or a refusal ✨
0 = Acceptance
1 = Refusal[1-7] Refusal Code. When Acceptance/Refusal Type = 1, this field holds the Refusal Code 💖
0 = Priority not being accepted
1 = Source WPS congestion
2 = Destination WPS congestion
3 = Destination host dead
4 = Destination WPS dead
5 = Illegal destination host address
6 = Destination host access not allowed
7 = Illegal source host address
8 = Message lost in access link
9 = Invalid stream ID
10 = Illegal source host for stream ID
11 = Message length too long
12 = Stream message too early
13 = Illegal control message type
14 = Illegal refusal code in A/R
15 = Can't implement loop
16 = Destination host congestion
17 = Delivery refused
18 = Odd byte length packet (not allowed)
19 = Invalid stream time-to-live value
20 = "Reliability length" exceeds message length[8-15] A/R Message Number. This field is the number of the message this acceptance/refusal is about 🦋 It also covers every outstanding message with an earlier number. Note that this field can never be zero, because a message number of zero means the A/R mechanism is disabled 🙈
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
0 | 1|LB|GOPRI| 0 | LENGTH | 1 |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
1 | HEADER CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| |
2-N : A/R's :
| |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
ACCEPTANCE/REFUSAL MESSAGE
Figure 40[0] Message Class = 1 (Control Message). 🎀
0[1] Loopback indicator.
0[2-3] Go-Priority.
0[4-7] Reserved.
0[8-11] Message Length. This is the total length of the message in words (N+1) 💅
0[12-15] Control Message Type = 1 (Acceptance/Refusal).
1[0-15] Header Checksum. It's the 2's-complement of the 2's-complement sum of words 0-N, leaving out the checksum word itself 🧮
2[0-15] Acceptance/Refusal Word.
3-N Additional Acceptance/Refusal Words (optional). ✨
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
0 | 1|LB|GOPRI| 0 | RES-CODE | 5 |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
1 | HEADER CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
2 | RESPONSE INFO |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
3 | RESPONSE INFO |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
UNNUMBERED RESPONSE
Figure 50[0] Message Class = 1 (Control Message). 🌈
0[1] Loopback indicator.
0[2-3] Go-Priority.
0[4-7] Reserved.
0[8-11] Response Code.
3 = Destination unreachable
5 = Illegal destination host address
7 = Illegal source host address
9 = Nonexistent stream ID
10 = Illegal stream ID
13 = Protocol violation
15 = Can't implement loop0[12-15] Control Message Type = 5 (Unnumbered Response). 👑
1[0-15] Header Checksum. It's the 2's-complement of the 2's-complement sum of words 0-3, leaving out the checksum word itself 🫶
2[0-15] Response Information. If Response Code is:
3: Destination Host Address
5: Destination Host Address
7: Source Host Address
9: Stream ID (right justified)
10: Stream ID (right justified)
13: Word 0 of offending message
15: Word 0 of Loopback Request message3[0-15] Response Information. If Response Code is:
3,5,7, or 9: Undefined
10: Source Host Address
13: Word 3 of offending message, or 0 if no word 3
15: Word 2 of Loopback Request message6. The Service Agent ✨
Okay bestie, the Service Agent is the big boss of resource allocation 👑. Streams, groups, all of it gets handled by sending little datagram messages called Setup messages between your host and the Service Agent, which lives at network address zero 🦋. Setup operations cover reserving, allocating, modifying, freeing, and deallocating resources. The Service Agent makes the requested action happen and acts as the middle person between you and the rest of the network 💅. Along the way it updates the network databases so they reflect what the resource looks like right now. Hosts can also ask about resources they own using Information Request and Information Reply messages 🔍.
A setup interaction started by a host is a 3-way exchange 🤝. First, the requesting host sends a Setup Request to the Service Agent. Then the Service Agent sends back a Setup Reply. Last, the requesting host sends a Setup Acknowledgment to the Service Agent. This is how we make sure Setup Requests and Replies actually arrive 🫶. So that a host can have more than one Setup Request floating around at once, every Request gets its own unique Request ID. The Reply and the Acknowledgment that follow are matched up by the Request ID they carry 🎀. The requesting host should get a reply to a setup request within 3 seconds ⏰. The real wait depends on what the request is and how the network is laid out, but for simple networks it's often under one second. After getting a Reply, the requesting host should send back a Setup Acknowledgment within one second.
Setup exchanges started by the Service Agent are a two-way exchange 💌. The Service Agent sends a Notification to the hosts that are affected, and those hosts send back a Setup Acknowledgment. Notifications tell a host when the status of a network resource changes 🌈. To allow more than one Notification to be outstanding, each one gets a unique Notification ID. The Setup Acknowledgment that the notified host sends back must include that Notification ID. The host should respond within one second ⚡.
An information query is started by a host and is also two-way 🔍. The host sends an Information Request message to the Service Agent, and the Service Agent sends back an Information Reply. There's no acknowledgment mechanism here, because this request doesn't change any resource allocation 🙅♀️. If something is wrong with the request, only one response gets sent by the WPS, and the WPS won't try to check for or resend lost responses 💀. So it's on the host to wait a bit, decide that an unanswered information request got lost, and send it again 🫠. (The time needed to answer one of these is usually much less than one second.) The WPS returns the message ID of the information request in the information reply message 🧚.
The general format of every Service Agent message looks like this 🍓:
<DATAGRAM MESSAGE HEADER>
<SERVICE AGENT HEADER>
<MESSAGE BODY>The Protocol ID field in the datagram message header must be HAP_PROTO_SETUP (1) (see Appendix C) for messages sent to the Service Agent, and it will be HAP_PROTO_SETUP in messages received from the Service Agent 💜. The Service Agent doesn't recognize or support other higher level protocols (for example, IP) in setup messages, so it will throw away any message that has those headers 🙈.
The message format illustrations below only show the Service Agent Header and the message body. They leave out the datagram message header 🎀. To remind you of that, word offsets are prefixed with an "S" ✨.
The Service Agent Header is laid out in Figure 6 💖. The body depends on the type of message. Stream Request and Reply messages are in Section 6.1, and Group Request and Reply messages are in Section 6.2 🌸. Notifications are described in Section 6.3, Setup Acknowledgments in Section 6.4, and Information Request and Reply messages in Section 6.5 🦋.
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | MESSAGE TYPE | CODE |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | MESSAGE ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
SERVICE AGENT HEADER
Figure 6Here's how each field works 💅:
- S0[0-7] Message Type. This field tells you what kind of message it is:
0 = Setup Acknowledgment
1 = Setup Request
2 = Setup Reply
3 = Notification
4 = Information Request
5 = Information Reply- S0[8-15] Code. For Setup Requests, this field says which request type it is:
1 = Create group (multicast) address
2 = Delete group address
3 = Join group
4 = Leave group
5 = Create stream
6 = Delete stream
7 = Change stream
8 = Create shared stream
9 = Delete all streams owned by this host
10 = Add member to group
11 = Remove member from groupFor Setup Replies, this field holds the Reply Code. Some Reply Codes can come back for any setup request, and others are specific to a request 🎀:
0 = Group or stream created
1 = Group or stream deleted
2 = Host added to group
3 = Host deleted from group
4 = Stream changed
5 = (Reserved)
6 = Request type invalid or unsupported
7 = (Reserved)
8 = Network trouble
9 = Bad group key
10 = Group address/stream ID nonexistent
11 = Not member of group/not creator of stream
12 = Stream precedence not being accepted
13 = (Reserved)
14 = (Reserved)
15 = (Reserved)
16 = Unable to add all the new hosts
17 = Insufficient network resources
18 = Requested bandwidth too large
19 = (Reserved)
20 = (Reserved)
21 = Maximum messages per interval too small
22 = Reply lost in network
23 = Illegal priority or precedence value
24 = Invalid address providedFor Notifications, this field holds the Notification Type (see Section 6.3) 🔔. For Setup Acknowledgments, it holds the Acknowledgment Type (see Section 6.4) 💌. For Information Requests, it holds the request type (see Section 6.5) 🔍. For Information Replies, it holds the reply type (see Section 6.5) 🧾.
- S1[0-15] Checksum. The checksum is the 2's-complement of the 2's-complement sum of the words in the Service Agent Header (leaving out the checksum word itself) and the message body. Messages that come in with bad checksums must be discarded 🚫.
- S2[0-15] Message ID. The host assigns this field to uniquely identify outstanding requests (Request ID). The Service Agent uses it to uniquely identify outstanding notifications (Notification ID) 🪪.
6.1. Stream Setup Messages
Streams are how you reserve network resources for delivering traffic at a set maximum throughput to a specific list of recipients 🌊. Traffic sent over a stream gets priority over all non-stream traffic and is delivered with the least end-to-end delay possible ⚡. Hosts use streams for apps with predictable traffic loads (like packet voice, video, or other continuous media) or apps that need minimum transmission delay and the lowest delay variance 🎬. Streams are usually for traffic flows that last a moderate to long time, where the cost of a stream Setup is worth it 💅.
Streams have to be set up before stream data messages can flow 🚦. The stream setup messages each have a Request and a Reply. They are Create Stream, Delete Stream, Change Stream, and Delete All Streams. (Create Shared Stream Request is a planned future addition to the protocol 🔮.) Figure 7 shows how these messages get used in a scenario between a host and the Service Agent 🎞️. In it, the host sets up a stream, sends some data, changes the stream characteristics, sends some more data, and finally shuts the stream down. The optional A/R indications tied to each stream Setup message aren't drawn, but they're implied in this scenario 💜.
Service Other
Host Agent hosts
Create Stream Request ---------->
Create Stream Reply <----------
Reply Acknowledgment ---------->
Stream Messages --------------------->
: :
Change Stream Request ---------->
Change Stream Reply <----------
Reply Acknowledgment ---------->
Stream Messages --------------------->
: :
Delete Stream Request ---------->
Delete Stream Reply <----------
Reply Acknowledgment ---------->
STREAM EXAMPLE
Figure 7A stream has eight characteristic properties that get picked when it's set up 🎀. They are: (1) data words per time interval, (2) time interval, (3) reliability, (4) reliability length, (5) precedence, (6) maximum messages per interval, (7) the list of recipients, and (8) the set of other streams this stream shares resources with 🧩. To set up a stream, the host sends the Create Stream Request message (Figure 8) to the Service Agent 📨. After the network has handled the Create Stream Request, the Service Agent replies with a Create Stream Reply message (Figure 9) 📬. If the reply code in the Create Stream Reply says the stream was created successfully, the host may start sending stream data messages after it sends a Reply Acknowledgment 🥳✨.
okay so during a stream's lifetime 💖 the host that made it might decide some of its characteristic properties need a glow-up 🦋 Almost all of them can be changed with the Change Stream Request message (Figure 10). The one that's locked is whether the stream is willing to share its resources with other streams 🙅♀️. After the network processes the Change Stream Request, the Service Agent sends back a Change Stream Reply (Figure 11) to the host ✨.
Here's the lowkey important part 👀. If the host is asking for a reduced channel allocation, it should decrease its sending rate immediately, without waiting for the Change Stream Reply 💅. If it's asking for an increased allocation, it should not transmit with the new set of parameters until it has received a Reply Code showing that the requested change has taken effect 🫶.
When the host no longer needs its stream 🥹, it should first stop sending traffic through the stream, and then send the Service Agent a Delete Stream Request (Figure 12). After the network processes that, the Service Agent replies with a Delete Stream Reply (Figure 13) 🧚.
Now, if the host has crashed or restarted 😭, it might not remember what streams it owns. No stress though! It can use an Information Request (see Section 6.5) to find out what streams it owns, or it can use a Delete All Streams Request (Figure 14) to discard whatever stream resources it may own. The format for the Delete All Streams Reply is shown in Figure 15 🌸.
Heads up: streams, like all other resources allocated by the Service Agent, may be reclaimed by the network if unused. Currently, if no traffic is sent to a stream in a 6 minute interval, and if the owner of the stream is down or unreachable, the stream may be deleted. 🙈
Next up is the Create Stream Request, which is giving main character energy 👑.
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 1 | 5 |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S3 | MAX MES | PRE | INT | RLY | RLEN |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S4 | DATA WORDS PER INTERVAL |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S5 | INTERVAL |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S6 | 0 | ADDRESS LIST LENGTH |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| |
S7-SN : DESTINATION ADDRESS LIST :
| |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
CREATE STREAM REQUEST
Figure 8Here's how each field works 🎀:
S0[0-7]is Setup Type = 1 (Request).S0[8-15]is Request Type = 5 (Create Stream).S1[0-15]is the Setup Checksum. (See setup header description.)S2[0-15]is the Request ID.S3[0-3]is Maximum Messages Per Interval (1-15). This field specifies the maximum number of stream messages the host will deliver to the WPS in any single stream interval.S3[4-5]is Precedence. This field specifies the precedence of the stream. When there are insufficient network resources to support all the requested streams, requests for higher precedence streams will preempt existing lower precedence streams, and requests for streams with insufficient precedence will be rejected. Medium precedence is recommended as the default choice. Here are the options 💜:
0 = Low Precedence
1 = Medium Precedence
2 = High PrecedenceS3[6-7]is Interval. This field specifies the interval, in multiples of 21.22 milliseconds. (For backward compatibility only. New applications should use 3. Use of this field to specify an interval is being phased out.) The values are:
0 = 21.22 milliseconds
1 = 42.44 milliseconds
2 = 84.88 milliseconds
3 = use interval in word S5S3[8-9]is Reliability. This field specifies the basic bit-error rate requirement for the data portion of all messages in the stream. The exact error rate obtained by each choice is not specified. The choices are:
0 = Low Reliability
1 = Medium-Low Reliability
2 = Medium-High Reliability
3 = High ReliabilityS3[10-15]is Reliability Length. This field specifies how many words beyond the stream message header should be transmitted at maximum reliability for all messages in the host stream.S4[0-15]is Data words per interval. This field specifies the maximum number of 16-bit words of this stream's data the network will need to carry during each interval, not counting HAP stream message header words. The stream data may be carried in however many messages (up to MAX MES) in each interval the host chooses.S5[0-15]is Interval (125 microsecond units). This field specifies the time interval over which the <data words per interval> data in <max mes> messages will be sent. For backward compatibility, an interval of 0 selects an interval of 169.76 milliseconds. This field is ignored unless the INT field is 3.S6[0-7]is Reserved. Must be zero.S6[8-15]is Destination address list length. This field specifies the number of entries in the Destination Address List field. Allowed values are 1-8.S7-SNis the Destination address list. This list must specify, at least indirectly, all the intended recipients of this stream's traffic. At least one destination address must be supplied. Any valid network address, specifically including group addresses, may be used (except the Service Agent's address, 0). Messages sent in the stream are not limited to using the HAP addresses listed. E.g., if the list consists of only group address G, and host A is a member of G, a stream message may be sent to A, which was not in the list.
Caution: Group membership is only evaluated at setup time. Changes in group membership do not cause the stream to be modified.
Caution: Stream creation involves allocation of specific network resources along specific routes for delivery of that traffic. A stream message sent to hosts other than those specified via Setup will probably be undeliverable. A stream message to a group address that has gained new members since the stream's last Setup may be undeliverable to the new members. 💀
Now for the reply, the Create Stream Reply 🦋:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 2 | REPLY CODE |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S3 | 0 | STREAM ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S4 | 0 | ADDRESS LIST LENGTH |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| |
S5-SN : ADDRESS LIST :
| |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
CREATE STREAM REPLY
Figure 9And the fields 🧚♀️:
S0[0-7]is Setup Type = 2 (Reply).S0[8-15]is Reply Code. Any reply other than "Stream created" means the stream was not created.
0 = Stream created
8 = Network trouble
12 = Stream precedence not being accepted
17 = Insufficient network resources
18 = Requested bandwidth too large
21 = Max. messages per interval too small
22 = Reply lost in network
23 = Illegal precedence value
24 = Invalid destination address in listS1[0-15]is the Setup Checksum. (See setup header description.)S2[0-15]is the Request ID.S3[0-5]is Reserved. Must be zero.S3[6-15]is Stream ID. This field contains a stream ID assigned by the network. It must be included in all stream data messages sent by the host to allow the WPS to associate the message with stored stream characteristics and the resources reserved for that stream's traffic. ✨S4[0-5]is Reserved. Must be zero.S4[6-15]is Address list length. The number of entries in the Address List field.S5-SNis the Address list. This contains the destination addresses from the Create Stream Request that were invalid or unreachable. Unreachable destinations are listed as a group if every member of the group was unreachable, or individually otherwise; i.e., group addresses are expanded and the unreachable members are included in the list. The list of unreachable destinations will be truncated, if needed, to limit this Reply to a single, maximum length HAP message.
Okay bestie, so the Change Stream messages are next, and they're giving main character energy 💅✨ Here's the Change Stream Request layout:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 1 | 7 |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S3 | 0 | STREAM ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S4 | MAX MES | PRE | INT | RLY | RLEN |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S5 | DATA WORDS PER INTERVAL |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S6 | INTERVAL |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S7 | 0 | ADDRESS LIST LENGTH |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| |
S8-SN : DESTINATION ADDRESS LIST :
| |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
CHANGE STREAM REQUEST
Figure 10Here's what each little field is doing 🎀:
S0[0-7]is the Setup Type, set to1 (Request)💖S0[8-15]is the Request Type, set to7 (Change Stream)🦋S1[0-15]is the Setup Checksum. Check the setup header description for the details 🧚S2[0-15]is the Request ID 🌸S3[0-5]is Reserved, and itMust be zero.🙈S3[6-15]is the Stream ID 💜S4[0-3]is the New Maximum Messages Per Interval ⭐S4[4-5]is the New Precedence 👑S4[6-7]is the New Interval selection 🍓S4[8-9]is the New Reliability 🫶S4[10-15]is the New Reliability Length 🌈S5[0-15]is the New Data Words Per Interval 🔥S6[0-15]is the New Interval, and it's ignored unlessINT = 3💅S7[0-7]is Reserved, and itMust be zero.🌸S7[8-15]is the Destination Address List length. This tells you how many entries are in the new Destination Address List. Allowed values are0-8. Use zero (meaning no addresses in the list) if you don't want to change the list of recipient hosts 🦋S8-SNis the New Destination Address List. It's the new, complete list of recipient hosts. Group membership gets checked at setup execution time. Later changes in group membership don't change the stream. Also, reusing the same destination address list from the Create Stream Request can still change the list of recipient hosts if group membership has changed, so keep an eye on that 👀💀
Next up is the Change Stream Reply:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 2 | REPLY CODE |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S3 | 0 | ADDRESS LIST LENGTH |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| |
S4-SN : ADDRESS LIST :
| |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
CHANGE STREAM REPLY
Figure 11S0[0-7]is the Setup Type, set to2 (Reply)💖S0[8-15]is the Reply Code. The number in parentheses tells you which processing phase the error happened in (see the Caution below). Phase zero and phase one errors leave the stream unchanged. Errors from later phases might leave the stream partially modified 😭
4 = Stream changed
8 = (1) Network trouble
10 = (0) Stream ID nonexistent
11 = (0) Not creator of stream
12 = (0) Stream precedence not being accepted
16 = (3) Unable to add all the new recipients
17 = (2) Insufficient network resources
18 = (2) Requested bandwidth too large
21 = (0) Maximum messages per interval too small
22 = (2) Reply lost in network
23 = (0) Illegal precedence value
24 = (0) Invalid destination address in listS1[0-15]is the Setup Checksum. See the setup header description 🧚S2[0-15]is the Request ID 🌸S3[0-5]is Reserved, and itMust be zero.🙈S3[6-15]is the Address list length. It tells you how many addresses are in the Address List 💜S4-SNis the Address list. It holds the destination addresses from the Change Stream Request that were invalid (phase 0 errors) or unreachable (phase 3 errors). Unreachable destinations get listed as a group if every member of the group was unreachable. Otherwise they're listed individually. So group addresses get expanded, and the unreachable members show up in the list 🦋 The list of unreachable destinations will be truncated if needed, so the Reply fits in a single, maximum length HAP message 🫶
Caution: The Change Stream Reply will indicate failure if any aspect of the requested changes did not occur. But the stream may have been partially modified anyway, so be careful 🙈 Processing happens in these phases: 0: check for invalid requests; 1: drop former recipients that are not in the latest list; 2: increase or decrease the stream's bandwidth allocation (decreases are normally successful); then 3: extend the stream to any new recipients. If phase 2 fails, phase 3 doesn't happen. The Reply Code will show an error, and the stream parameters stay unchanged. If phase 3 fails, the Address List will contain the destinations (if any) from the latest list that the stream doesn't reach. Phase 1 only fails if the stream has been suspended (see Notifications) or the WPS is having network connectivity problems 💀
Now the Delete Stream Request:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 1 | 6 |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S3 | 0 | STREAM ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
DELETE STREAM REQUEST
Figure 12S0[0-7]is the Setup Type, set to1 (Request)💖S0[8-15]is the Request Type, set to6 (Delete Stream)🦋S1[0-15]is the Setup Checksum. See the setup header description 🧚S2[0-15]is the Request ID 🌸S3[0-5]is Reserved, and itMust be zero.🙈S3[6-15]is the Stream ID 💜
And the Delete Stream Reply:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 2 | REPLY CODE |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
DELETE STREAM REPLY
Figure 13S0[0-7]is the Setup Type, set to2 (Reply)💖S0[8-15]is the Reply Code. If the request was valid, the Service Agent has already marked the stream for deletion, even if the stream resources haven't actually been deleted yet 🫶
1 = Stream deleted
10 = Stream ID nonexistent
11 = Not creator of streamS1[0-15]is the Setup Checksum. See the setup header description 🧚S2[0-15]is the Request ID 🌸
Next, the Delete All Streams Request:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 1 | 9 |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
DELETE ALL STREAMS REQUEST
Figure 14S0[0-7]is the Setup Type, set to1 (Request)💖S0[8-15]is the Request Type, set to9 (Delete All Streams)🦋S1[0-15]is the Setup Checksum. See the setup header description 🧚S2[0-15]is the Request ID 🌸
And the Delete All Streams Reply:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 2 | REPLY CODE |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
DELETE ALL STREAMS REPLY
Figure 15S0[0-7]is the Setup Type, set to2 (Reply)💖S0[8-15]is the Reply Code. The Service Agent has marked all of the host's streams for deletion, even if the stream resources haven't actually been deleted yet 🫶
1 = Streams deletedS1[0-15]is the Setup Checksum. See the setup header description 🧚S2[0-15]is the Request ID 🌸
6.2. Group Setup Messages ✨
Okay so group (multicast) addressing is seriously iconic 🦋 It lets a host send the same message to N different hosts without having to send N copies. The network makes the duplicates as needed. This takes a load off the originating host. It also lightens the load on the network, because the network doesn't have to carry duplicates along the shared parts of the paths between the source and the destinations. Multicasting is especially recommended for multi-site conferencing and distributed simulations 💜🌈
Group addresses get created and deleted dynamically, through setup messages exchanged between the hosts and the Service Agent 🧚 Membership in a group can be any arbitrary subset of the network's hosts. A datagram message or stream message addressed to a group gets delivered to all hosts that are members of that group. (Exception: stream messages sent to a group address that includes hosts the stream wasn't set up to reach 👀.) The group setup messages each have a Request and a Reply. They are Create Group, Delete Group, Join Group, Leave Group, Add Group Member, and Remove Group Member 💅✨
okay so Figure 16 is the whole group-chat-in-protocol-form moment 🫶🎀 It follows three hosts and the Service Agent. Host A creates a group, and hosts B and C join it. Then they swap data messages using the group address. Heads up: multicast messages are not returned to their originator, so nobody sees their own message echoed back 🙈 After that, Hosts A and C leave, and Host B decides to delete the group, bye bye 👋 Same deal as the scenario in Section 6.1: the A/R indications got left out so the diagram stays clean ✨
Okay, the key part 🔑 When the group gets created, the Service Agent hands the creating host a 48-bit key along with the 16-bit group address. The creating host MUST pass the key along with the group address to any other hosts that want to join. And those hosts MUST supply the key with the group address in their Join Group Requests. The key is what the network uses to authenticate these operations, so unwanted hosts are much less likely to sneak in deliberately or by accident 💅 How the host actually spreads the group address and key around is outside the scope of HAP, so that part is on you, bestie 🧚
Here's the scenario in full, with the network Service Agent drawn as one single entity for simplicity:
Service Host Host Host
Agent A B C
Create Group Request |<-------|
Create Group Reply |------->|
Reply Acknowledgment |<-------|
: :
Distribute Group Adr & Key |---->|
Distribute Group Adr & Key |---------->|
: :
Join Group Request (C) |<-------------------|
Join Group Reply |------------------->|
Reply Acknowledgment |<-------------------|
Join Group Request (B) |<-------------|
Join Group Reply |------------->|
Reply Acknowledgment |<-------------|
: :
Data Message 1 (A to B and C) |---->|---->|
Data Message 2 (B to A and C) |<----|---->|
Data Message 3 (C to A and B) |<----|<----|
: :
Leave Group Request (C) |<-------------------|
Leave Group Reply |------------------->|
Reply Acknowledgment |<-------------------|
Leave Group Request (A) |<-------|
Leave Group Reply |------->|
Reply Acknowledgment |<-------|
Delete Group Request |<-------------|
Delete Group Reply |------------->|
Reply Acknowledgment |<-------------|
GROUP EXAMPLE
Figure 16There's also a second way to change who's in the group 🦋 Instead of only using Join Group, a host that's already a member can use Add Group Member and Remove Group Member to add or delete other hosts. Those setup requests are the ones that let existing members do the managing.
Here's the security tea ☕ The setup requests Join Group, Leave Group, Add Group Member, Remove Group Member, and Delete Group all get authenticated with that 48-bit key. Leave Group and Remove Group Member only take a host off the group membership list. They don't touch the group itself existing. Delete Group is the big one 💀 It wipes all knowledge of the group out of the network. HAP lets any host with the proper key delete the group at any time, so a group can get deleted even if the host that created it already left or crashed. Groups can also exist with zero current members, which happens when everyone has run a Leave and nobody has run a Delete. Coordinating and managing group addresses is the hosts' job, not the network's 🫶
Heads up: group addresses are like every other resource the network hands out. If nobody uses one for too long, the network can take it back. Right now, if there's no traffic sent to the group address in a 6 minute interval, the network MAY delete the group and tell all the members it no longer exists. Yikes, so keep the chat active 😭
Now the requests and replies, one by one 💅
A Create Group Request (Figure 17) is how a host establishes a multicast address. Once the network has processed it, the Service Agent sends back a Create Group Reply (Figure 18).
A host can become a member of a group once it knows the group address and the 48-bit key. It sends the Service Agent a Join Group Request (Figure 19), and the Service Agent answers with a Join Group Reply (Figure 20). The host that creates a group becomes a member automatically, so it never needs to send its own Join Group Request 🎀
A member host MAY add another host to the group by sending the Service Agent an Add Group Member Request (Figure 21). The Service Agent replies with an Add Group Member Reply (Figure 22).
Any time after joining, a host can bounce from the group. It sends the Service Agent a Leave Group Request (Figure 23), and the Service Agent replies with a Leave Group Reply (Figure 24) 🦋
One member can also expel another member by sending the Service Agent a Remove Group Member Request (Figure 25). The Service Agent replies with a Remove Group Member Reply (Figure 26).
Last but not least, a host can delete an existing group with a Delete Group Request (Figure 27). The Service Agent replies with a Delete Group Reply (Figure 28). It also tells any remaining members that the group has been deleted, if there are any (see Section 6.3) 🌈
Now let's look at the Create Group Request. Figure 17 is the layout:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 1 | 1 |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
CREATE GROUP REQUEST
Figure 17Here's what each field does ✨
S0[0-7]is Setup Type = 1 (Request).S0[8-15]is Request Type = 1 (Create Group).S1[0-15]is the Setup Checksum. (See setup header description.)S2[0-15]is the Request ID.
Next up is the Create Group Reply, Figure 18 🫧
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 2 | REPLY CODE |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S3 | GROUP ADDRESS |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S4 | KEY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S5 | KEY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S6 | KEY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
CREATE GROUP REPLY
Figure 18The field breakdown:
S0[0-7]is Setup Type = 2 (Reply).S0[8-15]is the Reply Code. Possible values:
0 = Group created
8 = Network trouble
17 = Insufficient network resources
22 = Reply lost in networkS1[0-15]is the Setup Checksum. (See setup header description.)S2[0-15]is the Request ID.S3[0-15]is the Group Address. This field holds the 16-bit multicast address that any group member MAY use to reach the other group members. The network assigns multicast addresses dynamically, so you don't pick them yourself ✨S4-S6is the Key. This field holds the 48-bit key the network assigns, which goes with the group address. It MUST be provided for later Join Group, Leave Group, Add Group Member, Remove Group Member, and Delete Group requests that reference the group address 🔑
Now the Join Group Request, Figure 19. This is where a host asks to join:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 1 | 3 |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S3 | GROUP ADDRESS |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S4 | KEY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S5 | KEY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S6 | KEY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S7 | 0 | MGP |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
JOIN GROUP REQUEST
Figure 19Here's the breakdown 🎀
S0[0-7]is Setup Type = 1 (Request).S0[8-15]is Request Type = 3 (Join Group).S1[0-15]is the Setup Checksum. (See setup header description.)S2[0-15]is the Request ID.S3[0-15]is the Group Address, the group the host wants to join. Once it successfully joins, the host MAY send messages to the group, and it will receive messages sent to the group when those messages have a priority of MGP or higher 💜S4-S6is the Key, the key associated with the group address.S7[0-13]is Reserved. It MUST be zero.S7[14-15]is the Minimum group message priority. The host will not receive messages sent to the group that have a message priority less than MGP. To change the minimum priority, send another Join Group Request message 🌸
And finally, the Join Group Reply, Figure 20 🦋
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 2 | REPLY CODE |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
JOIN GROUP REPLY
Figure 20And the fields:
S0[0-7]is Setup Type = 2 (Reply).S0[8-15]is the Reply Code. Possible values:
2 = Host added to group
9 = Bad key
10 = Group address nonexistent
17 = Insufficient network resourcesS1[0-15]is the Setup Checksum. (See setup header description.)S2[0-15]is the Request ID.
Okay bestie, the ADD GROUP MEMBER REQUEST is up first, and it is giving main character energy 🎀✨ Here's the layout:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 1 | 10 |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S3 | GROUP ADDRESS |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S4 | KEY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S5 | KEY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S6 | KEY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S7 | HOST ADDRESS |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
ADD GROUP MEMBER REQUEST
Figure 21Here's the breakdown 🫶
S0[0-7]is the Setup Type, and it's1(Request) 💅S0[8-15]is the Request Type, and it's3(Join Group) 🦋S1[0-15]is the Setup Checksum. (See the setup header description.) 🔐S2[0-15]is the Request ID 🌸S3[0-15]is the Group Address, which is the group the host will join. Once the host has successfully joined, it may send messages to the group and it will receive messages that other hosts send to the group. The initial minimum priority will be0💜S4-S6is the Key, which is the key associated with the group address 🗝️S7[0-15]is the Host address, which is the network address of the host you're adding to the group 🧚
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 2 | REPLY CODE |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
ADD GROUP MEMBER REPLY
Figure 22Now the ADD GROUP MEMBER REPLY, which is the answer to that request 🎀
S0[0-7]is the Setup Type, and it's2(Reply) 💖S0[8-15]is the Reply Code, and the options are:
2 = Host added to group (or was already a member)
9 = Bad key
10 = Group address nonexistent
11 = Requestor is not a member of the group
17 = Insufficient network resources
22 = Reply lost in network
24 = Host address was invalidS1[0-15]is the Setup Checksum. (See setup header description.) 🔐S2[0-15]is the Request ID, so you can match the reply to the right request 🌈
Next up is the LEAVE GROUP REQUEST, the "bye bye, I'm out" message 👋💀
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 1 | 4 |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S3 | GROUP ADDRESS |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S4 | KEY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S5 | KEY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S6 | KEY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
LEAVE GROUP REQUEST
Figure 23S0[0-7]is the Setup Type, and it's1(Request) ✨S0[8-15]is the Request Type, and it's4(Leave Group) 🍓S1[0-15]is the Setup Checksum. (See setup header description.) 🔐S2[0-15]is the Request ID 🌸S3[0-15]is the Group Address, which is the group the host wants to stop being a member of. After it leaves, the host stops receiving messages sent to the group and can't send to the group anymore 🥀S4-S6is the Key, which is the key associated with the group address 🗝️
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 2 | REPLY CODE |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
LEAVE GROUP REPLY
Figure 24S0[0-7]is the Setup Type, and it's2(Reply) 💜S0[8-15]is the Reply Code, and the options are:
3 = Host deleted from group
9 = Bad key
10 = Invalid group address
11 = Not member of group
17 = Insufficient network resourcesS1[0-15]is the Setup Checksum. (See setup header description.) 🔐S2[0-15]is the Request ID 🌈
Now the REMOVE GROUP MEMBER REQUEST, where someone else gets kicked out of the group, which is a whole mood 😭👑
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 1 | 11 |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S3 | GROUP ADDRESS |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S4 | KEY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S5 | KEY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S6 | KEY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S7 | HOST ADDRESS |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
REMOVE GROUP MEMBER REQUEST
Figure 25S0[0-7]is the Setup Type, and it's1(Request) 💅S0[8-15]is the Request Type, and it's4(Leave Group) 🦋S1[0-15]is the Setup Checksum. (See setup header description.) 🔐S2[0-15]is the Request ID 🌸S3[0-15]is the Group Address, which is the group the host should be removed from. After that, the host stops receiving messages sent to the group and can't send to it either 🫠S4-S6is the Key, which is the key associated with the group address 🗝️S7[0-15]is the Host address, which is the network address of the host to remove from the group 🧚
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 2 | REPLY CODE |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
REMOVE GROUP MEMBER REPLY
Figure 26S0[0-7]is the Setup Type, and it's2(Reply) 💖S0[8-15]is the Reply Code, and the options are:
3 = Host deleted from group (or was not a member)
9 = Bad key
10 = Invalid group address
11 = Requestor is not a member of the group
17 = Insufficient network resources
22 = Reply lost in network
24 = Host address was invalidS1[0-15]is the Setup Checksum. (See setup header description.) 🔐S2[0-15]is the Request ID 🌈
Last up is the DELETE GROUP REQUEST, the big "the whole group is gone" move 🥹💀
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 1 | 2 |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S3 | GROUP ADDRESS |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S4 | KEY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S5 | KEY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S6 | KEY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
DELETE GROUP REQUEST
Figure 27S0[0-7]is the Setup Type, and it's1(Request) ✨S0[8-15]is the Request Type, and it's2(Delete Group) 💅S1[0-15]is the Setup Checksum. (See setup header description.) 🔐S2[0-15]is the Request ID 🌸S3[0-15]is the Group Address, which is the multicast address to delete. If the group gets deleted, any remaining members of the group will be notified about the deletion 📣S4-S6is the Key 🗝️
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 2 | REPLY CODE |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | SETUP CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | REQUEST ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
DELETE GROUP REPLY
Figure 28S0[0-7]is the Setup Type, and it's2(Reply) 💜S0[8-15]is the Reply Code, and the options are:
1 = Group deleted
8 = Network trouble
9 = Bad key
10 = Invalid group address
17 = Insufficient network resources
22 = Reply lost in networkS1[0-15]is the Setup Checksum. (See setup header description.) 🔐S2[0-15]is the Request ID 🌈
6.3. Notifications ✨
Okay bestie, so Notifications are Setup exchanges where the WPS starts the chat 📣 to tell a host that something changed with a network resource. The Notification message format is in Figure 29 🎀
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 3 | CODE |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | NOTIFICATION ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S3 | NOTIFICATION INFO |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
NOTIFICATION MESSAGE
Figure 29Here's the breakdown 💅
S0[0-7]is the Message Type, and it's3(Notification) 🔥S0[8-15]is the Code, and it tells you what the Notification is about 👀0= Stream suspended1= Stream resumed2= Stream deleted3= Group deleted by a host4= Group deleted by network5= All streams deleted6= All groups deleted7= Group changed by a host8= Group changed by network
S1[0-15]is the Checksum. (See Service Agent Header description.) 🧚S2[0-15]is the Notification ID 🦋S3[0-15]is the Notification Information, and what's in it depends on the type 💜
For Notification types 0, 1, and 2, the NOTIFICATION INFO field has a stream ID in it:
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S3 | 0 | stream ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+For Notification types 3, 4, 7, and 8, the NOTIFICATION INFO field has a group address in it:
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S3 | group address |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+For Notification types 5 and 6, which refer to all streams or groups, NOTIFICATION INFO is zero 🌸
6.4. Setup Acknowledgments 🫶
So the host must acknowledge receipt of Setup Replies and Notifications from the Service Agent, like we talked about earlier 💖 The Setup Acknowledgment message is in Figure 30 ✨
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 0 | CODE |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | MESSAGE ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
SETUP ACKNOWLEDGMENT
Figure 30S0[0-7]is the Message Type, and it's0(Acknowledgment) 🍓S0[8-15]is the Code, which says what kind of acknowledgment it is0= Reply acknowledgment1= Notification acknowledgment
S1[0-15]is the Checksum. (See Service Agent Header description.) 💅S2[0-15]is the Message ID. It's either a Request ID or a Notification ID 🔥
6.5. Information Request / Reply Messages 🦋
Okay this one is so useful 😭 The host may ask the Service Agent for info about the WPS state and about what resources the WPS has already allocated to that host. You do this by sending an Information Request message, and the Information Reply that comes back lets the host figure out two things: 1) what resources the WPS has given it, and 2) the current state of the network and, possibly, some network parameters. This means the host can stop trying to use stuff it no longer has, and it can recover info it may have lost about its network resources. The reply also tells the host what the network looks like, so it can make priority and routing decisions 👑
Each Information Request (Figure 31) and Information Reply (Figure 32) message deals with one type of resource at a time 🌈 The header of the Information Reply has the number of entries in the message, the number of 16-bit words in each entry, and one instance of the right information structure for each resource the reply describes. Those structures are in Figures 33 and 34 🧚
Future versions of the HAP protocol might let you ask about network connectivity, the estimated delay to a given destination address under certain conditions, and more. This section is probably going to grow later on 🌸 Extensions are expected to stay backward compatible, as long as implementors don't hard code the size of the returned information entries ⭐
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 4 | CODE |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | MESSAGE ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
INFORMATION REQUEST MESSAGE
Figure 31S0[0-7]is the Message type, and it's4(Information Request) 🎀S0[8-15]is the Code, which identifies the Information Request Type1= streams owned by host2= groups to which the host belongs
S1[0-15]is the Checksum. (See Service Agent Header description.)S2[0-15]is the Message ID. The host picks this to uniquely identify outstanding requests (Request ID), and the Service Agent copies it into Information Replies 💜
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S0 | 5 | CODE |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S1 | CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S2 | MESSAGE ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
S3 | NUMBER OF ENTRIES | WORDS PER ENTRY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| |
S4-SN : ENTRIES (0 or more) :
| |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
INFORMATION REPLY MESSAGE
Figure 32S0[0-7]is the Message type, and it's5(Information Reply) 💖S0[8-15]is the Code, which identifies the Information Reply Type1= streams owned by host2= groups to which the host belongs3= error in Information Request message4= network trouble5= access not allowed
S1[0-15]is the Checksum. (See Service Agent Header description.)S2[0-15]is the Message ID. The host assigns it in the Information Request message to uniquely identify outstanding requests. The Service Agent copies it into the Information Reply message 🦋S3[0-7]is the Number of entries included in the Information Reply message 🌈S3[8-15]is the Number of 16-bit words per entry ✨S4-SNis zero or more instances of either the stream information or group information structure 🫶
The stream information structure looks like this 👇
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
0 | 0 | STREAM ID |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
1 | STREAM TYPE OF SERVICE WORD |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
2 | STREAM SIZE (bits per interval) |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
3 | STREAM INTERVAL (in units of 0.125 ms.) |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
STREAM INFORMATION
Figure 33And the group information structure looks like this 🧚
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
0 | GROUP ADDRESS |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
1 | 0 | MGP |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
GROUP INFORMATION
Figure 347. Host Access Link Monitoring 🦋
Okay bestie, now we're on link monitoring 👀 While the access link is up and running, the host and the WPS are both keeping stats on traffic load and error rate 📊 Once a second, they swap Status messages (Figure 35) 💌 Since it goes both ways, both ends can keep an eye on flows in each direction 🤝 The WPS also reports these numbers up to the Network Operations Center (NOC) 🏢 And if either the host or the WPS goes ten seconds without getting a Status message, the link gets restarted (see Section 8) 💀 that's a whole mood.
A link restart resets all of the WPS's internal counts and stats for that link back to zero 🧹 As messages get processed, the counts go up for messages sent, messages received correctly, and messages received with each class of error since the last link restart ✨ Whenever a Status message arrives, the WPS grabs a snapshot of its local counts 📸 The local receive counts, plus a sent count inside the incoming Status message, let you work out traffic stats for that one-second update interval, as long as the set of counts from the previous monitoring report was saved 🧠 And by putting the receive counts (plus the sent count that was used with them) into the Status message going the other direction, the transmitting end and the receiving end can both figure out the link performance from sender to receiver 🫶 iykyk.
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
0 | 1|LB|GOPRI| 0 | 0 |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
1 | HEADER CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
2 | MOST RECENT A/R SENT |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
3 | STREAM CAPACITY |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
4 | TIMESTAMP |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
5 | SBU |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
6 | STU |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
7 | RNE |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
8 | RWE |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
9 | BHC |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
10 | HEI |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
STATUS MESSAGE
Figure 35Here's the breakdown of the Status message fields, and honestly it's giving very organized 💅
0[0]Message Class = 1 (Control Message) 🎀0[1]Loopback indicator 🔁0[2-3]Go-Priority 🚦0[4-11]Reserved. This has to be zero 🧊0[12-15]Control Message Type = 0 (Status) 📬1[0-15]Header Checksum. The checksum is the 2's-complement of the 2's-complement sum of words 0-10 (excluding the checksum word itself) 🧮 math bestie activated2[0-15]Most Recent A/R Sent. This is a duplicate of the most recent acceptance/refusal word. It's included in the periodic Status message just in case earlier transmissions carrying A/R information got lost 🛟3[0-15]Stream Capacity. When sent by the WPS, this field shows how much stream capacity is unused, in units of data bits per millisecond. There's no guarantee that a request for a stream of this size will succeed 🙈 Available capacity depends directly on a bunch of parameters the user can select, so this value is the maximum capacity that could be reached if existing streams were expanded at low reliability. When it's sent from the host to the WPS, this field isn't meaningful and has to be set to zero 🚫4[0-15]Timestamp. This shows the time the Status message was generated. When a WPS sends it, the time is in units of seconds since the last link restart ⏱️ The host should also timestamp its messages in units of seconds 🕰️5[0-15]Sent By Us. The count of messages we've sent since the last link restart (not including this one) 📤6[0-15]Sent To Us. The count of messages sent to us since the last link restart. This is the count from word 5 of the last Status message received 📥7[0-15]Received, No Errors. The count of messages received without errors (since the last link restart) at the moment the last Status message was received ✅8[0-15]Received With Errors. The count of messages received with errors (since the last link restart) at the time the last Status message was received ❌9[0-15]Bad Header Checksums. The count of messages received with bad header checksums (since the last link restart) at the time the last Status message was received 💔10[0-15]Hardware Error Indication. The count of messages received with hardware CRC errors or hardware interface error indications (since the last link restart) at the time the last Status message was received 🔧
8. Initialization ✨
okay so the Host Access Protocol has a bunch of state variables that need to be set up before anything works 🧚. These are the ones tied to the send and receive message numbers for the acceptance/refusal mechanism, plus the stats used for link monitoring 📊. Link initialization happens when a machine first powers on, when it does a system restart, when the ON state times out, when a loopback condition times out (see Section 9), or whenever the link goes from non-operational to operational 💜.
Setup works through a little handshake of Restart Request (RR) and Restart Complete (RC) messages between a host and a WPS 🤝. Either end (or both!) can send an initial RR, but both ends have to have sent AND received an RC before the link counts as up 🔥. The RC is always a reply (to an RR or an RC), so when both ends get an RC, that proves the physical link works in both directions. Bestie, that's such a clean guarantee 😭🫶. The initialization state diagram (Figure 36) has to be implemented by both the WPS and the host, and there are five states in it:
- OFF 🌸: you land here when you realize you need to restart. The interface in the Host or WPS can notice that itself, or get forced into it when an RR shows up from the other end while you're in the ON state.
- INIT 🦋: your local state variables are set up, but no RC messages have been sent or received yet. If an RR kicked off the restart, or if any RR has come in since the restart started, you send an RC (optional, it just cuts down startup time ⚡). Otherwise you send an RR to tell the other end you're restarting.
- RR-SNT 📤: you've sent an RR to the other end, but you haven't gotten any RR or RC back yet.
- RC-SNT 🍓: you sent an RC in response to an RR, and now you're waiting to receive an RC.
- ON 👑: RC messages have been sent AND received. Local counters are zeroed, and data and control messages can finally flow between the WPS and the host 🎉.
Every state has a 10-second timeout (not drawn in the diagram) that sends the protocol back to OFF 😬. Any events that aren't in the diagram just get ignored, so no drama there 💅.
.-----.
Any Timeout or ----->| OFF |<----------------------------+
Device Down `--+--' |
| |
| (When I/O Device Up) |
V |
.-------. |
| INIT | |
`---+---' |
| |
(Yes) V (No) |
+---------RR Received?----------+ |
| | |
| Send RR |
| | |
| V |
| .--------. |
Send RC <-----+-------<--------+ RR-SNT | |
| | (Rcv RR) `---+----' |
| | | (Rcv RC) |
V | | |
.--------. | | |
| RC-SNT +--->--+ Send RC |
`----+---' (Rcv RR) | |
(Rcv RC) | | |
| | |
+------->------+-------<--------+ |
| |
Initialize Status Counters |
| |
V |
.-----. Rcv RR or |
Rcv Any +----->| ON +---------------------->------+
Other | `--+--' Fail to Rcv Status message
+---------+ for 10 seconds
HAP LINK RESTART STATE DIAGRAM
Figure 36The Restart Request control message (Figure 37) can be sent by either a host or a WPS when it wants to restart a link 🔄. An RR makes all the monitoring stats reported in the Status Message reset to zero, and it stops all traffic on the link in both directions 🛑. The Restart Complete message (Figure 38) is sent in reply to an RR or RC to finish link initialization ✅. The RC carries a field the host uses to turn the acceptance/refusal mechanism on or off for the link being restarted (see Section 5) 🎀. Once an RC has been processed, traffic can flow on the link 🌈.
Resources (streams and groups) are their own thing, separate from the state of the host's access link(s) to the WPS 🧠. A host can use the Information Request message (see Section 6.5) to check what resources it has. If the "SL" bit is set in the Restart Complete from the WPS, and the host thinks it has resources allocated, the host is strongly encouraged to send an Information Request to make sure it still has them 🫶.
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
0 | 1|LB| 0 |VERSION | 0 | 3 |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
1 | HEADER CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
2 | HOST ADDRESS |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
3 | LINK NUMBER |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
RESTART REQUEST
Figure 37Here's how the Restart Request fields break down 🍓:
0[0] Message Type = 1 (Control Message).
0[1] Loopback indicator.
0[2-4] Reserved. Must be zero.
0[5-7] HAP version number. Use 1. Use of zero invokes
backward compatibility code (see Appendix B).
0[8-11] Reserved. Must be zero.
0[12-15] Control Message Type = 3 (Restart Request).
1[0-15] Header Checksum. The checksum is the 2's-complement of
the 2's-complement sum of words 0-3 (excluding the
checksum word itself).
2[0-15] Host Address. The WPS inserts the primary network
address of the host. The host may insert any of its
network addresses in this field (hosts may have more
than one logical address per physical port). The WPS
will only bring up the HAP link if the host address is
valid for the port being used.
3[0-15] Link Number. This field contains the sender's
identification of the physical link being used. This
information is used to identify the link when reporting
errors to the Network Operations Center (NOC).Now for the Restart Complete 💖:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
0 | 1|LB| 0 |VERSION | 0 |SL|AR| 4 |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
1 | HEADER CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
2 | HOST ADDRESS |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
3 | LINK NUMBER |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
RESTART COMPLETE
Figure 38And the Restart Complete field details 🎀:
0[0] Message Type = 1 (Control Message).
0[1] Loopback indicator.
0[2-4] Reserved. Must be zero.
0[5-7] HAP version number. Use 1. Use of zero invokes
backward compatibility code (see Appendix B).
0[8-9] Reserved. Must be zero.
0[10] Service loss alert (boolean) (WPS to host only; host
must send zero). If the WPS has any reason to believe
that the resources allocated to the host may not match
what the host believes is allocated, SL is set to one.
If SL is one, a host that believes it owns any resources
is strongly encouraged to use an Information Request to
verify that the resources are still allocated. SL will
be one the first time a link is brought up after a WPS
is restarted, and may be set in other cases.
0[11] Acceptance/Refusal Control. This bit is used by the
host to enable or disable the acceptance/refusal
mechanism for all traffic on the link.
0 = Disable acceptance/refusal
1 = Enable acceptance/refusal
0[12-15] Control Message Type = 4 (Restart Complete).
1[0-15] Header Checksum. Covers words 0-3.
2[0-15] Host Address.
3[0-15] Link Number.9. Loopback Control ✨
okay so the Host Access Protocol gives you a Loopback Request control message 🔁 that a WPS or a host can send to ask the other side to loop back its HAP messages. this usually happens when an operator is poking around to figure out what's broken, so it's basically a diagnostic power move 🔍. to keep things clear, the unit asking for the loop is the "transmitter" 📤, and the unit that says yes (or no) is the "receiver" 📥.
when the host access link is remotely looped, every HAP message gets sent right back over the access link, unmodified 🪞. (messages that are too long to be valid HAP messages are allowed to get tossed instead of returned 🗑️.) the receiver doesn't send any of its own messages to the transmitter while the loop is running 🤐. WPS-generated messages and host-generated messages are told apart by the Loopback indicator that lives in every HAP message header 🏷️.
there are two kinds of remote loop you can ask for: a loop at the receiver's interface hardware, and a loop at the receiver's I/O driver software 🔧. HAP doesn't say how the receiver has to set these up 🤷♀️. some receivers might have interface hardware that can't loop the transmitter's messages at all, so they can only do software loops 💻. a receiver also might not be able to make sense of the transmitter's messages while it's looping them back 🤔. if it can interpret them, though, it still won't act on any of them except a request to reinitialize the WPS-host link, which is a Restart Request (RR) control message 🔄 (see Section 8.) 💖.
here's the promise part 🤝: when a receiver starts a loopback because someone asked, it's making an implicit promise to keep that loop going for the duration in the Loopback Request message. BUT if something unexpected happens, like a system restart on either the transmitter or the receiver 💥, the affected unit will try to reinitialize the WPS-host link by sending an RR message to the other unit. if the other unit recognizes that RR message, a link initialization sequence can finish, and that puts the link back to unlooped even if the loop duration hasn't run out yet 🙌. if a receiver can't interpret the transmitter's RR messages, then unless someone at the receiver steps in, the loop just stays put until its time is up 😬.
HAP doesn't specify what kinds of loopback conditions a unit can set up locally on its own 🏠. one example is when a WPS tells its host interface to loop back its own messages 🪃. if those local loops also end up reflecting messages that came from the remote unit, the remote unit can spot the loop through the Loopback indicator in the HAP header 👀.
setting up a remote loop has a specific order, and it MUST be followed 📋. it kicks off once the HAP link is initialized and somebody decides a remote loop is needed. the transmitter sends a Loopback Request message (Figure 39) to the receiver, then waits for one of three things: (1) a 10-second timer runs out ⏰, (2) a "Can't implement loop" Unnumbered Response message comes back from the receiver 🚫, or (3) one of its own reflected messages shows up 🪞. if (1) or (2) happens, the request failed, and the transmitter MAY try again with a brand-new Loopback Request message 🔁. if (3) happens, the remote loopback is established and we're in business 🎉. while it's waiting for one of those events, messages coming from the receiver still get processed normally 📨. just a heads up though: any RR messages that arrive from the receiver during this wait will end the loopback request 🛑.
when a receiver gets a Loopback Request message, it either sets up the requested loop for the specified duration, or it sends back a "Can't implement loop" response and leaves the link state alone 🙅♀️. that second option would happen if, say, the receiver just can't do the hardware loop it was asked for 🔩. a receiver SHOULD start reinitializing the link with RR message(s) whenever a loopback condition times out ⏳.
there's one asymmetry in the sequence above that is REQUIRED, and it handles the rare case where the WPS and the host both ask for a remote loop at the exact same time 👯. if a WPS gets a Loopback Request message from a host while the WPS is still waiting on one of the events (1) through (3), it sends back a "Can't implement loop" response to the host and keeps waiting 💪. a host in the opposite situation, though, will cancel its own loopback request and go with the WPS's loopback request instead 🫡.
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
0 | 1|LB|GOPRI| 0 | LOOP TYPE | 8 |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
1 | HEADER CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
2 | LOOP DURATION |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
LOOPBACK REQUEST
Figure 39here's how each field in the Loopback Request works 🧩:
0[0] Message Type = 1 (Control Message).
0[1] Loopback indicator.
0[2-3] Go-Priority.
0[4-7] Reserved. Must be zero.
0[8-11] Loop Type. This field indicates the type of loop that
is being requested as follows:
0 = Undefined
1 = Loop at interface (hardware loop)
2 = Loop at driver (software loop)
3-15 = Undefined
0[12-15] Control Message Type = 8 (Loopback Request).
1[0-15] Header Checksum. The checksum is the 2's-complement of
the 2's-complement sum of words 0-2 (excluding the
checksum word itself).
2[0-15] Loop Duration. The transmitter of a Loopback Request
message uses this field to specify the number of
seconds that the loop is to be maintained by the
receiver.(quick reminder on the bits: the Reserved bits at 0[4-7] MUST be zero 🔒. yes, the spec literally says so, no cap 💅.)
10. Other Control Messages 💅
before a WPS or a host voluntarily shuts down a WPS-host link, it SHOULD send at least one Link Going Down control message (Figure 40) over that link 📣. HAP doesn't define what a WPS or host should do when one of these comes in 🤷♀️. telling the Network Operations Center (NOC) and/or the network users about the upcoming outage is the typical move 📢. also, each Link Going Down message only applies to the WPS-host link it was sent over 🔗. so if a host and a WPS have multiple links between them, you can switch off just some of them and leave the rest running 🎛️.
a No Operation (NOP) control message (Figure 41) can be sent at any time by a WPS or a host ⏯️. a NOP message holds up to 32 words of arbitrary data that HAP leaves totally undefined 🎲. sometimes NOP messages are needed to clear out the state of the WPS-host link hardware 🧹.
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
0 | 1|LB|GOPRI| 0 | REASON | 7 |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
1 | HEADER CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
2 | TIME UNTIL DOWN |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
3 | DOWN DURATION |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
LINK GOING DOWN
Figure 40here's the breakdown for Link Going Down 📝:
0[0] Message Type = 1 (Control Message).
0[1] Loopback indicator.
0[2-3] Go-Priority.
0[4-7] Reserved. Must be zero.
0[8-11] Reason. This field is used by the WPS or the host to
indicate the reason for disabling this WPS-host link as
follows:
0 = Cancel previous notice, not going down
1 = Unspecified reason
2 = Scheduled PM
3 = Scheduled hardware work
4 = Scheduled software work
5 = Emergency restart
6 = Power outage
7 = Software breakpoint
8 = Hardware failure
9 = Not scheduled up
10 = Last warning: The WPS or host will disable
the link in 10 seconds
11-15 = Undefined
0[12-15] Control Message Type = 7 (Link Going Down).
1[0-15] Header Checksum. The checksum is the 2's-complement of
the 2's-complement sum of words 0-3 (excluding the
checksum word itself).
2[0-15] Time Until Down. This field specifies the amount of
time remaining until the WPS or host disables the link
(in minutes). An entry of zero indicates that there is
less than a minute remaining.
3[0-15] Down Duration. This field specifies the amount of time
that the WPS-host link will be down (in minutes). An
entry of zero indicates that the down duration will be
less than a minute. An entry of -1 (all bits set)
indicates an indefinite down duration.and now the NOP message, the chill one that can carry data 😌:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
0 | 1|LB| 0 | LENGTH | 6 |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
1 | HEADER CHECKSUM |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| |
2-N : ARBITRARY DATA :
| |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
NO OPERATION (NOP)
Figure 41and the field-by-field for NOP 🧾:
0[0] Message Type = 1 (Control Message).
0[1] Loopback indicator.
0[2-6] Reserved. Must be zero.
0[7-11] Length. The number of words of arbitrary data.
0[12-15] Control Message Type = 6 (NOP).
1[0-15] Header Checksum. The checksum is the 2's-complement of
the 2's-complement sum of words 0-N (excluding the
checksum word itself).
2-N Arbitrary Data. Up to 32 words of data may be sent.
The data are undefined by HAP.11. Appendix A -- Future Extensions ✨
okay bestie, this section is all about stuff that is NOT in HAP yet 🔮 These extensions are only here for context, so you can see what HAP can do today and how it could level up for multi-site conferencing. 💅 TWBNET does not support any of this rn.
One change being considered is a "conference" resource 🎀. It would own some number of streams and groups, and it would make the network way better at meeting the needs of video conference users. One request to modify the "conference", like adding a new member, would update all the streams in the conference to include that member, update the conference's primary group address to add them too, and so on, all in a single network operation 🙌 That's giving efficiency. Hosts would have an easier time managing conference resources, there would be fewer network setup operations, decisions about whether a conference modification is possible could be more nearly "atomic" 🦋, and recovery would be less of a mess if a modification can't happen.
Another change being considered is "shared streams." 🌈 This would let hosts share a single allocation of network bandwidth (and other resources) wherever the streams share a common communication path. Hosts using a shared stream must be willing to restrict their total transmission rate to the rate of the shared bandwidth. Multi-site conferences could use this to avoid allocating full bandwidth for voice data for every conference member. Instead, bandwidth for, say, four active voices at once could be allocated and shared, and voice messages would only be lost when more than four people tried to talk at once 🎤 literally the vibe.
The Create Shared Stream Request would use a different request code than Create Stream Request, and the setup message would likely contain at least one additional field to identify the set of shared streams. Change and Delete Stream requests could be used for both shared and non-shared streams ✨
12. Appendix B -- Backward compatibility 🕰️
okay so, the WPS is going to keep supporting HAP version 0 for hosts until every host has upgraded to version 1 🫶 The WPS figures out which HAP version a host is using by checking the Restart Request and/or Restart Complete control messages the host sends to the WPS. If the host starts a restart and sends both a Restart Request and a Restart Complete, and the HAP version numbers in those two messages don't match, the version number in the Restart Complete wins 👑 The WPS will always set the version number to 1. If the host sends 0 in the version number field, version 0 compatibility mode gets invoked.
Version 0 of HAP did not have the PROTOCOL ID field in the datagram and stream message headers 💀 Instead, the IL bit in the Type of Service word was used to say whether an Internet Protocol (IP) header (any version number) came after the HAP header. This is the original description of that bit:
3[1] Internet/Local Flag. This flag is set by a source host to
specify to a destination host whether the data portion of
the message contains an Internet Protocol (IP) header [3].
This field is passed transparently by the source and
destination WPSen for traffic between network hosts. This
field is examined by WPS Agents in order to support
Internet operation.
0 = Internet
1 = LocalConversion Algorithms
Link control messages (e.g., Restart Request) do not require conversion 🙈 Datagram and stream messages sent by or to a host running HAP version 0 will be converted by the WPS. Message conversion will probably make the maximum throughput of version 0 hosts a little lower than that of version 1 hosts.
HAP version 0 used the IL bit in the HAP Type of Service word to say whether an IP header was there. Version 1 uses the Protocol ID field instead 🦋 To convert host-to-WPS messages, the IL bit gets cleared, and the protocol ID field gets inserted with the value shown here:
IL was Destination Protocol ID set to:
------ ------------- ---------------------
0 any HAP_PROTO_IP (0x800)
1 Service Agent HAP_PROTO_SETUP (1)
1 other HAP_PROTO_NONE (0)To convert WPS-to-host messages, the protocol ID field gets deleted, and the IL bit gets set by:
IL = (protocol_id was HAP_PROTO_IP) ? 0 : 1;HAP_PROTO_IP (see Appendix C) will be used for IP "versions" 3 (GG protocol), 4 (IP), and 5 (ST).
The datagram message header fields TTL and PRI were swapped in HAP version 0 compared to version 1, so the conversion code swaps the contents of these two fields for version 0 hosts 🔄
The stream message header field TTL in HAP version 0 got replaced by the PRE field in version 1. Since the only permitted value of TTL was 1, and that's a valid PRE value, no conversion is needed ✅
In HAP version 0, messages between a host and the Service Agent were allowed to contain Internet Protocol headers. No hosts use that capability, so no provision will be made to fit IP headers into Setups between hosts and the Service Agent 💅
In version 0, the Restart Request control message had a "reason for restart" field. That field was ignored in all current implementations and has been removed in version 1 😭
Current implementations expect the WPS to insert an "incarnation count" in bits 5-10 of the first word of both Restart Request and Restart Complete messages. This has been replaced by the "SL" bit in the Restart Complete message in version 1 🧚 Compatibility code will be added if it's needed, but it's expected that none will be needed.
13. Appendix C -- HAP Protocol ID Assigned Numbers 🔢
this section lists the values of the PROTOCOL ID field. This part of the specification will become obsolete once a version of the Assigned Numbers RFC containing HAP protocol ID numbers is issued 📚
HAP adopts the Ether-type numbers in the 1500-65535 range. Protocol IDs 256-511 identify ISO protocols. Zero means there is no higher level protocol header. Other protocol IDs are reserved for future assignment 🌸
Protocol ID Indicates
----------- ---------
0 No higher level protocol
1 For Network Service Agent messages
2-255 Reserved
256-511 ISO protocol identifier + 256
512-1499 Reserved
1500-65535 Identical to Ether-type [10].
HAP PROTOCOL ID NUMBERS
Figure 42REFERENCES 📚
- Falk, G., Groff, S., Koolish, R., and W. Milliken, "PSAT Technical Report", BBN Technical Report No. 4469, Chapter 4, May 1981.
- Rees, T., Editor, "A Host Access Protocol Specification", BBN Laboratories, Inc., May 1987. (A revision of RFC 907 that was distributed to DARPA and the WBNET user community but not resubmitted as an RFC.)
- Postel, J., Editor, "Internet Protocol - DARPA Internet Program Protocol Specification", RFC 791, USC/Information Sciences Institute, September 1981.
- Topolcic, C., Editor, "Experimental Internet Stream Protocol, Version 2 (ST-II)", RFC 1190, Bolt Beranek and Newman, Inc., October 1990.
- Edmond, W., Seo, K., Leib, M., and C. Topolcic, "The DARPA Wideband Network Dual Bus Protocol", Proceedings of ACM SIGCOMM '90, pages 79-89, September 24-27, 1990.
- "Host/SATNET Protocol", Internet Engineering Note (IEN) 192, July 1981.
- Evenchik, L., McNeill, D., Bressler, R., Owen, A., Rice, Jr., R., Trout, G., Pavey, C., Damer, R., Deckelman, F., and T. Hughes, "MATNET, An Experimental Navy Shipboard Satellite Communications Network", Proceedings of INFOCOM '82, pages 3-11, March 30 - April 1, 1982.
- Falk, G., Groff, J., Milliken, W., Nodine, M., Blumenthal, S., and W. Edmond, "Integration of Voice and Data in the Wideband Packet Satellite Network", IEEE Journal on Selected Areas in Communications, Vol. SAC-1, No. 6, December 1983.
- "Interface Message Processor: Specifications for the Interconnection of a Host and an IMP", BBN Technical Report No. 1822, October 1980.
- Reynolds, J., and J. Postel, "Assigned Numbers", RFC 1060, USC/Information Sciences Institute, March 1990.
Security Considerations 🔒
This memo does not discuss security issues. Security issues are not discussed in this memo, so please take that seriously 🙏
Author's Address 📮
Winston Edmond
Bolt Beranek and Newman, Inc.
Network Technologies Department
10 Moulton Street
Cambridge, Massachusetts 02138
Phone: (617) 873-3000
EMail: wbe@bbn.com📦 where this page comes from
- ietf: rfc1221 1991-04
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms