0001 =====
0002 Pi433
0003 =====
0004
0005
0006 Introduction
0007 ============
0008 This driver is for controlling pi433, a radio module for the Raspberry Pi
0009 (www.pi433.de). It supports transmission and reception. It can be opened
0010 by multiple applications for transmission and reception. While transmit
0011 jobs are queued and processed automatically in the background, the first
0012 application asking for reception will block out all other applications
0013 until something gets received terminates the read request.
0014 The driver supports on the fly reloading of the hardware fifo of the rf
0015 chip, thus enabling for much longer telegrams than the hardware fifo size.
0016
0017 Description of driver operation
0018 ===============================
0019
0020 a) transmission
0021
0022 Each transmission can take place with a different configuration of the rf
0023 module. Therefore each application can set its own set of parameters. The driver
0024 takes care, that each transmission takes place with the parameterset of the
0025 application, that requests the transmission. To allow the transmission to take
0026 place in the background, a tx thread is introduced.
0027 The transfer of data from the main thread to the tx thread is realised by a
0028 kfifo. With each write request of an application, the passed in data and the
0029 corresponding parameter set gets written to the kfifo.
0030 On the other "side" of the kfifo, the tx thread continuously checks, whether the
0031 kfifo is empty. If not, it gets one set of config and data from the kfifo. If
0032 there is no receive request or the receiver is still waiting for something in
0033 the air, the rf module is set to standby, the parameters for transmission gets
0034 set, the hardware fifo of the rf chip gets preloaded and the transmission gets
0035 started. Upon hardware fifo threshold interrupt it gets reloaded, thus enabling
0036 much longer telegrams than the hardware fifo size. If the telegram is sent and there
0037 is more data available in the kfifo, the procedure is repeated. If not the
0038 transmission cycle ends.
0039
0040 b) reception
0041
0042 Since there is only one application allowed to receive data at a time, for
0043 reception there is only one configuration set.
0044 As soon as an application sets a request for receiving a telegram, the reception
0045 configuration set is written to the rf module and it gets set into receiving mode.
0046 Now the driver is waiting, that a predefined RSSI level (signal strength at the
0047 receiver) is reached. Until this hasn't happened, the reception can be
0048 interrupted by the transmission thread at any time to insert a transmission cycle.
0049 As soon as the predefined RSSI level is met, a receiving cycle starts. Similar
0050 as described for the transmission cycle the read out of the hardware fifo is done
0051 dynamically. Upon each hardware fifo threshold interrupt, a portion of data gets
0052 read. So also for reception it is possible to receive more data than the hardware
0053 fifo can hold.
0054
0055
0056 Driver API
0057 ==========
0058
0059 The driver is currently implemented as a character device. Therefore it supports
0060 the calls open, ioctl, read, write and close.
0061
0062
0063 params for ioctl
0064 ----------------
0065
0066 There are four options:
0067 PI433_IOC_RD_TX_CFG - get the transmission parameters from the driver
0068 PI433_IOC_WR_TX_CFG - set the transmission parameters
0069 PI433_IOC_RD_RX_CFG - get the receiving parameters from the driver
0070 PI433_IOC_WR_RX_CFG - set the receiving parameters
0071
0072 The tx configuration is transferred via struct pi433_tx_cfg, the parameterset for transmission.
0073 It is divided into two sections: rf parameters and packet format.
0074
0075 rf params:
0076 frequency
0077 frequency used for transmission.
0078 Allowed values: 433050000...434790000
0079 bit_rate
0080 bit rate used for transmission.
0081 Allowed values: #####
0082 dev_frequency
0083 frequency deviation in case of FSK.
0084 Allowed values: 600...500000
0085 modulation
0086 FSK - frequency shift key
0087 OOK - On-Off-key
0088 modShaping
0089 shapingOff - no shaping
0090 shaping1_0 - gauss filter with BT 1 (FSK only)
0091 shaping0_5 - gauss filter with BT 0.5 (FSK only)
0092 shaping0_3 - gauss filter with BT 0.3 (FSK only)
0093 shapingBR - filter cut off at BR (OOK only)
0094 shaping2BR - filter cut off at 2*BR (OOK only)
0095 pa_ramp (FSK only)
0096 ramp3400 - amp ramps up in 3.4ms
0097 ramp2000 - amp ramps up in 2.0ms
0098 ramp1000 - amp ramps up in 1ms
0099 ramp500 - amp ramps up in 500us
0100 ramp250 - amp ramps up in 250us
0101 ramp125 - amp ramps up in 125us
0102 ramp100 - amp ramps up in 100us
0103 ramp62 - amp ramps up in 62us
0104 ramp50 - amp ramps up in 50us
0105 ramp40 - amp ramps up in 40us
0106 ramp31 - amp ramps up in 31us
0107 ramp25 - amp ramps up in 25us
0108 ramp20 - amp ramps up in 20us
0109 ramp15 - amp ramps up in 15us
0110 ramp12 - amp ramps up in 12us
0111 ramp10 - amp ramps up in 10us
0112 tx_start_condition
0113 fifo_level - transmission starts, if fifo is filled to
0114 threshold level
0115 fifo_not_empty - transmission starts, as soon as there is one
0116 byte in internal fifo
0117 repetitions
0118 This gives the option, to send a telegram multiple times. Default: 1
0119
0120 packet format:
0121 enable_preamble
0122 optionOn - a preamble will be automatically generated
0123 optionOff - no preamble will be generated
0124 enable_sync
0125 optionOn - a sync word will be automatically added to
0126 the telegram after the preamble
0127 optionOff - no sync word will be added
0128 Attention: While possible to generate sync without preamble, the
0129 receiver won't be able to detect the sync without preamble.
0130 enable_length_byte
0131 optionOn - the length of the telegram will be automatically
0132 added to the telegram. It's part of the payload
0133 optionOff - no length information will be automatically added
0134 to the telegram.
0135 Attention: For telegram length over 255 bytes, this option can't be used
0136 Attention: should be used in combination with sync, only
0137 enable_address_byte
0138 optionOn - the address byte will be automatically added to the
0139 telegram. It's part of the payload
0140 optionOff - the address byte will not be added to the telegram.
0141 The address byte can be used for address filtering, so the receiver
0142 will only receive telegrams with a given address byte.
0143 Attention: should be used in combination with sync, only
0144 enable_crc
0145 optionOn - an crc will be automatically calculated over the
0146 payload of the telegram and added to the telegram
0147 after payload.
0148 optionOff - no crc will be calculated
0149 preamble_length
0150 length of the preamble. Allowed values: 0...65536
0151 sync_length
0152 length of the sync word. Allowed values: 0...8
0153 fixed_message_length
0154 length of the payload of the telegram. Will override the length
0155 given by the buffer, passed in with the write command. Will be
0156 ignored if set to zero.
0157 sync_pattern[8]
0158 contains up to eight values, that are used as the sync pattern
0159 on sync option
0160 address_byte
0161 one byte, used as address byte on address byte option.
0162
0163
0164 The rx configuration is transferred via struct pi433_rx_cfg, the parameterset for receiving. It is divided into two sections: rf parameters and packet format.
0165
0166 rf params:
0167 frequency
0168 frequency used for transmission.
0169 Allowed values: 433050000...434790000
0170 bit_rate
0171 bit rate used for transmission.
0172 Allowed values: #####
0173 dev_frequency
0174 frequency deviation in case of FSK.
0175 Allowed values: 600...500000
0176 modulation
0177 FSK - frequency shift key
0178 OOK - on off key
0179 rssi_threshold
0180 threshold value for the signal strength on the receiver input.
0181 If this value is exceeded, a reception cycle starts
0182 Allowed values: 0...255
0183 threshold_decrement
0184 in order to adapt to different levels of singnal strength, over
0185 time the receiver gets more and more sensitive. This value
0186 determs, how fast the sensitivity increases.
0187 step_0_5db - increase in 0,5dB steps
0188 step_1_0db - increase in 1 db steps
0189 step_1_5db - increase in 1,5dB steps
0190 step_2_0db - increase in 2 db steps
0191 step_3_0db - increase in 3 db steps
0192 step_4_0db - increase in 4 db steps
0193 step_5_0db - increase in 5 db steps
0194 step_6_0db - increase in 6 db steps
0195 antenna_impedance
0196 sets the electrical adoption of the antenna
0197 fifty_ohm - for antennas with an impedance of 50Ohm
0198 two_hundred_ohm - for antennas with an impedance of 200Ohm
0199 lna_gain
0200 sets the gain of the low noise amp
0201 automatic - lna gain is determined by an agc
0202 max - lna gain is set to maximum
0203 max_minus_6 - lna gain is set to 6db below max
0204 max_minus_12 - lna gain is set to 12db below max
0205 max_minus_24 - lna gain is set to 24db below max
0206 max_minus_36 - lna gain is set to 36db below max
0207 max_minus_48 - lna gain is set to 48db below max
0208 bw_mantisse
0209 sets the bandwidth of the channel filter - part one: mantisse.
0210 mantisse16 - mantisse is set to 16
0211 mantisse20 - mantisse is set to 20
0212 mantisse24 - mantisse is set to 24
0213 bw_exponent
0214 sets the bandwidth of the channel filter - part two: exponent.
0215 Allowd values: 0...7
0216 dagc;
0217 operation mode of the digital automatic gain control
0218 normal_mode
0219 improve
0220 improve_for_low_modulation_index
0221
0222 packet format:
0223 enable_sync
0224 optionOn - sync detection is enabled. If configured sync pattern
0225 isn't found, telegram will be internally discarded
0226 optionOff - sync detection is disabled.
0227 enable_length_byte
0228 optionOn - First byte of payload will be used as a length byte,
0229 regardless of the amount of bytes that were requested
0230 by the read request.
0231 optionOff - Number of bytes to be read will be set according to
0232 amount of bytes that were requested by the read request.
0233 Attention: should be used in combination with sync, only
0234 enable_address_filtering;
0235 filtering_off - no address filtering will take place
0236 node_address - all telegrams, not matching the node
0237 address will be internally discarded
0238 node_or_broadcast_address - all telegrams, neither matching the
0239 node, nor the broadcast address will
0240 be internally discarded
0241 Attention: Sync option must be enabled in order to use this feature
0242 enable_crc
0243 optionOn - a crc will be calculated over the payload of
0244 the telegram, that was received. If the
0245 calculated crc doesn't match to two bytes,
0246 that follow the payload, the telegram will be
0247 internally discarded.
0248 Attention: This option is only operational if sync on and fixed length
0249 or length byte is used
0250 sync_length
0251 Gives the length of the payload.
0252 Attention: This setting must meet the setting of the transmitter,
0253 if sync option is used.
0254 fixed_message_length
0255 Overrides the telegram length either given by the first byte of
0256 payload or by the read request.
0257 bytes_to_drop
0258 gives the number of bytes, that will be dropped before transferring
0259 data to the read buffer
0260 This option is only useful if all packet helper are switched
0261 off and the rf chip is used in raw receiving mode. This may be
0262 needed, if a telegram of a third party device should be received,
0263 using a protocol not compatible with the packet engine of the rf69 chip.
0264 sync_pattern[8]
0265 contains up to eight values, that are used as the sync pattern
0266 on sync option.
0267 This setting must meet the configuration of the transmitting device,
0268 if sync option is enabled.
0269 node_address
0270 one byte, used as node address byte on address byte option.
0271 broadcast_address
0272 one byte, used as broadcast address byte on address byte option.
0273
0274
