Add LINKTYPE_FIRA_UCI and DLT_FIRA_UCI

[hchataing]

No description provided.

[mcr]

Same comment as in libpcap: this is not a publically available document. Is there a better reference? In the end, it's okay if we can't read the spec, but it's way better if we can.

[hchataing]

I will make some inquiries to see if the contents may be shared with non members. I am also annoyed by this 🙄

[mcr]

At least, if the redirect could go to something that acknowledges that the document exists, and asks one to login, at least a person would know that they were getting into. Perhaps there is a wikipedia page that abstracts what the protocol does.

[hchataing]

I will be talking to a FiRa board member this week, I will let you know what comes out of it.

[hchataing]

I will modify the note to mention that it is member only, and additionally link to the wireshark dissector implementation, if that's ok with you ?

[guyharris]

The Wikipedia page for the FIRa Consortium says that

The FiRa Consortium builds on to the IEEE 802.15.4/4z and future iterations and enhancements High Rate PHY (HRP) with an interoperable HRP standard that includes performance requirements, test methods and procedures, and a certification program based on the IEEE’s profiled features.

and that

In May 2020, the FiRa Consortium has released their first technical requirement specifications for the UWB PHY and MAC layers. Both specifications are based on the High Rate Pulse (HRP) portion of the IEEE 802.15.4-2015 technical specification and 802.15.4z/D8 draft amendment for fine-ranging UWB technology. The UWB MAC Technical Requirements defines elements such as how ranging protocol works, types of ranging that are supported, the parameters and format of the messages that are exchanged, and how ranging messages are encrypted. Similarly, the PHY Technical Requirements Specification document leverages select portions of the IEEE specification to facilitate interoperability between FiRa Consortium Certified UWB-enabled products.

So how does this differ from any of the other 802.15.4 LINKTYPE_/DLT_ values that we already have?

[guyharris]

Or is this more like the Bluetooth HCI, i.e. a standard interface between code on the host computer and an adapter? This message for a new Linux driver says

UCI mode (UWB Command interface)
Once Firmware download finishes sr1xx will switch to UCI mode packet
structure.Here this driver acts as pipe between user space and sr1xx.
Any response or notification received from sr1xx through SPI line
will convey to user space.User space(UCI lib) will take care of
UCI parsing logic.

And this chip description says

Communications between the host and the UWB IC aregoverned by a FiRa-standard UWB command interface (UCI)running over SPI.

so that's what it sounds like.

Give that there's a proposed Linux driver (open source) using UCI, and that there's your own Wireshark dissector, if FIRa won't make the spec public, could somebody just write up a separate spec based on existing open-source code, which we could put into the repository?

[hchataing]

UCI is the procotol used to communicate between the host and subsystem, it fills exactly the same role as HCI from the Bluetooth specification. The MAC and PHY specifications address the baseband protocol.

[hchataing]

You might use the dissector code that I am writing as reference : https://gitlab.com/wireshark/wireshark/-/merge_requests/6884.
Android is in the process of integrating an UWB stack, when that is complete you will also be able to reference the sources in aosp.

[hchataing]

The takeaway of my meeting with a FiRa board member : the UCI specification is not going to be made publicly available in the near future. We will have to do without...

[infrastation]

For clarity, who is the most interested party to get this protocol widely supported?

[guyharris]

The takeaway of my meeting with a FiRa board member : the UCI specification is not going to be made publicly available in the near future. We will have to do without...

I am in the process of taking the Wireshark dissector code and constructing a protocol document, along the lines of some of the other ones that are on the tcpdump.org Web site and that are linked to from the main link-layer types page.

We should put that document on the Web site and have the LINKTYPE_FIRA_UCI/DLT_FIRA_UCI entry point to it, rather than throwing the burden of reading and understanding the Wireshark code on the implementor of code to dissect that type; the latter is absolutely the wrong way to do it, as said implementor may not know anything about how Wireshark dissectors work and thus won't be able to understand the dissector code.

