writing a profile guide: products part 1

docs/writing-a-profile.md

@@ -78,11 +78,63 @@ profile.parseLine = createParseLineWithoutFoo
 	- Add a function `transformReqBody(body)` to your profile, which assigns them to `body`.
 	- Some profiles have a `checksum` parameter (like [here](https://gist.github.com/derhuerst/2a735268bd82a0a6779633f15dceba33#file-journey-details-1-http-L1)) or two `mic` & `mac` parameters (like [here](https://gist.github.com/derhuerst/5fa86ed5aec63645e5ae37e23e555886#file-1-http-L1)). If you see one of them in your requests, jump to [*Appendix A: checksum, mic, mac*](#appendix-a-checksum-mic-mac). Unfortunately, this is necessary to get the profile working.
 
-todo: products/modes
+## 3. Products
+
+In `hafas-client`, there's a difference between the `mode` and the `product` field:
+
+- The `mode` field describes the mode of transport in general. [Standardised by the *Friendly Public Transport Format* `1.0.1`](https://github.com/public-transport/friendly-public-transport-format/blob/1.0.1/spec/readme.md#modes), it is on purpose limited to a very small number of possible values, e.g. `train` or `bus`.
+- The value for `product` relates to how a means of transport "works" *in local context*. Example: Even though [*S-Bahn*](https://en.wikipedia.org/wiki/Berlin_S-Bahn) and [*U-Bahn*](https://en.wikipedia.org/wiki/Berlin_U-Bahn) in Berlin are both `train`s, they have different operators, service patterns, stations and look different. Therefore, they are two distinct `product`s `subway` and `suburban`.
+
+**Specify `product`s that appear in the app** you recorded requests of. For a fictional transit network, this may look like this:
+
+```js
+const products = {
+	commuterTrain: {
+		product: 'commuterTrain',
+		mode: 'train',
+		bitmask: 1,
+		name: 'ACME Commuter Rail',
+		short: 'CR'
+	},
+	metro: {
+		product: 'metro',
+		mode: 'train',
+		bitmask: 2,
+		name: 'Foo Bar Metro',
+		short: 'M'
+	}
+}
+```
+
+Let's break this down:
+
+- `product` should contain a sensible, [camelCased](https://en.wikipedia.org/wiki/Camel_case#Variations_and_synonyms), alphanumeric identifier. Use it for the key in the `products` object as well.
+- `mode` should be a [valid *Friendly Public Transport Format* `1.0.1` mode](https://github.com/public-transport/friendly-public-transport-format/blob/1.0.1/spec/readme.md#modes).
+- HAFAS endpoints work with a [bitmask](https://en.wikipedia.org/wiki/Mask_(computing)#Arguments_to_functions) that toggles the individual products. `bitmask` should toggle the appropriate bit(s) in the bitmask (see below).
+- `name` should be a short, but distinct name for the means of transport, *just precise enough in local context*. In Berlin, `S-Bahn commuter rail` would be too much, because everyone knows what `S-Bahn` means.
+- `short` short be the shortest possible symbol that identifies the product.
+
+todo: `defaultProducts`, `allProducts`, `bitmasks`, add to profile
 
 If you want, you can now **verify that the profile works**; I've prepared [a script](https://runkit.com/derhuerst/hafas-client-profile-example) for that. Alternatively, [submit Pull Request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/) and I will help you out with testing and improvements.
 
-## 3. Additional info
+### Finding the right values for the `bitmask` field
+
+As shown in [the video](https://stuff.jannisr.de/how-to-record-hafas-requests.mp4), search for a journey and toggle off one product at a time, recording the requests. After extracting the products bitmask ([example](https://gist.github.com/derhuerst/193ef489f8aa50c2343f8bf1f2a22069#file-via-http-L34)) you will end up with values looking like these:
+
+```
+toggles                     value  binary notation  subtraction      bit(s)
+all products                255    11111111         255 - 0
+all but ACME Commuter Rail  127    01111111         255 - 2^7        2^7
+all but Foo Bar Metro       191    10111111         255 - 2^6        2^6
+all but product C           223    11011111         255 - 2^5        2^5
+all but product D           239    11101111         255 - 2^4        2^4
+all but product E           243    11110011         255 - 2^3 - 2^2  2^3 & 2^2
+all but product F           253    11111101         255 - 2^1        2^1
+all but product G           254    11111110         255 - 2^0        2^0
+```
+
+## 4. Additional info
 
 We consider these improvements to be *optional*: