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 were queued and process 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 then hardware fifo size.
16
17Discription of driver operation
18===============================
19
20a) transmission
21
22Each transmission can take place with a different configuration of the rf
23module. Therfore 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 then hardware fifo size. If the telegram is send 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 an 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 meat, 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 then 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 transfered via struct pi433_tx_cfg, the parameterset for transmission.
73It is devided 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	paRamp (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		fifoLevel	- transmission starts, if fifo is filled to
114				  threshold level
115		fifoNotEmpty	- 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 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				  telgram. 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 transfered via struct pi433_rx_cfg, the parameterset for receiving. It is devided 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 exeeded, a reception cycle starts
182		Allowed values: 0...255
183	thresholdDecrement
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	antennaImpedance
196		sets the electrical adoption of the antenna
197		fiftyOhm	- for antennas with an impedance of 50Ohm
198		twohundretOhm	- for antennas with an impedance of 200Ohm
199	lnaGain
200		sets the gain of the low noise amp
201		automatic	- lna gain is determed by an agc
202		max		- lna gain is set to maximum
203		maxMinus6	- lna gain is set to  6db below max
204		maxMinus12	- lna gain is set to 12db below max
205		maxMinus24	- lna gain is set to 24db below max
206		maxMinus36	- lna gain is set to 36db below max
207		maxMinus48	- 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		normalMode
219		improve
220		improve4LowModulationIndex
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 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		filteringOff		- no adress filtering will take place
236		nodeAddress		- all telegrams, not matching the node
237					  address will be internally discarded
238		nodeOrBroadcastAddress	- 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 transfering
259		data to the read buffer
260		This option is only usefull, 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
275