1874bcba6SMarcus Wolf===== 2874bcba6SMarcus WolfPi433 3874bcba6SMarcus Wolf===== 4874bcba6SMarcus Wolf 5874bcba6SMarcus Wolf 6874bcba6SMarcus WolfIntroduction 7874bcba6SMarcus Wolf============ 8874bcba6SMarcus WolfThis driver is for controlling pi433, a radio module for the Raspberry Pi 9874bcba6SMarcus Wolf(www.pi433.de). It supports transmission and reception. It can be opened 10874bcba6SMarcus Wolfby multiple applications for transmission and reception. While transmit 11fb407e32SShannon Boothjobs are queued and processed automatically in the background, the first 12874bcba6SMarcus Wolfapplication asking for reception will block out all other applications 13874bcba6SMarcus Wolfuntil something gets received terminates the read request. 14874bcba6SMarcus WolfThe driver supports on the fly reloading of the hardware fifo of the rf 15fb407e32SShannon Boothchip, thus enabling for much longer telegrams than the hardware fifo size. 16874bcba6SMarcus Wolf 17874bcba6SMarcus WolfDiscription of driver operation 18874bcba6SMarcus Wolf=============================== 19874bcba6SMarcus Wolf 20874bcba6SMarcus Wolfa) transmission 21874bcba6SMarcus Wolf 22874bcba6SMarcus WolfEach transmission can take place with a different configuration of the rf 23a6233017SKeerthi Reddymodule. Therefore each application can set its own set of parameters. The driver 24874bcba6SMarcus Wolftakes care, that each transmission takes place with the parameterset of the 25874bcba6SMarcus Wolfapplication, that requests the transmission. To allow the transmission to take 26874bcba6SMarcus Wolfplace in the background, a tx thread is introduced. 27874bcba6SMarcus WolfThe transfer of data from the main thread to the tx thread is realised by a 28874bcba6SMarcus Wolfkfifo. With each write request of an application, the passed in data and the 29874bcba6SMarcus Wolfcorresponding parameter set gets written to the kfifo. 30874bcba6SMarcus WolfOn the other "side" of the kfifo, the tx thread continuously checks, whether the 31874bcba6SMarcus Wolfkfifo is empty. If not, it gets one set of config and data from the kfifo. If 32874bcba6SMarcus Wolfthere is no receive request or the receiver is still waiting for something in 33874bcba6SMarcus Wolfthe air, the rf module is set to standby, the parameters for transmission gets 34874bcba6SMarcus Wolfset, the hardware fifo of the rf chip gets preloaded and the transmission gets 35874bcba6SMarcus Wolfstarted. Upon hardware fifo threshold interrupt it gets reloaded, thus enabling 36a6233017SKeerthi Reddymuch longer telegrams than the hardware fifo size. If the telegram is sent and there 37874bcba6SMarcus Wolfis more data available in the kfifo, the procedure is repeated. If not the 38874bcba6SMarcus Wolftransmission cycle ends. 39874bcba6SMarcus Wolf 40874bcba6SMarcus Wolfb) reception 41874bcba6SMarcus Wolf 42874bcba6SMarcus WolfSince there is only one application allowed to receive data at a time, for 43874bcba6SMarcus Wolfreception there is only one configuration set. 44a6233017SKeerthi ReddyAs soon as an application sets a request for receiving a telegram, the reception 45874bcba6SMarcus Wolfconfiguration set is written to the rf module and it gets set into receiving mode. 46874bcba6SMarcus WolfNow the driver is waiting, that a predefined RSSI level (signal strength at the 47874bcba6SMarcus Wolfreceiver) is reached. Until this hasn't happened, the reception can be 48874bcba6SMarcus Wolfinterrupted by the transmission thread at any time to insert a transmission cycle. 49fb407e32SShannon BoothAs soon as the predefined RSSI level is met, a receiving cycle starts. Similar 50874bcba6SMarcus Wolfas described for the transmission cycle the read out of the hardware fifo is done 51874bcba6SMarcus Wolfdynamically. Upon each hardware fifo threshold interrupt, a portion of data gets 52fb407e32SShannon Boothread. So also for reception it is possible to receive more data than the hardware 53874bcba6SMarcus Wolffifo can hold. 54874bcba6SMarcus Wolf 55874bcba6SMarcus Wolf 56874bcba6SMarcus WolfDriver API 57874bcba6SMarcus Wolf========== 58874bcba6SMarcus Wolf 59874bcba6SMarcus WolfThe driver is currently implemented as a character device. Therefore it supports 60874bcba6SMarcus Wolfthe calls open, ioctl, read, write and close. 61874bcba6SMarcus Wolf 62874bcba6SMarcus Wolf 63874bcba6SMarcus Wolfparams for ioctl 64874bcba6SMarcus Wolf---------------- 65874bcba6SMarcus Wolf 66874bcba6SMarcus WolfThere are four options: 67874bcba6SMarcus WolfPI433_IOC_RD_TX_CFG - get the transmission parameters from the driver 68874bcba6SMarcus WolfPI433_IOC_WR_TX_CFG - set the transmission parameters 69874bcba6SMarcus WolfPI433_IOC_RD_RX_CFG - get the receiving parameters from the driver 70874bcba6SMarcus WolfPI433_IOC_WR_RX_CFG - set the receiving parameters 71874bcba6SMarcus Wolf 728d7ec913SValentin VidicThe tx configuration is transferred via struct pi433_tx_cfg, the parameterset for transmission. 738d7ec913SValentin VidicIt is divided into two sections: rf parameters and packet format. 74874bcba6SMarcus Wolf 75874bcba6SMarcus Wolfrf params: 76874bcba6SMarcus Wolf frequency 77874bcba6SMarcus Wolf frequency used for transmission. 78874bcba6SMarcus Wolf Allowed values: 433050000...434790000 79874bcba6SMarcus Wolf bit_rate 80874bcba6SMarcus Wolf bit rate used for transmission. 81874bcba6SMarcus Wolf Allowed values: ##### 82874bcba6SMarcus Wolf dev_frequency 83874bcba6SMarcus Wolf frequency deviation in case of FSK. 84874bcba6SMarcus Wolf Allowed values: 600...500000 85874bcba6SMarcus Wolf modulation 86874bcba6SMarcus Wolf FSK - frequency shift key 87874bcba6SMarcus Wolf OOK - On-Off-key 88874bcba6SMarcus Wolf modShaping 89874bcba6SMarcus Wolf shapingOff - no shaping 90874bcba6SMarcus Wolf shaping1_0 - gauss filter with BT 1 (FSK only) 91874bcba6SMarcus Wolf shaping0_5 - gauss filter with BT 0.5 (FSK only) 92874bcba6SMarcus Wolf shaping0_3 - gauss filter with BT 0.3 (FSK only) 93874bcba6SMarcus Wolf shapingBR - filter cut off at BR (OOK only) 94874bcba6SMarcus Wolf shaping2BR - filter cut off at 2*BR (OOK only) 95a9f83a65SValentin Vidic pa_ramp (FSK only) 96874bcba6SMarcus Wolf ramp3400 - amp ramps up in 3.4ms 97874bcba6SMarcus Wolf ramp2000 - amp ramps up in 2.0ms 98874bcba6SMarcus Wolf ramp1000 - amp ramps up in 1ms 99874bcba6SMarcus Wolf ramp500 - amp ramps up in 500us 100874bcba6SMarcus Wolf ramp250 - amp ramps up in 250us 101874bcba6SMarcus Wolf ramp125 - amp ramps up in 125us 102874bcba6SMarcus Wolf ramp100 - amp ramps up in 100us 103874bcba6SMarcus Wolf ramp62 - amp ramps up in 62us 104874bcba6SMarcus Wolf ramp50 - amp ramps up in 50us 105874bcba6SMarcus Wolf ramp40 - amp ramps up in 40us 106874bcba6SMarcus Wolf ramp31 - amp ramps up in 31us 107874bcba6SMarcus Wolf ramp25 - amp ramps up in 25us 108874bcba6SMarcus Wolf ramp20 - amp ramps up in 20us 109874bcba6SMarcus Wolf ramp15 - amp ramps up in 15us 110874bcba6SMarcus Wolf ramp12 - amp ramps up in 12us 111874bcba6SMarcus Wolf ramp10 - amp ramps up in 10us 112874bcba6SMarcus Wolf tx_start_condition 113acf71f8dSValentin Vidic fifo_level - transmission starts, if fifo is filled to 114874bcba6SMarcus Wolf threshold level 115acf71f8dSValentin Vidic fifo_not_empty - transmission starts, as soon as there is one 116874bcba6SMarcus Wolf byte in internal fifo 117874bcba6SMarcus Wolf repetitions 118874bcba6SMarcus Wolf This gives the option, to send a telegram multiple times. Default: 1 119874bcba6SMarcus Wolf 120874bcba6SMarcus Wolfpacket format: 121874bcba6SMarcus Wolf enable_preamble 122874bcba6SMarcus Wolf optionOn - a preamble will be automatically generated 123874bcba6SMarcus Wolf optionOff - no preamble will be generated 124874bcba6SMarcus Wolf enable_sync 125874bcba6SMarcus Wolf optionOn - a sync word will be automatically added to 126a6233017SKeerthi Reddy the telegram after the preamble 127874bcba6SMarcus Wolf optionOff - no sync word will be added 128874bcba6SMarcus Wolf Attention: While possible to generate sync without preamble, the 129874bcba6SMarcus Wolf receiver won't be able to detect the sync without preamble. 130874bcba6SMarcus Wolf enable_length_byte 131874bcba6SMarcus Wolf optionOn - the length of the telegram will be automatically 132874bcba6SMarcus Wolf added to the telegram. It's part of the payload 133874bcba6SMarcus Wolf optionOff - no length information will be automatically added 134874bcba6SMarcus Wolf to the telegram. 135874bcba6SMarcus Wolf Attention: For telegram length over 255 bytes, this option can't be used 136874bcba6SMarcus Wolf Attention: should be used in combination with sync, only 137874bcba6SMarcus Wolf enable_address_byte 138874bcba6SMarcus Wolf optionOn - the address byte will be automatically added to the 139a6233017SKeerthi Reddy telegram. It's part of the payload 140874bcba6SMarcus Wolf optionOff - the address byte will not be added to the telegram. 141874bcba6SMarcus Wolf The address byte can be used for address filtering, so the receiver 142874bcba6SMarcus Wolf will only receive telegrams with a given address byte. 143874bcba6SMarcus Wolf Attention: should be used in combination with sync, only 144874bcba6SMarcus Wolf enable_crc 145874bcba6SMarcus Wolf optionOn - an crc will be automatically calculated over the 146874bcba6SMarcus Wolf payload of the telegram and added to the telegram 147874bcba6SMarcus Wolf after payload. 148874bcba6SMarcus Wolf optionOff - no crc will be calculated 149874bcba6SMarcus Wolf preamble_length 150874bcba6SMarcus Wolf length of the preamble. Allowed values: 0...65536 151874bcba6SMarcus Wolf sync_length 152874bcba6SMarcus Wolf length of the sync word. Allowed values: 0...8 153874bcba6SMarcus Wolf fixed_message_length 154874bcba6SMarcus Wolf length of the payload of the telegram. Will override the length 155874bcba6SMarcus Wolf given by the buffer, passed in with the write command. Will be 156874bcba6SMarcus Wolf ignored if set to zero. 157874bcba6SMarcus Wolf sync_pattern[8] 158874bcba6SMarcus Wolf contains up to eight values, that are used as the sync pattern 159874bcba6SMarcus Wolf on sync option 160874bcba6SMarcus Wolf address_byte 161874bcba6SMarcus Wolf one byte, used as address byte on address byte option. 162874bcba6SMarcus Wolf 163874bcba6SMarcus Wolf 164a6233017SKeerthi ReddyThe rx configuration is transferred via struct pi433_rx_cfg, the parameterset for receiving. It is divided into two sections: rf parameters and packet format. 165874bcba6SMarcus Wolf 166874bcba6SMarcus Wolfrf params: 167874bcba6SMarcus Wolf frequency 168874bcba6SMarcus Wolf frequency used for transmission. 169874bcba6SMarcus Wolf Allowed values: 433050000...434790000 170874bcba6SMarcus Wolf bit_rate 171874bcba6SMarcus Wolf bit rate used for transmission. 172874bcba6SMarcus Wolf Allowed values: ##### 173874bcba6SMarcus Wolf dev_frequency 174874bcba6SMarcus Wolf frequency deviation in case of FSK. 175874bcba6SMarcus Wolf Allowed values: 600...500000 176874bcba6SMarcus Wolf modulation 177874bcba6SMarcus Wolf FSK - frequency shift key 178874bcba6SMarcus Wolf OOK - on off key 179874bcba6SMarcus Wolf rssi_threshold 180874bcba6SMarcus Wolf threshold value for the signal strength on the receiver input. 181a6233017SKeerthi Reddy If this value is exceeded, a reception cycle starts 182874bcba6SMarcus Wolf Allowed values: 0...255 183b52a5b79SValentin Vidic threshold_decrement 184874bcba6SMarcus Wolf in order to adapt to different levels of singnal strength, over 185874bcba6SMarcus Wolf time the receiver gets more and more sensitive. This value 186874bcba6SMarcus Wolf determs, how fast the sensitivity increases. 187874bcba6SMarcus Wolf step_0_5db - increase in 0,5dB steps 188874bcba6SMarcus Wolf step_1_0db - increase in 1 db steps 189874bcba6SMarcus Wolf step_1_5db - increase in 1,5dB steps 190874bcba6SMarcus Wolf step_2_0db - increase in 2 db steps 191874bcba6SMarcus Wolf step_3_0db - increase in 3 db steps 192874bcba6SMarcus Wolf step_4_0db - increase in 4 db steps 193874bcba6SMarcus Wolf step_5_0db - increase in 5 db steps 194874bcba6SMarcus Wolf step_6_0db - increase in 6 db steps 195370d7ce6SValentin Vidic antenna_impedance 196874bcba6SMarcus Wolf sets the electrical adoption of the antenna 1970b897065SValentin Vidic fifty_ohm - for antennas with an impedance of 50Ohm 1980b897065SValentin Vidic two_hundred_ohm - for antennas with an impedance of 200Ohm 199e4928ac2SValentin Vidic lna_gain 200874bcba6SMarcus Wolf sets the gain of the low noise amp 201a6233017SKeerthi Reddy automatic - lna gain is determined by an agc 202874bcba6SMarcus Wolf max - lna gain is set to maximum 203b167a524SValentin Vidic max_minus_6 - lna gain is set to 6db below max 204b167a524SValentin Vidic max_minus_12 - lna gain is set to 12db below max 205b167a524SValentin Vidic max_minus_24 - lna gain is set to 24db below max 206b167a524SValentin Vidic max_minus_36 - lna gain is set to 36db below max 207b167a524SValentin Vidic max_minus_48 - lna gain is set to 48db below max 208874bcba6SMarcus Wolf bw_mantisse 209874bcba6SMarcus Wolf sets the bandwidth of the channel filter - part one: mantisse. 210874bcba6SMarcus Wolf mantisse16 - mantisse is set to 16 211874bcba6SMarcus Wolf mantisse20 - mantisse is set to 20 212874bcba6SMarcus Wolf mantisse24 - mantisse is set to 24 213874bcba6SMarcus Wolf bw_exponent 214874bcba6SMarcus Wolf sets the bandwidth of the channel filter - part two: exponent. 215874bcba6SMarcus Wolf Allowd values: 0...7 216874bcba6SMarcus Wolf dagc; 217874bcba6SMarcus Wolf operation mode of the digital automatic gain control 218bcb4f0d7SValentin Vidic normal_mode 219874bcba6SMarcus Wolf improve 220bcb4f0d7SValentin Vidic improve_for_low_modulation_index 221874bcba6SMarcus Wolf 222874bcba6SMarcus Wolf packet format: 223874bcba6SMarcus Wolf enable_sync 224874bcba6SMarcus Wolf optionOn - sync detection is enabled. If configured sync pattern 225874bcba6SMarcus Wolf isn't found, telegram will be internally discarded 226874bcba6SMarcus Wolf optionOff - sync detection is disabled. 227874bcba6SMarcus Wolf enable_length_byte 228fb407e32SShannon Booth optionOn - First byte of payload will be used as a length byte, 229874bcba6SMarcus Wolf regardless of the amount of bytes that were requested 230874bcba6SMarcus Wolf by the read request. 231874bcba6SMarcus Wolf optionOff - Number of bytes to be read will be set according to 232874bcba6SMarcus Wolf amount of bytes that were requested by the read request. 233874bcba6SMarcus Wolf Attention: should be used in combination with sync, only 234874bcba6SMarcus Wolf enable_address_filtering; 235cd9d5291SValentin Vidic filtering_off - no address filtering will take place 236cd9d5291SValentin Vidic node_address - all telegrams, not matching the node 237874bcba6SMarcus Wolf address will be internally discarded 238cd9d5291SValentin Vidic node_or_broadcast_address - all telegrams, neither matching the 239874bcba6SMarcus Wolf node, nor the broadcast address will 240874bcba6SMarcus Wolf be internally discarded 241874bcba6SMarcus Wolf Attention: Sync option must be enabled in order to use this feature 242874bcba6SMarcus Wolf enable_crc 243874bcba6SMarcus Wolf optionOn - a crc will be calculated over the payload of 244874bcba6SMarcus Wolf the telegram, that was received. If the 245874bcba6SMarcus Wolf calculated crc doesn't match to two bytes, 246874bcba6SMarcus Wolf that follow the payload, the telegram will be 247874bcba6SMarcus Wolf internally discarded. 248a6233017SKeerthi Reddy Attention: This option is only operational if sync on and fixed length 249874bcba6SMarcus Wolf or length byte is used 250874bcba6SMarcus Wolf sync_length 251874bcba6SMarcus Wolf Gives the length of the payload. 252874bcba6SMarcus Wolf Attention: This setting must meet the setting of the transmitter, 253874bcba6SMarcus Wolf if sync option is used. 254874bcba6SMarcus Wolf fixed_message_length 255874bcba6SMarcus Wolf Overrides the telegram length either given by the first byte of 256874bcba6SMarcus Wolf payload or by the read request. 257874bcba6SMarcus Wolf bytes_to_drop 258a6233017SKeerthi Reddy gives the number of bytes, that will be dropped before transferring 259874bcba6SMarcus Wolf data to the read buffer 260a6233017SKeerthi Reddy This option is only useful if all packet helper are switched 261874bcba6SMarcus Wolf off and the rf chip is used in raw receiving mode. This may be 262874bcba6SMarcus Wolf needed, if a telegram of a third party device should be received, 263874bcba6SMarcus Wolf using a protocol not compatible with the packet engine of the rf69 chip. 264874bcba6SMarcus Wolf sync_pattern[8] 265874bcba6SMarcus Wolf contains up to eight values, that are used as the sync pattern 266874bcba6SMarcus Wolf on sync option. 267874bcba6SMarcus Wolf This setting must meet the configuration of the transmitting device, 268874bcba6SMarcus Wolf if sync option is enabled. 269874bcba6SMarcus Wolf node_address 270874bcba6SMarcus Wolf one byte, used as node address byte on address byte option. 271874bcba6SMarcus Wolf broadcast_address 272874bcba6SMarcus Wolf one byte, used as broadcast address byte on address byte option. 273874bcba6SMarcus Wolf 274874bcba6SMarcus Wolf 275