[hchataing]

uci_packets.md
Please use this document for reference (I had to change the extension to upload it). The syntax is described here.

[guyharris]

(I had to change the extension to upload it).

GitHub sux - at least when it comes to uploading attachments. It should really have a larger list of "this is text" extensions; I seem to remember having to rename a .c file to .c.txt for the same reason.

Adding ".txt" is probably the best solution, as it leaves the old extension, preserving at least some indication of the particular syntax used in the text file. ".md" suggests Markdown, which that document isn't.

The syntax is described here.

By which you presumably mean "The syntax is described here.".

Another packet description language to add to the list, along with WSGD and a bunch of others. Wireshark really needs built-in support for those, as well as at least some of the others, such as ASN.1, rpcgen, DCE RPC IDL, etc., preferably in a way that allows people to add protocol support without a compiler. tcpdump is a little trickier, as it doesn't just dump out the fields in a tree, the way Wireshark does for the packet details, but a way to express the sort of dissection that tcpdump does might also work for the packet summary line in Wireshark.

[hchataing]

I am in the process of taking the Wireshark dissector code and constructing a protocol document, along the lines of some of the other ones that are on the tcpdump.org Web site and that are linked to from the main link-layer types page.

Thanks a lot for your help :)

[hchataing]

@guyharris, is there anything I can do to help with the UCI link type documentation ?

[DeltaEvo]

Hello, is there a way to move forward with this ? Maybe updating the documentation in a latter PR when it's ready ?
As currently this is holding back the MR for Wireshark and it would be useful for UWB Developers to have support of this by default in Wireshark.
Thanks

[infrastation]

Thank you for waiting. It would look reasonable that if somebody wants to publish a protocol dissector, they would also publish the protocol description, otherwise how do the users know the dissector dissects the protocol right? This has been raised before, but not addressed yet. On a procedural note, after the most recent commit the next available value is 296 (hence the merge conflict, which needs to be resolved).

[DeltaEvo]

I totally agree with you and find a bit sad that this doc is not public in the first place. With @hchataing we are trying to make the required thing to make the consortium put this documentation public. However as this is a standardisation consortium things are moving slowly :(.

Personally I would prefer to not create a second source of truth for the protocol format as this could get in the way of the standardisation, but I may be biased here because I have access to it :/.

However I think there is a need to provide a standard format for UWB captures as currently Android was doing something custom and non standard on top of snoop logs for its capture and this would makes it harder for developers to use those debug informations.
And writing that I realise that we did a mistake as @hchataing replaced this custom format with a PCAPNG and I think this was merged with a wrong linktype.

[mcr]

Denis Ovsienko ***@***.***> wrote: Thank you for waiting. It would look reasonable that if somebody wants to publish a protocol dissector, they would also publish the protocol description, otherwise how do the users know the dissector dissects the protocol right? I would say that we strongly prefer to have reasonable LINKTYPE descriptions. But, there are types that people want to use tcpdump or wireshark with where the information is not public, and there is nothing we can do about that. (But, two layers of obfuscation down, there is an IP header...) That of course means that the support might break and be hard to fix, and we might say "screw this" later on.

[hchataing]

I will upload documentation for the packet header format (i.e. not documenting each command or response parameters).
Would that be sufficient for a start ? You will be able to review it as soon as I get approval from the lawyers...

[infrastation]

That would certainly be better than nothing, and hopefully sufficient for the purpose.

[hchataing]

I am adding documentation for the UCI packet framing and basic command groups.
For additional details I would need to go through validation, and I am not sure to which extent I can reproduce the original specification here. Please tell me if that is sufficient.

[hchataing]

Gentle ping :)

[DeltaEvo]

Another gentle ping :)

[DeltaEvo]

I really hate to ping another time, but it's blocking merging uwb support in wireshark and makes us to ship things with a wrong linktype, would it be possible to get an update if the current documentation is enough for you guys ?

