Commit | Line | Data |
---|---|---|
8e4a0740 SS |
1 | =============================== |
2 | IEEE 802.15.4 Developer's Guide | |
3 | =============================== | |
4 | ||
5 | Introduction | |
6 | ============ | |
7 | The IEEE 802.15.4 working group focuses on standardization of the bottom | |
8 | two layers: Medium Access Control (MAC) and Physical access (PHY). And there | |
9 | are mainly two options available for upper layers: | |
10 | ||
11 | - ZigBee - proprietary protocol from the ZigBee Alliance | |
12 | - 6LoWPAN - IPv6 networking over low rate personal area networks | |
13 | ||
14 | The goal of the Linux-wpan is to provide a complete implementation | |
15 | of the IEEE 802.15.4 and 6LoWPAN protocols. IEEE 802.15.4 is a stack | |
16 | of protocols for organizing Low-Rate Wireless Personal Area Networks. | |
17 | ||
18 | The stack is composed of three main parts: | |
19 | ||
20 | - IEEE 802.15.4 layer; We have chosen to use plain Berkeley socket API, | |
21 | the generic Linux networking stack to transfer IEEE 802.15.4 data | |
22 | messages and a special protocol over netlink for configuration/management | |
23 | - MAC - provides access to shared channel and reliable data delivery | |
24 | - PHY - represents device drivers | |
25 | ||
26 | Socket API | |
27 | ========== | |
28 | ||
29 | .. c:function:: int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0); | |
30 | ||
31 | The address family, socket addresses etc. are defined in the | |
32 | include/net/af_ieee802154.h header or in the special header | |
33 | in the userspace package (see either http://wpan.cakelab.org/ or the | |
34 | git tree at https://github.com/linux-wpan/wpan-tools). | |
35 | ||
36 | 6LoWPAN Linux implementation | |
37 | ============================ | |
38 | ||
39 | The IEEE 802.15.4 standard specifies an MTU of 127 bytes, yielding about 80 | |
40 | octets of actual MAC payload once security is turned on, on a wireless link | |
41 | with a link throughput of 250 kbps or less. The 6LoWPAN adaptation format | |
42 | [RFC4944] was specified to carry IPv6 datagrams over such constrained links, | |
43 | taking into account limited bandwidth, memory, or energy resources that are | |
44 | expected in applications such as wireless Sensor Networks. [RFC4944] defines | |
45 | a Mesh Addressing header to support sub-IP forwarding, a Fragmentation header | |
46 | to support the IPv6 minimum MTU requirement [RFC2460], and stateless header | |
47 | compression for IPv6 datagrams (LOWPAN_HC1 and LOWPAN_HC2) to reduce the | |
48 | relatively large IPv6 and UDP headers down to (in the best case) several bytes. | |
49 | ||
50 | In September 2011 the standard update was published - [RFC6282]. | |
51 | It deprecates HC1 and HC2 compression and defines IPHC encoding format which is | |
52 | used in this Linux implementation. | |
53 | ||
54 | All the code related to 6lowpan you may find in files: net/6lowpan/* | |
55 | and net/ieee802154/6lowpan/* | |
56 | ||
57 | To setup a 6LoWPAN interface you need: | |
58 | 1. Add IEEE802.15.4 interface and set channel and PAN ID; | |
59 | 2. Add 6lowpan interface by command like: | |
60 | # ip link add link wpan0 name lowpan0 type lowpan | |
61 | 3. Bring up 'lowpan0' interface | |
62 | ||
63 | Drivers | |
64 | ======= | |
65 | ||
66 | Like with WiFi, there are several types of devices implementing IEEE 802.15.4. | |
67 | 1) 'HardMAC'. The MAC layer is implemented in the device itself, the device | |
68 | exports a management (e.g. MLME) and data API. | |
69 | 2) 'SoftMAC' or just radio. These types of devices are just radio transceivers | |
70 | possibly with some kinds of acceleration like automatic CRC computation and | |
71 | comparation, automagic ACK handling, address matching, etc. | |
72 | ||
73 | Those types of devices require different approach to be hooked into Linux kernel. | |
74 | ||
75 | HardMAC | |
76 | ------- | |
77 | ||
78 | See the header include/net/ieee802154_netdev.h. You have to implement Linux | |
79 | net_device, with .type = ARPHRD_IEEE802154. Data is exchanged with socket family | |
80 | code via plain sk_buffs. On skb reception skb->cb must contain additional | |
81 | info as described in the struct ieee802154_mac_cb. During packet transmission | |
82 | the skb->cb is used to provide additional data to device's header_ops->create | |
83 | function. Be aware that this data can be overridden later (when socket code | |
84 | submits skb to qdisc), so if you need something from that cb later, you should | |
85 | store info in the skb->data on your own. | |
86 | ||
87 | To hook the MLME interface you have to populate the ml_priv field of your | |
88 | net_device with a pointer to struct ieee802154_mlme_ops instance. The fields | |
89 | assoc_req, assoc_resp, disassoc_req, start_req, and scan_req are optional. | |
90 | All other fields are required. | |
91 | ||
92 | SoftMAC | |
93 | ------- | |
94 | ||
95 | The MAC is the middle layer in the IEEE 802.15.4 Linux stack. This moment it | |
96 | provides interface for drivers registration and management of slave interfaces. | |
97 | ||
98 | NOTE: Currently the only monitor device type is supported - it's IEEE 802.15.4 | |
99 | stack interface for network sniffers (e.g. WireShark). | |
100 | ||
101 | This layer is going to be extended soon. | |
102 | ||
103 | See header include/net/mac802154.h and several drivers in | |
104 | drivers/net/ieee802154/. | |
105 | ||
106 | Fake drivers | |
107 | ------------ | |
108 | ||
109 | In addition there is a driver available which simulates a real device with | |
110 | SoftMAC (fakelb - IEEE 802.15.4 loopback driver) interface. This option | |
111 | provides a possibility to test and debug the stack without usage of real hardware. | |
112 | ||
113 | Device drivers API | |
114 | ================== | |
115 | ||
116 | The include/net/mac802154.h defines following functions: | |
117 | ||
118 | .. c:function:: struct ieee802154_dev *ieee802154_alloc_device (size_t priv_size, struct ieee802154_ops *ops) | |
119 | ||
120 | Allocation of IEEE 802.15.4 compatible device. | |
121 | ||
122 | .. c:function:: void ieee802154_free_device(struct ieee802154_dev *dev) | |
123 | ||
124 | Freeing allocated device. | |
125 | ||
126 | .. c:function:: int ieee802154_register_device(struct ieee802154_dev *dev) | |
127 | ||
128 | Register PHY in the system. | |
129 | ||
130 | .. c:function:: void ieee802154_unregister_device(struct ieee802154_dev *dev) | |
131 | ||
132 | Freeing registered PHY. | |
133 | ||
134 | .. c:function:: void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, u8 lqi): | |
135 | ||
136 | Telling 802.15.4 module there is a new received frame in the skb with | |
137 | the RF Link Quality Indicator (LQI) from the hardware device. | |
138 | ||
139 | .. c:function:: void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, bool ifs_handling): | |
140 | ||
141 | Telling 802.15.4 module the frame in the skb is or going to be | |
142 | transmitted through the hardware device | |
143 | ||
144 | The device driver must implement the following callbacks in the IEEE 802.15.4 | |
145 | operations structure at least:: | |
146 | ||
147 | struct ieee802154_ops { | |
148 | ... | |
149 | int (*start)(struct ieee802154_hw *hw); | |
150 | void (*stop)(struct ieee802154_hw *hw); | |
151 | ... | |
152 | int (*xmit_async)(struct ieee802154_hw *hw, struct sk_buff *skb); | |
153 | int (*ed)(struct ieee802154_hw *hw, u8 *level); | |
154 | int (*set_channel)(struct ieee802154_hw *hw, u8 page, u8 channel); | |
155 | ... | |
156 | }; | |
157 | ||
158 | .. c:function:: int start(struct ieee802154_hw *hw): | |
159 | ||
160 | Handler that 802.15.4 module calls for the hardware device initialization. | |
161 | ||
162 | .. c:function:: void stop(struct ieee802154_hw *hw): | |
163 | ||
164 | Handler that 802.15.4 module calls for the hardware device cleanup. | |
165 | ||
166 | .. c:function:: int xmit_async(struct ieee802154_hw *hw, struct sk_buff *skb): | |
167 | ||
168 | Handler that 802.15.4 module calls for each frame in the skb going to be | |
169 | transmitted through the hardware device. | |
170 | ||
171 | .. c:function:: int ed(struct ieee802154_hw *hw, u8 *level): | |
172 | ||
173 | Handler that 802.15.4 module calls for Energy Detection from the hardware | |
174 | device. | |
175 | ||
176 | .. c:function:: int set_channel(struct ieee802154_hw *hw, u8 page, u8 channel): | |
177 | ||
178 | Set radio for listening on specific channel of the hardware device. | |
179 | ||
180 | Moreover IEEE 802.15.4 device operations structure should be filled. |