pi433.txt (11096B)
1===== 2Pi433 3===== 4 5 6Introduction 7============ 8This driver is for controlling pi433, a radio module for the Raspberry Pi 9(www.pi433.de). It supports transmission and reception. It can be opened 10by multiple applications for transmission and reception. While transmit 11jobs are queued and processed automatically in the background, the first 12application asking for reception will block out all other applications 13until something gets received terminates the read request. 14The driver supports on the fly reloading of the hardware fifo of the rf 15chip, thus enabling for much longer telegrams than the hardware fifo size. 16 17Description of driver operation 18=============================== 19 20a) transmission 21 22Each transmission can take place with a different configuration of the rf 23module. Therefore each application can set its own set of parameters. The driver 24takes care, that each transmission takes place with the parameterset of the 25application, that requests the transmission. To allow the transmission to take 26place in the background, a tx thread is introduced. 27The transfer of data from the main thread to the tx thread is realised by a 28kfifo. With each write request of an application, the passed in data and the 29corresponding parameter set gets written to the kfifo. 30On the other "side" of the kfifo, the tx thread continuously checks, whether the 31kfifo is empty. If not, it gets one set of config and data from the kfifo. If 32there is no receive request or the receiver is still waiting for something in 33the air, the rf module is set to standby, the parameters for transmission gets 34set, the hardware fifo of the rf chip gets preloaded and the transmission gets 35started. Upon hardware fifo threshold interrupt it gets reloaded, thus enabling 36much longer telegrams than the hardware fifo size. If the telegram is sent and there 37is more data available in the kfifo, the procedure is repeated. If not the 38transmission cycle ends. 39 40b) reception 41 42Since there is only one application allowed to receive data at a time, for 43reception there is only one configuration set. 44As soon as an application sets a request for receiving a telegram, the reception 45configuration set is written to the rf module and it gets set into receiving mode. 46Now the driver is waiting, that a predefined RSSI level (signal strength at the 47receiver) is reached. Until this hasn't happened, the reception can be 48interrupted by the transmission thread at any time to insert a transmission cycle. 49As soon as the predefined RSSI level is met, a receiving cycle starts. Similar 50as described for the transmission cycle the read out of the hardware fifo is done 51dynamically. Upon each hardware fifo threshold interrupt, a portion of data gets 52read. So also for reception it is possible to receive more data than the hardware 53fifo can hold. 54 55 56Driver API 57========== 58 59The driver is currently implemented as a character device. Therefore it supports 60the calls open, ioctl, read, write and close. 61 62 63params for ioctl 64---------------- 65 66There are four options: 67PI433_IOC_RD_TX_CFG - get the transmission parameters from the driver 68PI433_IOC_WR_TX_CFG - set the transmission parameters 69PI433_IOC_RD_RX_CFG - get the receiving parameters from the driver 70PI433_IOC_WR_RX_CFG - set the receiving parameters 71 72The tx configuration is transferred via struct pi433_tx_cfg, the parameterset for transmission. 73It is divided into two sections: rf parameters and packet format. 74 75rf params: 76 frequency 77 frequency used for transmission. 78 Allowed values: 433050000...434790000 79 bit_rate 80 bit rate used for transmission. 81 Allowed values: ##### 82 dev_frequency 83 frequency deviation in case of FSK. 84 Allowed values: 600...500000 85 modulation 86 FSK - frequency shift key 87 OOK - On-Off-key 88 modShaping 89 shapingOff - no shaping 90 shaping1_0 - gauss filter with BT 1 (FSK only) 91 shaping0_5 - gauss filter with BT 0.5 (FSK only) 92 shaping0_3 - gauss filter with BT 0.3 (FSK only) 93 shapingBR - filter cut off at BR (OOK only) 94 shaping2BR - filter cut off at 2*BR (OOK only) 95 pa_ramp (FSK only) 96 ramp3400 - amp ramps up in 3.4ms 97 ramp2000 - amp ramps up in 2.0ms 98 ramp1000 - amp ramps up in 1ms 99 ramp500 - amp ramps up in 500us 100 ramp250 - amp ramps up in 250us 101 ramp125 - amp ramps up in 125us 102 ramp100 - amp ramps up in 100us 103 ramp62 - amp ramps up in 62us 104 ramp50 - amp ramps up in 50us 105 ramp40 - amp ramps up in 40us 106 ramp31 - amp ramps up in 31us 107 ramp25 - amp ramps up in 25us 108 ramp20 - amp ramps up in 20us 109 ramp15 - amp ramps up in 15us 110 ramp12 - amp ramps up in 12us 111 ramp10 - amp ramps up in 10us 112 tx_start_condition 113 fifo_level - transmission starts, if fifo is filled to 114 threshold level 115 fifo_not_empty - transmission starts, as soon as there is one 116 byte in internal fifo 117 repetitions 118 This gives the option, to send a telegram multiple times. Default: 1 119 120packet format: 121 enable_preamble 122 optionOn - a preamble will be automatically generated 123 optionOff - no preamble will be generated 124 enable_sync 125 optionOn - a sync word will be automatically added to 126 the telegram after the preamble 127 optionOff - no sync word will be added 128 Attention: While possible to generate sync without preamble, the 129 receiver won't be able to detect the sync without preamble. 130 enable_length_byte 131 optionOn - the length of the telegram will be automatically 132 added to the telegram. It's part of the payload 133 optionOff - no length information will be automatically added 134 to the telegram. 135 Attention: For telegram length over 255 bytes, this option can't be used 136 Attention: should be used in combination with sync, only 137 enable_address_byte 138 optionOn - the address byte will be automatically added to the 139 telegram. It's part of the payload 140 optionOff - the address byte will not be added to the telegram. 141 The address byte can be used for address filtering, so the receiver 142 will only receive telegrams with a given address byte. 143 Attention: should be used in combination with sync, only 144 enable_crc 145 optionOn - an crc will be automatically calculated over the 146 payload of the telegram and added to the telegram 147 after payload. 148 optionOff - no crc will be calculated 149 preamble_length 150 length of the preamble. Allowed values: 0...65536 151 sync_length 152 length of the sync word. Allowed values: 0...8 153 fixed_message_length 154 length of the payload of the telegram. Will override the length 155 given by the buffer, passed in with the write command. Will be 156 ignored if set to zero. 157 sync_pattern[8] 158 contains up to eight values, that are used as the sync pattern 159 on sync option 160 address_byte 161 one byte, used as address byte on address byte option. 162 163 164The rx configuration is transferred via struct pi433_rx_cfg, the parameterset for receiving. It is divided into two sections: rf parameters and packet format. 165 166rf params: 167 frequency 168 frequency used for transmission. 169 Allowed values: 433050000...434790000 170 bit_rate 171 bit rate used for transmission. 172 Allowed values: ##### 173 dev_frequency 174 frequency deviation in case of FSK. 175 Allowed values: 600...500000 176 modulation 177 FSK - frequency shift key 178 OOK - on off key 179 rssi_threshold 180 threshold value for the signal strength on the receiver input. 181 If this value is exceeded, a reception cycle starts 182 Allowed values: 0...255 183 threshold_decrement 184 in order to adapt to different levels of singnal strength, over 185 time the receiver gets more and more sensitive. This value 186 determs, how fast the sensitivity increases. 187 step_0_5db - increase in 0,5dB steps 188 step_1_0db - increase in 1 db steps 189 step_1_5db - increase in 1,5dB steps 190 step_2_0db - increase in 2 db steps 191 step_3_0db - increase in 3 db steps 192 step_4_0db - increase in 4 db steps 193 step_5_0db - increase in 5 db steps 194 step_6_0db - increase in 6 db steps 195 antenna_impedance 196 sets the electrical adoption of the antenna 197 fifty_ohm - for antennas with an impedance of 50Ohm 198 two_hundred_ohm - for antennas with an impedance of 200Ohm 199 lna_gain 200 sets the gain of the low noise amp 201 automatic - lna gain is determined by an agc 202 max - lna gain is set to maximum 203 max_minus_6 - lna gain is set to 6db below max 204 max_minus_12 - lna gain is set to 12db below max 205 max_minus_24 - lna gain is set to 24db below max 206 max_minus_36 - lna gain is set to 36db below max 207 max_minus_48 - lna gain is set to 48db below max 208 bw_mantisse 209 sets the bandwidth of the channel filter - part one: mantisse. 210 mantisse16 - mantisse is set to 16 211 mantisse20 - mantisse is set to 20 212 mantisse24 - mantisse is set to 24 213 bw_exponent 214 sets the bandwidth of the channel filter - part two: exponent. 215 Allowd values: 0...7 216 dagc; 217 operation mode of the digital automatic gain control 218 normal_mode 219 improve 220 improve_for_low_modulation_index 221 222 packet format: 223 enable_sync 224 optionOn - sync detection is enabled. If configured sync pattern 225 isn't found, telegram will be internally discarded 226 optionOff - sync detection is disabled. 227 enable_length_byte 228 optionOn - First byte of payload will be used as a length byte, 229 regardless of the amount of bytes that were requested 230 by the read request. 231 optionOff - Number of bytes to be read will be set according to 232 amount of bytes that were requested by the read request. 233 Attention: should be used in combination with sync, only 234 enable_address_filtering; 235 filtering_off - no address filtering will take place 236 node_address - all telegrams, not matching the node 237 address will be internally discarded 238 node_or_broadcast_address - all telegrams, neither matching the 239 node, nor the broadcast address will 240 be internally discarded 241 Attention: Sync option must be enabled in order to use this feature 242 enable_crc 243 optionOn - a crc will be calculated over the payload of 244 the telegram, that was received. If the 245 calculated crc doesn't match to two bytes, 246 that follow the payload, the telegram will be 247 internally discarded. 248 Attention: This option is only operational if sync on and fixed length 249 or length byte is used 250 sync_length 251 Gives the length of the payload. 252 Attention: This setting must meet the setting of the transmitter, 253 if sync option is used. 254 fixed_message_length 255 Overrides the telegram length either given by the first byte of 256 payload or by the read request. 257 bytes_to_drop 258 gives the number of bytes, that will be dropped before transferring 259 data to the read buffer 260 This option is only useful if all packet helper are switched 261 off and the rf chip is used in raw receiving mode. This may be 262 needed, if a telegram of a third party device should be received, 263 using a protocol not compatible with the packet engine of the rf69 chip. 264 sync_pattern[8] 265 contains up to eight values, that are used as the sync pattern 266 on sync option. 267 This setting must meet the configuration of the transmitting device, 268 if sync option is enabled. 269 node_address 270 one byte, used as node address byte on address byte option. 271 broadcast_address 272 one byte, used as broadcast address byte on address byte option. 273 274