[guyharris]

Have you told the people whose approval is required to make the document public that

1. it'll be a lot easier to get free-software packet capture and analysis support if they just make the document public;
2. if there are free-software packet analyzers, that information will be public anyway?

[hchataing]

I requested the specification to be made public using the same arguments that you have, but it was rejected.
They are not likely to budge on this issue in the short term...

[DeltaEvo]

For your second point @guyharris it's even worse than that, the whole AOSP UWB implementation is public and it contains even more information than a protocol analyser.

It contains things like the uci_packets.pdl file that we sent you previously that describe the whole protocol

And having the implementation public is allowed by the consortium, there is some logic that I'm missing here ...

Henri and I are totally convinced that this should be public, @hchataing reached out to our Google colleague that interact with the consortium and rised thoses issues to him. Maybe they will get addressed, but I feel that we did our best with this situation here :/

To be totally transparent to you guys, we don't even work on Android UWB, we work on Android Bluetooth. We are looking at UWB because of a side project https://github.com/google/pica which is a virtual UWB controller for testing (like btvirt but for UWB) and as a dev tool it's useful for it to capture and log packets, using an open packet capture format instead of doing our own is something that we value (here is the implementation with for now a wrong linktype)

And while working on that @hchataing noticed that the Android UWB stack did it's own custom format based on btsnoop logs and made the change to use pcapng to try to rectify that https://cs.android.com/android/_/android/platform/external/uwb/+/9957328eb898e65c7706cae529018073448c724d, unfortunately and it's totally our fault here ... using a wrong linktype :(

Would it be possible to get a linktype to let us fix that and use the correct one and unblock the Wireshark MR and continue the discussion of the closed documentation after that ?

[DeltaEvo]

Should be 297

[DeltaEvo]

Re-reading the conversation, we never answered @infrastation question

For clarity, who is the most interested party to get this protocol widely supported?

I would say the UWB consortium. But at the same time, for them having the documentation private means that to have access to it your company need to be a member, so it needs to pay 😞

I'm convinced that if it was public, the protocol adoption would be easier and the tooling of greater quality which in the end will bring members but I guess it's harder to see it that way 😞

[infrastation]

@hchataing and @DeltaEvo, you are not going to add a page with the new DLT description, correct?

[hchataing]

@infrastation Hi! the change already includes the documentation for the framing of the UCI packets. I don't think I will add the description of all the commands. Do you think that it will be enough ?

[infrastation]

You are right, there is the page, which I did not see for some reason, please excuse me. One thing in the document that does not look quite right is that big-endian applies to multi-byte integers, but not to bit fields, so a simpler way to achieve clarity could be a standard packet diagram for the first two bytes of the header. Does OID take the rightmost 6 bits in the 16 bits of these two bytes?

[hchataing]

You are right it is missing clarification. The byte order is little-endian, the big-endian in the packet header refers to the bit ordering, e.g. the OID takes the 6 least significant bits in the packet header. I will update the doc.

[hchataing]

@infrastation I updated the doc and the assigned number.

[infrastation]

Thank you. @guyharris, to me the most recent revision looks good enough as far as proprietary DLTs go, so if you don't mind, this will be merged soonish.

[infrastation]

This is now ready to be merged next, please shout before long if you see a good reason to stop.

[infrastation]

Hopefully the last question: since this is a proprietary DLT, who is the owner and the contact point? FiRa Consortium?

[hchataing]

The owner will be the Fira consortium, I can be the contact point.
Where is this information recorded ? How should I report a change in the future ?

[infrastation]

This is now code point 299. DLT_FIRA_UCI in libpcap pcap/dlt.h shows you as the contact person and in this repository LINKTYPE_FIRA_UCI.html states the payload specification is member-only, so I believe what could be done for this link-layer header type so far has been done. If you make any progress convincing FiRa Consortium to publish the specification, please remember to update the page. Thank you for waiting and good luck with your project.