1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
|
##############################################################################
README - radlib distribution notes and installation
##############################################################################
ARCHIVE CONTENTS
------- --------
File/Directory Remark
-------------- ------------------------------------------------------
configure build configuration script to be executed before
building radlib
config-radlib-arm-linux example cross compilation script for radlib
(see the CROSS COMPILING section below for
more details)
COPYING The FreeBSD-style License file
h Header files for radlib
src Source directory for the radlib library
msgRouter Source directory for the radlib message routing
daemon radmrouted
database Database server-specific source files
test/database Database API verification test application
test/multicast radUDPsocket multicast verification test application
test/sha radsha SHA-1 and SHA-256 example test application
debug Simple radlib debug utility with makefile - see the
section marked "Debugging" below for details
README This file
ChangeLog Release notes
radlib-api-reference.html radlib HTML API Reference Manual
template-old template/example process which uses some of the
more common radlib capabilities. It demonstrates the
older *destination-based* (QUEUE_GROUP) interprocess
messaging paradigm which is still supported in
radlib. It includes a build environment. It is
functional when built and demonstrates how to
construct and build a radlib application.
template template/example processes which use some of the
more common radlib capabilities. It demonstrates the
new (preferred) *message ID-based* interprocess
messaging paradigm which requires use of the radlib
message routing daemon radmrouted. It includes
a build environment. It is functional when built
and demonstrates how to construct and build
a multi-process radlib application. See the README
file in the 'template' directory for more details.
template/databaseExample.c example program to demo the radlib database API
BUILDING
--------
1) Extract to the location <radlib_path> of your choosing.
2) Change directory to the radlib root source directory.
cd <radlib_path>
3) Run the configure script to create the build files for your platform.
Note: Do NOT enable more than one type of database support! Try
"./configure --help" to see user configurable options.
[No database support (default)]
./configure
---OR---
[With MySQL database support]
./configure --enable-mysql
---OR---
[With PostgreSQL database support]
./configure --enable-pgresql
4) Build the library.
make
5) Become root.
su
<password>
6) Install the library and headers.
make install
Note: The following build targets are available:
make - default target builds all source
make clean - deletes library and object files
make install - makes <default> then installs the library and
headers to "/usr/local/lib" and
"/usr/local/include"
7) Add the radlib directory to your shared library cache.
As root, edit /etc/ld.so.conf
Add "/usr/local/lib" to the file, save and exit.
Run ldconfig: ldconfig
CROSS COMPILING
---------------
See the script "config-radlib-arm-linux for a "./configure" alternative.
This script can be edited to suit your target and toolchain environment.
The general build sequence is:
#./config-radlib-arm-linux
#make
[become root]
#make install
The lib and headers are installed in the toolchain root, defined in the
config script.
DEBUGGING
---------
Included in the distribution is a simple debug utility you can build and use
to display buffer and semaphore information about a running radlib system. It
is called "raddebug" and it is found in the "debug" directory of the distro.
It is built and installed to $prefix/bin/raddebug when you build and install
radlib as described above.
To run it:
#raddebug [radlib_system_ID] <working_directory>
radlib_system_ID the radlib system you want to inspect in the range 1-255;
it is the value passed to "radSystemInit" for the
running system you are interested in
working_directory (optional) working directory given to the radmrouted
daemon when it was started; this enables dumping of the
radmrouted routing statistics
Note: If you specify a non-existent [radlib_system_ID], it will create one and
report all buffers free, then destroy the radlib system and exit.
This is probably not what you want although it is not a problem per se,
just not very informative concerning the radlib system you were trying to
inspect.
EXAMPLE/TEMPLATE
----------------
There are two example radlib applications included in the distribution. Either
may be used as a template for your radlib application development.
template - contains the newer, message router-based, multiprocess example
template-old - contains the older, source/destination messaging single process
example
In either case see the README file in the respective directory for build and use
details.
GENERAL DATABASE API EXAMPLES
-----------------------------
Regardless of your database choice, radlib abstracts the specifics so you can
write portable code which will run on any radlib-supported database engine.
The best example of the API usage is the database test application used to
regression test the radlib database interface. Not well commented but the
printfs in the code give you an idea what is happening. It is found in the
distro at radlib-x.y.z/test/database/dbtest.c. You can also build and run
this application to verify your database setup.
The other resource is the example file:
radlib-x.y.z/template/databaseExample.c
MYSQL DATABASE SETUP (optional)
-------------------------------
This assumes the following (replace with your own preferences):
- the MySQL server is running
- mysql user name: testdbuser
- mysql user password: testdbpw
- mysql database: dbTestDB
1) Connect to the MySQL server:
mysql -u root -p
<password>
2) Create the wview database:
CREATE DATABASE dbTestDB;
3) Create the user account and password for the new database:
GRANT ALL ON dbTestDB.* TO testdbuser@localhost IDENTIFIED BY "testdbpw";
4) Make sure mysqlclient libraries are installed:
find /usr -name "mysql*" -print
If you do not see the files libmysqlclient.a and mysql.h in the output,
it isn't installed. Install the version matching your mysql server that
is installed.
5) Build radlib with database support:
cd <radlib_path>
make distclean # if it had been previously built
./configure --enable-mysql
make install
PostgreSQL DATABASE SETUP (optional)
------------------------------------
This assumes the following (replace with your own preferences):
- the PostgreSQL server is running
- PostgreSQL user name: testdbuser
- PostgreSQL user password: testdbpw
- PostgreSQL database: dbTestDB
1) Create a PostgreSQL user for a unix login user (dbadmin must be a
valid non-root account on the wview server):
Login to the PostgreSQL account:
root@server:# su pgsql
Create an administrative user based on a unix account:
pgsql@server:# /usr/local/bin/createuser dbadmin
Answer the questions:
Shall the new user be allowed to create databases? (y/n) y
Shall the new user be allowed to create more new users? (y/n) y
PostgreSQL acknowledgement:
CREATE USER
Logout of the PostgreSQL account:
pgsql@server:# logout
root@server:#
2) Create the test database:
Login to the admin account:
root@server:# su dbadmin
Create the test database:
dbadmin@server:# /usr/local/bin/createdb dbTestDB
PostgreSQL acknowledgement:
CREATE DATABASE
3) Create the test user account for the test database:
Connect to the PostgreSQL server:
dbadmin@server:# /usr/local/bin/psql dbTestDB
Create the user account and password for the test database:
mydb=# create user testdbuser with password 'testdbpw';
PostgreSQL acknowledgement:
CREATE USER
Disconnect from the server and logout of the admin account:
mydb=# \q
dbadmin@server:# logout
root@server:#
4) Make sure the PostgreSQL development library is installed:
find /usr -name "libpq.a" -print
If you do not see the file libpq.a in the output, it isn't installed.
Install the version matching your PostgreSQL server that is installed.
5) Build radlib with PostgreSQL database support:
cd <radlib_path>
make distclean # if it had been previously built
./configure --enable-pgresql
make install
BUILDING AND RUNNING THE TEMPLATE
---------------------------------
1) Change directory to the template source:
cd <radlib_path>/template
2) Build it:
make
3) Run it:
./templated
BUILDING AND RUNNING THE DATABASE EXAMPLE
-----------------------------------------
1) Change directory to the template source:
cd <radlib_path>/template
2) Build it:
make databaseExample
3) Run it:
./databaseExample
Note: It will fail if you do not have the database, table and permissions
set properly as described above.
LINKSYS NSLU2 DEVELOPMENT
-------------------------
The Linksys NSLU2 is a network storage link which uses USB external hard drives
and an ethernet interface to provide Network Attached Storage (NAS) to the
masses. This is a perfect embedded platform to use for radlib development. It
is small, inexpensive (~$70) and uses little power. In addition, there exists a
mature linux hacking community which has developed an entire open source
distribution including a simple package management system.
1) Install Openslug
Download the openslug 2.7-beta binary:
http://www.openslug.org/
Flash the NSLU2 with the openslug binary:
http://www.nslu2-linux.org/wiki/OpenSlug/UsingTheBinary
Initialize your hard disk and transfer the root filesystem:
http://www.nslu2-linux.org/wiki/OpenSlug/InitialisingOpenSlug
2) Prepare ipkg to Use the wviewweather.com Repository
Once you have your slug (NSLU2) booting from the USB hard drive, do the
following to enable the wviewweather.com ipkg repository:
Obtain the wview ipkg config file:
cd /etc/ipkg
wget http://www.wviewweather.com/ipkg/wview.conf
Configure ipkg:
ipkg update
3) Install the Native Development Tools
ipkg install openslug-native
4) Install the radlib Development Package
ipkg install radlib-dev
Alternatively, if you just need the radlib run-time libraries for an existing
radlib application ipkg, install the "radlib" package.
You are now ready to compile and link native radlib applications on the NSLU2!
Note: There are many other packages available for the slug - execute
"ipkg list" to see the available packages.
DOCS AND EXAMPLES
-----------------
radlib has been successfully deployed (in earlier incarnations) in
several mission-critical applications. In addition, it is used in my
open-source weather application for the Davis Vantage Pro weather station
(see www.wview.teel.ws for details and download). The wview application
source is also an excellent example of how to deploy a radlib based
application.
If you are new to radlib, have a look at the template process as well as the
radlib API reference. Together, these two resources should answer most of
your questions. Also, radlib is a registered SourceForge project.
There is a mailing list as well as a bugtracking system hosted by SourceForge
for the radlib project. Comments/suggestions are welcome.
|
