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
|
The Lua LCM API {#lua_api}
====
The Lua API wraps the LCM C API, and is meant to mirror its functionality and organization. The bulk of the Lua API is represented by the LCM userdata, which basically wraps \ref LcmC_lcm_t "lcm_t and related functions".
# LCM Userdata {#lcm_userdata}
The LCM userdata manages an internal \ref LcmC_lcm_t "lcm_t" and any number of subscriptions.
\em Initializer
\li \ref lcm_userdata_new "new"
\em Methods
\li \ref lcm_userdata_publish "publish"
\li \ref lcm_userdata_subscribe "subscribe"
\li \ref lcm_userdata_unsubscribe "unsubscribe"
\li \ref lcm_userdata_handle "handle"
\li \ref lcm_userdata_handle_timeout "handle_timeout"
\li \ref lcm_userdata_timedhandle "timedhandle (Deprecated)"
<hr>
## new {#lcm_userdata_new}
\em Parameters
\li \c provider Optional. The LCM provider.
<em>Return Values</em>
\li The new LCM userdata.
\em Description
This is the userdata initializer; it creates a new userdata.
<em>Example Code</em>
\verbatim
local lcm = require('lcm')
local lc = lcm.lcm.new()
local lc2 = lcm.lcm.new('udpm://239.255.76.67:7667?ttl=1')
\endverbatim
<hr>
## publish {#lcm_userdata_publish}
\em Parameters
\li \c channel The channel to publish to.
\li \c message The encoded message to send.
<em>Return Values</em>
\li (None.)
\em Description
This method publishes a message to a channel. If the message cannot be published, an error is raised.
<em>Example Code</em>
\verbatim
local lcm = require('lcm')
local msg_t = require('msg_t') -- or any other message type
local lc = lcm.lcm.new()
local msg = msg_t:new()
local encoded_msg = msg:encode()
lc:publish('somechannel', encoded_msg)
\endverbatim
<hr>
## subscribe {#lcm_userdata_subscribe}
\em Parameters
\li \c channel The channel to subscribe to.
\li \c handler The callback.
<em>Return Values</em>
\li The subscription reference.
\em Description
This method creates a subscription to a channel. There may be multiple subscriptions per channel. Creating a subscription involves registering a callback, which is invoked once per received message on the specified channel. The callback is invoked during calls to \ref lcm_userdata_handle "handle" or \ref lcm_userdata_timedhandle "timedhandle".
Notice that this function does not return an actual subscription, but a reference to one. This function returns an integer which is used to index an internal table of subscriptions. The lifetime of the internal subscription is not dependent on the reference, so subscriptions cannot be garbage collected. Subscriptions can only be removed by being \ref lcm_userdata_unsubscribe "unsubscribed".
<em>Example Code</em>
\verbatim
local lcm = require('lcm')
local msg_t = require('msg_t') -- or any other message type
local lc = lcm.lcm.new()
local function handler(channel, encoded_msg)
local msg = msg_t.decode(encoded_msg)
-- ...
end
local sub = lc:subscribe('somechannel', handler)
\endverbatim
<hr>
## unsubscribe {#lcm_userdata_unsubscribe}
\em Parameters
\li \c sub The subscription refernce to unsubscribe.
<em>Return Values</em>
\li (None.)
\em Description
The method removes a subscription created by \ref lcm_userdata_subscribe "subscribe". Also note that all subscriptions are automatically unsubscribed when the LCM userdata is garbage collected.
<em>Example Code</em>
\verbatim
local lcm = require('lcm')
local msg_t = require('msg_t') -- or any other message type
local lc = lcm.lcm.new()
local function handler(channel, encoded_msg)
local msg = msg_t.decode(encoded_msg)
-- ...
end
local sub = lc:subscribe('somechannel', handler)
--- ...
lc:unsubscribe(sub)
\endverbatim
<hr>
## handle {#lcm_userdata_handle}
\em Parameters
\li (None.)
<em>Return Values</em>
\li (None.)
\em Description
Waits for an incomming message, and dispatches handler callbacks as necessary. This method will block indefinitely until a message is recieved. When a message is received, all of the handler callbacks for the message's channel are invoked, in the same order they were \ref lcm_userdata_subscribe "subscribed".
<em>Example Code</em>
\verbatim
local lcm = require('lcm')
local lc = lcm.lcm.new()
lc:handle()
\endverbatim
<hr>
## handle_timeout {#lcm_userdata_handle_timeout}
\em Parameters
\li \c time The time to block, in milliseconds.
<em>Return Values</em>
\li A boolean: \c true if a message was received and handled, \c false otherwise.
\em Description
This method is like the normal \ref lcm_userdata_handle "handle" except it only blocks for a specified amount of time.
<em>Example Code</em>
\verbatim
local lcm = require('lcm')
local lc = lcm.lcm.new()
local ok = lc:handle_timeout(500)
if not ok then
print('timed out!')
end
\endverbatim
<hr>
## timedhandle (Deprecated) {#lcm_userdata_timedhandle}
This function is deprecated! Please use \ref lcm_userdata_handle_timeout "handle_timeout" instead!
\em Parameters
\li \c time The time to block, in seconds.
<em>Return Values</em>
\li A boolean: \c true if a message was received and handled, \c false otherwise.
\em Description
This method is like the normal \ref lcm_userdata_handle "handle" except it only blocks for a specified amount of time.
<em>Example Code</em>
\verbatim
local lcm = require('lcm')
local lc = lcm.lcm.new()
local ok = lc:timedhandle(0.5)
if not ok then
print('timed out!')
end
\endverbatim
|
