Add test for Nordic Semiconductor nRF905 protocol decoder
[sigrok-test.git] / README
1 -------------------------------------------------------------------------------
2 README
3 -------------------------------------------------------------------------------
4
5 The sigrok project aims at creating a portable, cross-platform,
6 Free/Libre/Open-Source signal analysis software suite that supports various
7 device types (such as logic analyzers, oscilloscopes, multimeters, and more).
8
9 sigrok-test is a collection of various tools and files for testing sigrok.
10
11
12 Status
13 ------
14
15 Work in progress.
16
17 Distro packagers should NOT package this!
18
19
20 Requirements
21 ------------
22
23  - git
24  - gcc
25  - make
26  - autoconf >= 2.63
27  - automake >= 1.11
28  - pkg-config >= 0.22
29  - libglib >= 2.24.0
30  - Python >= 3.2
31  - libsigrok >= 0.5.0
32  - libsigrokdecode >= 0.5.0
33  - python3-coverage
34
35
36 Building and usage
37 ------------------
38
39 Assumption: libsigrok and libsigrokdecode are installed in $HOME/sr.
40 If they are in a standard location instead, you don't need the
41 PKG_CONFIG_PATH and LD_LIBRARY_PATH below.
42
43 In order to get the sigrok-test source code and build it, run:
44
45  $ git clone git://sigrok.org/sigrok-test
46  $ cd sigrok-test
47  $ ./autogen.sh
48  $ PKG_CONFIG_PATH=$HOME/sr/lib/pkgconfig ./configure \
49         --with-decodersdir=/path/to/decoders
50  $ make
51
52 This will test the decoders located at /path/to/decoders:
53
54  $ LD_LIBRARY_PATH=$HOME/sr/lib ./decoder/pdtest -r -v -a
55
56
57 Adding tests
58 ------------
59
60 The best way to add tests is to copy one that is similar, and adjust
61 accordingly. Some notes:
62
63  * In test.conf, the channel assignments must be done in a specific way:
64
65     protocol-decoder <pdname> channel <pd_channel_name>=<#> ...
66
67    Example:
68
69     protocol-decoder mcs48 d0=8 d1=9 [...] a8=0 ...
70
71    Of important note, the channels/probes are numbered from 0, regardless of
72    the naming used in the capture file.
73
74  * To initially generate the test files which have been configured in test.conf
75    pdtest has to be run with the -f parameter first.
76
77    Example:
78
79     ./decoder/pdtest -r -v -f <testroot>
80
81   This can also be done to update the test-cases in case of a changes in
82   the protocol decoder.
83
84  * To troubleshoot a specific test, try:
85
86     * Run all tests under decoder/test/<testroot>:
87
88       ./decoder/pdtest -v -d -r <testroot>
89
90     * Run the named test. Note, in this case <testname> is not
91       a file but rather a test described in <testroot>/test.conf.
92
93       ./decoder/pdtest -v -d -r <testroot>/<testname>
94
95     * Print parameters as parsed from <testroot>/test.conf (to spot typos):
96
97       ./decoder/pdtest -v -s <testroot>
98
99
100 Copyright and license
101 ---------------------
102
103 sigrok-test contains various tools that are licensed under different terms.
104
105 Some are licensed under the terms of the GNU GPL version 2 (or later),
106 others under the terms of the GNU GPL version 3 (or later).
107
108 Please see the individual source files for the full list of copyright holders
109 and the license that applies to the respective tool.
110
111
112 Mailing list
113 ------------
114
115  https://lists.sourceforge.net/lists/listinfo/sigrok-devel
116
117
118 IRC
119 ---
120
121 You can find the sigrok developers in the #sigrok IRC channel on Freenode.
122
123
124 Website
125 -------
126
127  http://sigrok.org
128