 Thanks everyone for attending so this session is going to be about the I3C 802-154 layer in the Linux kernel. So I'm Mikkel, I recently got involved into the WPAN subsystem on a project with Corvo trying to bring more support for the Mac management commands in the Linux kernel. So I'm going to stop this presentation with a go through the specification just to give a little bit of context what I'm trying to achieve and how and then I'll go through the Linux kernel stack how it's currently managed and maybe at the end I'll try to do the demo if I have enough time. So here is a a short picture that shows where the specification brings something in the system so you have the kind of an OZ model on the right so the specification brings two layers the fee layer and the data link layer fee and Mac. So this was first introduced to create low power, low range and low rate networks typically you have several devices to connect you want them to be battery powered if possible the devices will usually just wake up send a bit of data a few bytes and then go back to sleep. So that's what you use in home automation, infrastructure monitoring and there are other fields that are listed in the specification as being the target for this document. We usually have above the ZigBee applications or the ZigBee network thing is using those two layers as is the six-slope one layer as well was using those two layers and anything is built on top of them. So the fee layer well the fee has several things to handle like changing the channels of course it can perform energy detection scans so space it is sensing on a channel if there is someone that is talking you don't really listen at what's being sent on the on this channel. The medium access of course so the main algorithm I think is a CSMA CA so carrier sense multiple access collision avoidance so you try to avoid collisions with some algorithms that's one of the different algorithms that are available in the spec but quite common of course you can transmit and receive packets when you receive packets you have access to an indicator which is the link quality indicator the LQI the LQI gives you the basically the strength the signal strength with the well that defines the device in front of you and the physical data encoding of course there are many algorithms again you can possibly perform running as well so only on ultra wide band fees and finally you basically get some data from the upper layer so namely the MAC layer and you can you have to encapsulate it into a fee protocol data unit a ppdu with a header and a synchronization here what's inside the payload of the fee frame is defined there so the the MAC sublayer which is above has actually two kind of services one of the two services is a data service so just sending the data forwarding the data by encapsulating the payload that was received into a MAC frame so that's named the mpdu the MAC protocol data unit and this MAC frame contains a frame control field at the beginning this is a field that defines the frame for the peer so basically it says what type of frame it is if it's an acknowledgement if it's a data frame if it's a MAC command whatever and it also defines the other fields that are present in this in this frame because almost all what you see here is optional and it depends on the type of frame and the how you configure it so a good example would be the address fields you have a source field a destination field both of them can be present or not and within those address fields you can have extended addressing or short addressing so you have to define in the frame control field what's to be expected at the end you have the frame check sequence the fcs which is a basically a to buy checksum usually on the other side of course you have the MAC management services which goes through what we call the mlme the MAC sublayer management entity the MAC sublayer management entity offers different services like is my mic still working yes okay yeah okay perfect i was also hearing myself back so from the MAC layer you have to choose the channel of course that you want to well you tell the file please send change the channel and the frame validation is supposed to happen at MAC level as well the all the network management features such as scanning, beconning, associating, the associating is also handled at this by this entity there are some security mechanisms as well which I want to talk about and the acknowledgements are also part of the MAC layer in the field you'll find two types of devices so the reduced function devices which are pretty limited devices just battery powered the sensors usually the leaf nodes in the network they have very few computational resources and try just to connect to another peer that has more resources and more power usually which are the full function devices so a full function device may either act as a leaf node as well or as a coordinator and a coordinator is meant to have more features is supposed to to help managing the network so it provides more synchronization services than a regular leaf node so coordinators well any device can connect to a coordinator which makes in the end a network which we call a personal area network the pan one device has at some point to create a network so this one will become the pan coordinator there is only one pan coordinator in a network it can then give the hand to another device which might have more computational resources or maybe a better internet connection as well but well that's how it starts so the pan coordinator will take a will pick a pan id so it's a 16 bit value and a short address so that short address is only valid on this particular pan it will then advertise the pan through the beacons it might decide to send and possibly allow the associations from other devices to create a bigger network this works thanks to the discovery mechanism which uses beacons so beacons are very short frames they have no destination field it's a frame that tells the other nodes around i am a coordinator i am part of this pan so you give the pan id and if you want to reach me i'm available at this address so the other nodes around either lift nodes or other coordinators well yeah will receive those beacons process them and build a list of the available nodes around there are two kind of ways of advertising a pan either by sending beacons at a regular rate so it's called a creating a beacons enabled pan or by just answering beacons requests so if you want to join let's say you are a pretty you don't have a lot of battery you just want to wake up perform a few exchanges and then go back to sleep you might either decide to wait for a beacons if there is any or if you want an immediate beacons you can send a beacons request on the channel you're on and all the coordinators around which are already part of a pan should in theory answer you with a beacon so you can basically perform three types of what we call a scan so the energy detection scan is just to sense the channel and that's all the passive scan which expects a beacon to arrive at some point and the active scan where you actually send a beacon request you'll get thanks to the beacon reception and link quality indicator which gives you the strengths of the signal with a pair with a coordinator which helps you building the network like you have on the right side figure you might or you might see on this figure several numbers on the edges those are the LQIs between all the nodes so you know which coordinator might be the closest to you for instance so why do we why would we want to create beacon enabled fans in the first place and I think the main answer would be that it helps saving battery at least the lift nodes can save more battery because you expect beacons to be sent at a given rate this rate is advertised in the in the beacon frame actually and as a lift node you would expect the next beacon in a very short time frame so you can just wake up at that moment that's when all the devices may try to access the medium and send their data so they are there are time slots you can try to access the medium during the contention aware period which is right after the beacon after the contention aware period there is a contention free period this is reserved for specific critical and low latency devices which might request a guaranteed time slot a gts and after those slots there is an inactive portion so the during the inactive portion all the devices should just turn off the radio perhaps start sleeping and this active and inactive those two portions are actually configurable there is a beacon order which is a number between zero that ranges from 0 to 15 or 14 and same for the superframe duration superframe order so those orders will increase exponentially the time of the two periods and you can that way tune the amount of inactive time and the amount of active time between the the beacons another feature is the hardware filtering this is actually useful if you don't want to be woken up if you don't want your transceiver to wake your host every time a new pack a new packet gets received so you can set in hardware your extended address your short address your plan idea as well and you'll also receive the broadcast messages and basically what's not matching the frames that are not matching those parameters will just get dropped by hardware so you don't get interrupted for nothing provided of course that you've successfully tuned your hardware filters otherwise you might lose some frames most transceivers are capable of at least having no filtering at all on one side and full filtering with the addresses on the other side there is in the specification two intermediate levels one of them is called the promiscuous mode which in the specification is defined as a mode that just checks the frame integrity but if you look at code in the Linux kernel in particular the Linux WPAN community and I see Stefan laughing has decided that it will not be like that so in the Linux kernel when you see promiscuous mode that actually means that there is no filtering at all because the promiscuity was meant to be used for devices that would act as sneakers so you really want all the frames to go there even those which are badly constructed or may have a wrong checksum so in order to build those those networks you need a number of MLME operations which are the discovery of the surrounding devices so this implies scanning on one end and beconning on the other end enlarging and shrinking the network which implies associating and disassociating keeping all the devices synchronized may be done through the beacon enabled pan feature and the acknowledgments and finally handling all the faulty situations that might arise which I will detail a bit after as well so those are the main Mac management commands that you'll find in the spec so let's go through them one by one what does all of them imply for the scan so this is an MLME request you have from the soft Mac layer to stop all the transmissions you want all the transmissions to be over before you actually send your your MLME request or your your your MLME frames so you turn your you change your filtering level as well because now you want to only receive becons during a scan we no longer process any data frame no any command Mac command we only process the becons so there is something to tune at the filtering level you need to provide of course the list of channels that you want to scan because a scan usually goes from one channel to the other and you have to wait a given amount of time on each of them so the amount of time is the beacon order that you can provide that you should have should be able to provide and upon reception of a beacon of course you need to pass the frame extract the the the address of the coordinator it's pan ID and we retrieve as well the LQI indicator associations work this way any device in the system including coordinators may try to associate with coordinators or the pan coordinator as well so the peer will send an association request the coordinator that receives the request should immediately acknowledge the request this is time critical then it has some time to decide whether or not it wants the device to be associated this the an association response is then sent back to the peer the association response contains a status so either the the device was accepted or the the pan was at capacity you will reach the maximum number of devices or you just simply don't want this device to to join so there are two error codes that can be provided if the peer requested a short address on this pan which is not mandatory the spec says that if the device is too limited it can just refuse the the short address and in that case you would return 0x fffe which is a standard which is a placeholder of saying this this device doesn't have any short address otherwise the the coordinator should allocate one on the pan and send it to the to the peer in the association response these associations can be done from both sides so the coordinator may tell a child that it's been kicked out of the network at any moment and the child itself may also leave if it if it's its desire and in both case of course you the address filters should be updated on the peer side because you no longer want to get the frames from the the pan if any the conflicts that may arise are called pan id conflicts so there are two situations that may lead to a pan id conflict one of them is your pan coordinator you receive a beacon in this beacon there is a bit saying that the beacon has been emitted by the pan coordinator and this bit is set meaning there is another device on the same pan id on the same network that says i am the pan coordinator which might happen if maybe the devices move and get in range at some point well that that's possible so this is a situation where that is not acceptable for the the pan controller that received the beacon and an action should be taken another situation where this could arise is maybe having a node in between two other coordinators there the the pan ids are 16 bit values so you have more than 65 000 possibilities but it's possible that two controllers have decided to create pan with the same pan id they don't get the beacons they are not in range but the device in the middle might receive the beacons from both of them so it is associated with one pan coordinator and it receives a beacon from the other pan coordinator saying oh i am also the the pan coordinator which cannot work so in that case the device should send an a conflict notification to its own pan coordinator which then should take an action in that case the concerned pan coordinator might need to sense the network so sense all the channels find a huge a new channel that is not used and a pan id that is also unused on this channel and send to all its children a coordinator realignment command the devices upon reception of this command should follow the coordinator change their channel and pan id and continue working on another channel and another pan id of course what may happen as well uh device may lose the synchronization with the coordinator so maybe it doesn't receive any more acknowledgement from its coordinator or maybe he didn't receive the coordinator realignment command because it was asleep i don't know or not in range at that moment so if it was associated it may try to do something that looks like a scan but instead of sending beacon requests it will go through all the channels and send orphan notifications until the coordinator receives the notification and immediately answers with a coordinator coordinator realignment command saying yes i recognize you you can still be part of the network otherwise the device should have to just forget about the pan and start a new association with after another scan so let's now switch to the link kernel stack here is my beautiful figure trying to picture how it's built in the linux kernel hopefully you can you can see uh so um let's uh start from the bottom i have the bottom you have the hardware hardware it's on silver with a phy the phy uh so you can have several files on the device but it's not really common so i use the simple situation where you only have one the phy is described in software by a w pan phy structure uh this structure is there is a one-one mapping with the the actual hardware okay but then from the mac layer you can create several sub interfaces on a single phy so each sub interface will actually be given a role the three roles that are now available well in the past we only had node and monitor and with my recent contributions we should now soon be able to create coordinator sub interfaces as well so a node is just a device in the network that acts like leaf node basically the monitor is the sniffing device so uh during the the demo i will try to set up a monitor interface on one of my three uh at usb's and i will open wire shack to show you what happens on the network while the others are talking but this one will remain silent on the network of course and the last possibility is being a coordinator which is something new and the coordinator uh can also send the beacons which is uh uh which is something new and possibly in the future have may maybe more features as well a sub interface contains a w pan device structure this w pan device structure actually belongs to the i3c 802 154 layer where we have a cfg layer that kind of makes the link between the net link layer and the uh mac implementation so right now in the linux kernel we only have a soft mac implementation which is the left most side uh we might have at some point a hard mac driver which would interfere in the interface with the cfg layer in that case right now we have an hard mac a single hard mac device in the linux kernel that is supported but it's been wired through the soft mac layer so it's it's a bit specific i explained at the beginning that some of the features were um that the the file had some uh some duties on the mac as well in practice some of the mac duties are offloaded to the to the hardware and are not performed by software uh typically the frame validation and the acknowledgements uh well the for the frame validation you read as i said you don't want to be interrupted too frequently so it's best if you just want to receive frames from your own well that are targeted to you to set the filters properly so that uh you're only interrupted when it's needed and for the acknowledgements uh this would be hard to support in software because we have uh because this operation is time critical as i said so uh we need the acknowledge well we need the frame that must be acknowledged to go through the address filters because we only want to answer frames that are targeted to us then this frame should have the acknowledgement request bit enabled in the frame in the mac frame and also the the the the hardware should be configured to answer those those frames if everything is right then the acknowledgement frame is automatically sent back so the current implementation in the Linux kernel well the one before uh my huge pile of patches didn't allow the the dynamic discoveries we couldn't create coordinators there was no beckoning uh beckoning feature possible at that time so you would have to create your network beforehand to set up an id a static pan id and hopefully it would work on the field but of course this is a bit limiting so we prefer to be able to create a network directly in the field and have those dynamic uh interactions between the different devices so that's what those commands are made for so the first interface that has been brought was of course the scanning interface and there is a netlink command for that the netlink command takes a the type of scan that should be performed if it's a passive scan an active scan energy detection scan are not yet supported then the range of channels possibly as well the page and the beacon order that so that's the time you want to wait on each channel this request will be processed by the netlink layer and forwarded to the mac layer which will actually perform the the scan by stopping the traffic wait for the transmission queue to be flushed and well basically create a background job that will do the channel changes and wait on each of the channels and this background thread should also even possibly send beacon requests if you are performing an active scan and in all cases wait for the incoming beacons until we receive the beacons we check of course they validity and we forward them directly to the to the upper layers so that the user now has full access to all the data that's been received the user can stop those the scan feature at any moment and a when the the scan stops or is is aborted or stops naturally the information is also sent to user space to notify user space that the scan is over and the interface is set back to in its original state the beacon interface works more or less the same you need to provide a duration the maximum duration that you can provide is 15 so below 15 you are actually providing a real beacon order which will change the the beacon interval if you provide 15 it it actually means please only answer the beacon request so by default a coordinator in the Linux channel will not send any beacons if it's a coordinator interface you can allow the beacons to be sent by using this command and either you provide a number below 15 and this will send beacons at a given rate or you give 15 and only the beacon request will produce the emission of a beacon this is also handled in the background job and you may change the the beacon order at runtime here you have the new commands in the IAWPAN tool so there is a WPAN tool repository for the user space tool it's based well the idea is based on the IW tool for wireless devices so this one is just for the WPAN subsystem you can now start a scan of course the scan the first command will start the scan and show you the results while they arrive and then return the the the command will end when the scan is over otherwise scan trigger will just trigger the scan return immediately if you want to follow you can look at the netlink socket with IWPAN monitor for instance which will show you what happens on the socket if new beacons are being received or not you can abort the scan and of course on the other side so the other coordinator that advertises its own pan you can start sending beacon or stop sending beacon basically after scanning you know what are the coordinators around so you can decide to send you can decide to associate with the device so you the user might decide might choose the the coordinator with the highest LQI the so the link quality indicator and the the while a netlink command is also involved on the mac side a an association request will be sent we expect an acknowledgement that was a a problem to while while developing this this feature because we missed this information in the past and we then wait for the association response past this response and update our our address filters accordingly that was a trick there because the address filters had to be updated at least with the pan id before sending the association request because the association response will be targeted to this pan id so the pan id field the pan id value would be within the destination field of the association response and the processing of the association request is very simple either you so we added a new parameter which is basically the number of devices that you allow to connect that can be tuned with a netlink command as well otherwise for now i've decided to make it simple and always allow the associations this will not be enough and we would need at some point to forward the request to user space because this is not so time critical and let the user space decide whether or not it wants to allow to associate with the device with this device on the disassociation notification side it's very simple just a notification so the netlink command gives the pan id and the coordinator address that you want to reach to send this this this association not only the there is no pan id involved here just the the address so here are the new commands as well the association associate command disassociate command the list association command will show you your both the parent and the child devices and the set max associations will also give you well allows to set a maximum number of devices that you may want to associate in the network so here are the patches if you want to check out this work and may want to try home i strongly advise you to check out the github repository instead of the patches on the mailing list because i have like 60 or 70 patches ongoing only the first 10 patches also are sent at new in each new iteration i've also played with a zeffir device that you have here so this is an arduino nano ble that runs the zeffir stack just to see if they were operating together i had a few issues with that so there are some patches that are being discussed on the on zeffir github but otherwise it's more or less work now so we can we can scan the devices running the linux stack on one side and associate with them and also send a disassociation command from both sides i have five minutes so i'm gonna do a short demo let's first i hope you can read yeah um so let's first set up the the monitor interface so that's just setting a channel we can show just setting a channel creating a monitor interface and setting it up on the other side i'm gonna start wire shack just to show you the various freak the various frames all right so it's gonna be here we are we first set the same channel on the two remaining at usb devices so the devices that are here they are all running the same linux stack we create a coordinator interface on one of them the other one will be a leaf node this coordinator gets a pan id and a short address i will then perform a scan so this is a passive scan i'm only scanning two channels just to make it quicker while the so the leaf node will perform a scan while the coordinator itself will send beacons once this has been done i will stop sending beacons passively there i will change the beacon order to 15 meaning please only answer beacon beacon request to not pollute the wire shock output the on the then you have when after scanning you have the extended the extended address so you can perform an association we will list the associations and then perform a dis association and again list those so first those are the the interfaces it performs a scan you have the kernel log on the right it finds a pan coordinator a coordinator sorry which advertises pan number two we can associate with it so now we have when we list the associations on both sides one has a child the other has a parent and then we can finally do associate and we have no longer associations between the two i could as well use the zefir device so i've just enabled the interface here i can perform an active scan which finds the the device running the linux stack and now i can associate with this device as well and on one side i have the zefir device saying okay i'm associated on the other side i can see the association was successful as well and i can finally show the wire shock output where we have first the three beacons that were sent then and i say i'm sorry it's a little it's small small you you have to trust me now so there is an association request here an acknowledgement the response an acknowledgement then the disassociation notification well everything that i've sent is visible on wire shock we could also on the association response for instance if it was big enough i would show you that we can see the short address that was allocated to the to the device and that's all for me do you have any questions you you can use well it creates the the interface that gets created is visible under ip l or ip a and you can use it to send data as well yes i fear there are no ways for now that's indeed something that we've discussed a little bit internally that would be very nice to have both being connected together but i think there is no interface yet short answer no well we are running out of time so thank you very much everyone