Class: Tinkerforge::BrickletGPS

Inherits:
Device
  • Object
show all
Defined in:
lib/tinkerforge/bricklet_gps.rb

Overview

Determine position, velocity and altitude using GPS

Constant Summary collapse

DEVICE_IDENTIFIER =

:nodoc:

222
DEVICE_DISPLAY_NAME =

:nodoc:

'GPS Bricklet'
CALLBACK_COORDINATES =

This callback is triggered periodically with the period that is set by BrickletGPS#set_coordinates_callback_period. The parameters are the same as for BrickletGPS#get_coordinates.

The CALLBACK_COORDINATES callback is only triggered if the coordinates changed since the last triggering and if there is currently a fix as indicated by BrickletGPS#get_status.

17
CALLBACK_STATUS =

This callback is triggered periodically with the period that is set by BrickletGPS#set_status_callback_period. The parameters are the same as for BrickletGPS#get_status.

The CALLBACK_STATUS callback is only triggered if the status changed since the last triggering.

18
CALLBACK_ALTITUDE =

This callback is triggered periodically with the period that is set by BrickletGPS#set_altitude_callback_period. The parameters are the same as for BrickletGPS#get_altitude.

The CALLBACK_ALTITUDE callback is only triggered if the altitude changed since the last triggering and if there is currently a fix as indicated by BrickletGPS#get_status.

19
CALLBACK_MOTION =

This callback is triggered periodically with the period that is set by BrickletGPS#set_motion_callback_period. The parameters are the same as for BrickletGPS#get_motion.

The CALLBACK_MOTION callback is only triggered if the motion changed since the last triggering and if there is currently a fix as indicated by BrickletGPS#get_status.

20
CALLBACK_DATE_TIME =

This callback is triggered periodically with the period that is set by BrickletGPS#set_date_time_callback_period. The parameters are the same as for BrickletGPS#get_date_time.

The CALLBACK_DATE_TIME callback is only triggered if the date or time changed since the last triggering.

21
FUNCTION_GET_COORDINATES =

:nodoc:

1
FUNCTION_GET_STATUS =

:nodoc:

2
FUNCTION_GET_ALTITUDE =

:nodoc:

3
FUNCTION_GET_MOTION =

:nodoc:

4
FUNCTION_GET_DATE_TIME =

:nodoc:

5
FUNCTION_RESTART =

:nodoc:

6
FUNCTION_SET_COORDINATES_CALLBACK_PERIOD =

:nodoc:

7
FUNCTION_GET_COORDINATES_CALLBACK_PERIOD =

:nodoc:

8
FUNCTION_SET_STATUS_CALLBACK_PERIOD =

:nodoc:

9
FUNCTION_GET_STATUS_CALLBACK_PERIOD =

:nodoc:

10
FUNCTION_SET_ALTITUDE_CALLBACK_PERIOD =

:nodoc:

11
FUNCTION_GET_ALTITUDE_CALLBACK_PERIOD =

:nodoc:

12
FUNCTION_SET_MOTION_CALLBACK_PERIOD =

:nodoc:

13
FUNCTION_GET_MOTION_CALLBACK_PERIOD =

:nodoc:

14
FUNCTION_SET_DATE_TIME_CALLBACK_PERIOD =

:nodoc:

15
FUNCTION_GET_DATE_TIME_CALLBACK_PERIOD =

:nodoc:

16
FUNCTION_GET_IDENTITY =

:nodoc:

255
FIX_NO_FIX =

:nodoc:

1
FIX_2D_FIX =

:nodoc:

2
FIX_3D_FIX =

:nodoc:

3
RESTART_TYPE_HOT_START =

:nodoc:

0
RESTART_TYPE_WARM_START =

:nodoc:

1
RESTART_TYPE_COLD_START =

:nodoc:

2
RESTART_TYPE_FACTORY_RESET =

:nodoc:

3

Constants inherited from Device

Device::DEVICE_IDENTIFIER_CHECK_MATCH, Device::DEVICE_IDENTIFIER_CHECK_MISMATCH, Device::DEVICE_IDENTIFIER_CHECK_PENDING, Device::RESPONSE_EXPECTED_ALWAYS_TRUE, Device::RESPONSE_EXPECTED_FALSE, Device::RESPONSE_EXPECTED_INVALID_FUNCTION_ID, Device::RESPONSE_EXPECTED_TRUE

Instance Attribute Summary

Attributes inherited from Device

#callback_formats, #expected_response_function_id, #expected_response_sequence_number, #high_level_callbacks, #registered_callbacks, #replaced, #uid

Instance Method Summary collapse

Methods inherited from Device

#check_validity, #dequeue_response, #enqueue_response, #get_api_version, #get_response_expected, #send_request, #set_response_expected, #set_response_expected_all

Constructor Details

#initialize(uid, ipcon) ⇒ BrickletGPS

Creates an object with the unique device ID uid and adds it to the IP Connection ipcon.



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
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 91

def initialize(uid, ipcon)
  super uid, ipcon, DEVICE_IDENTIFIER, DEVICE_DISPLAY_NAME

  @api_version = [2, 0, 1]

  @response_expected[FUNCTION_GET_COORDINATES] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_STATUS] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_ALTITUDE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_MOTION] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_DATE_TIME] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_RESTART] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_SET_COORDINATES_CALLBACK_PERIOD] = RESPONSE_EXPECTED_TRUE
  @response_expected[FUNCTION_GET_COORDINATES_CALLBACK_PERIOD] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_STATUS_CALLBACK_PERIOD] = RESPONSE_EXPECTED_TRUE
  @response_expected[FUNCTION_GET_STATUS_CALLBACK_PERIOD] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_ALTITUDE_CALLBACK_PERIOD] = RESPONSE_EXPECTED_TRUE
  @response_expected[FUNCTION_GET_ALTITUDE_CALLBACK_PERIOD] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_MOTION_CALLBACK_PERIOD] = RESPONSE_EXPECTED_TRUE
  @response_expected[FUNCTION_GET_MOTION_CALLBACK_PERIOD] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_DATE_TIME_CALLBACK_PERIOD] = RESPONSE_EXPECTED_TRUE
  @response_expected[FUNCTION_GET_DATE_TIME_CALLBACK_PERIOD] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_IDENTITY] = RESPONSE_EXPECTED_ALWAYS_TRUE

  @callback_formats[CALLBACK_COORDINATES] = [26, 'L k L k S S S S']
  @callback_formats[CALLBACK_STATUS] = [11, 'C C C']
  @callback_formats[CALLBACK_ALTITUDE] = [16, 'l l']
  @callback_formats[CALLBACK_MOTION] = [16, 'L L']
  @callback_formats[CALLBACK_DATE_TIME] = [16, 'L L']

  @ipcon.add_device self
end

Instance Method Details

#get_altitude ⇒ Object

Returns the current altitude and corresponding geoidal separation.

This data is only valid if there is currently a fix as indicated by BrickletGPS#get_status.



170
171
172
173
174
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 170

def get_altitude
  check_validity

  send_request FUNCTION_GET_ALTITUDE, [], '', 16, 'l l'
end

#get_altitude_callback_period ⇒ Object

Returns the period as set by BrickletGPS#set_altitude_callback_period.



262
263
264
265
266
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 262

def get_altitude_callback_period
  check_validity

  send_request FUNCTION_GET_ALTITUDE_CALLBACK_PERIOD, [], '', 12, 'L'
end

#get_coordinates ⇒ Object

Returns the GPS coordinates. Latitude and longitude are given in the “DD.dddddd°“ format, the value 57123468 means 57.123468°. The parameter “ns“ and “ew“ are the cardinal directions for latitude and longitude. Possible values for “ns“ and “ew“ are ‘N’, ‘S’, ‘E’ and ‘W’ (north, south, east and west).

PDOP, HDOP and VDOP are the dilution of precision (DOP) values. They specify the additional multiplicative effect of GPS satellite geometry on GPS precision. See ‘here <en.wikipedia.org/wiki/Dilution_of_precision_(GPS)>`__ for more information.

EPE is the “Estimated Position Error”. This is not the absolute maximum error, it is the error with a specific confidence. See ‘here <www.nps.gov/gis/gps/WhatisEPE.html>`__ for more information.

This data is only valid if there is currently a fix as indicated by BrickletGPS#get_status.



141
142
143
144
145
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 141

def get_coordinates
  check_validity

  send_request FUNCTION_GET_COORDINATES, [], '', 26, 'L k L k S S S S'
end

#get_coordinates_callback_period ⇒ Object

Returns the period as set by BrickletGPS#set_coordinates_callback_period.



226
227
228
229
230
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 226

def get_coordinates_callback_period
  check_validity

  send_request FUNCTION_GET_COORDINATES_CALLBACK_PERIOD, [], '', 12, 'L'
end

#get_date_time ⇒ Object

Returns the current date and time. The date is given in the format “ddmmyy“ and the time is given in the format “hhmmss.sss“. For example, 140713 means 14.07.13 as date and 195923568 means 19:59:23.568 as time.



194
195
196
197
198
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 194

def get_date_time
  check_validity

  send_request FUNCTION_GET_DATE_TIME, [], '', 16, 'L L'
end

#get_date_time_callback_period ⇒ Object

Returns the period as set by BrickletGPS#set_date_time_callback_period.



298
299
300
301
302
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 298

def get_date_time_callback_period
  check_validity

  send_request FUNCTION_GET_DATE_TIME_CALLBACK_PERIOD, [], '', 12, 'L'
end

#get_identity ⇒ Object

Returns the UID, the UID where the Bricklet is connected to, the position, the hardware and firmware version as well as the device identifier.

The position can be ‘a’, ‘b’, ‘c’, ‘d’, ‘e’, ‘f’, ‘g’ or ‘h’ (Bricklet Port). A Bricklet connected to an :ref:‘Isolator Bricklet <isolator_bricklet>` is always at position ’z’.

The device identifier numbers can be found :ref:‘here <device_identifier>`. |device_identifier_constant|



314
315
316
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 314

def get_identity
  send_request FUNCTION_GET_IDENTITY, [], '', 33, 'Z8 Z8 k C3 C3 S'
end

#get_motion ⇒ Object

Returns the current course and speed. A course of 0° means the Bricklet is traveling north bound and 90° means it is traveling east bound.

Please note that this only returns useful values if an actual movement is present.

This data is only valid if there is currently a fix as indicated by BrickletGPS#get_status.



184
185
186
187
188
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 184

def get_motion
  check_validity

  send_request FUNCTION_GET_MOTION, [], '', 16, 'L L'
end

#get_motion_callback_period ⇒ Object

Returns the period as set by BrickletGPS#set_motion_callback_period.



280
281
282
283
284
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 280

def get_motion_callback_period
  check_validity

  send_request FUNCTION_GET_MOTION_CALLBACK_PERIOD, [], '', 12, 'L'
end

#get_status ⇒ Object

Returns the current fix status, the number of satellites that are in view and the number of satellites that are currently used.

Possible fix status values can be:

"Value", "Description"

"1", "No Fix, BrickletGPS#get_coordinates, BrickletGPS#get_altitude and BrickletGPS#get_motion return invalid data"
"2", "2D Fix, only BrickletGPS#get_coordinates and BrickletGPS#get_motion return valid data"
"3", "3D Fix, BrickletGPS#get_coordinates, BrickletGPS#get_altitude and BrickletGPS#get_motion return valid data"

There is also a :ref:‘blue LED <gps_bricklet_fix_led>` on the Bricklet that indicates the fix status.



160
161
162
163
164
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 160

def get_status
  check_validity

  send_request FUNCTION_GET_STATUS, [], '', 11, 'C C C'
end

#get_status_callback_period ⇒ Object

Returns the period as set by BrickletGPS#set_status_callback_period.



244
245
246
247
248
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 244

def get_status_callback_period
  check_validity

  send_request FUNCTION_GET_STATUS_CALLBACK_PERIOD, [], '', 12, 'L'
end

#register_callback(id, &block) ⇒ Object

Registers a callback with ID id to the block block.



319
320
321
322
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 319

def register_callback(id, &block)
  callback = block
  @registered_callbacks[id] = callback
end

#restart(restart_type) ⇒ Object

Restarts the GPS Bricklet, the following restart types are available:

"Value", "Description"

"0", "Hot start (use all available data in the NV store)"
"1", "Warm start (don't use ephemeris at restart)"
"2", "Cold start (don't use time, position, almanacs and ephemeris at restart)"
"3", "Factory reset (clear all system/user configurations at restart)"



208
209
210
211
212
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 208

def restart(restart_type)
  check_validity

  send_request FUNCTION_RESTART, [restart_type], 'C', 8, ''
end

#set_altitude_callback_period(period) ⇒ Object

Sets the period with which the CALLBACK_ALTITUDE callback is triggered periodically. A value of 0 turns the callback off.

The CALLBACK_ALTITUDE callback is only triggered if the altitude changed since the last triggering.



255
256
257
258
259
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 255

def set_altitude_callback_period(period)
  check_validity

  send_request FUNCTION_SET_ALTITUDE_CALLBACK_PERIOD, [period], 'L', 8, ''
end

#set_coordinates_callback_period(period) ⇒ Object

Sets the period with which the CALLBACK_COORDINATES callback is triggered periodically. A value of 0 turns the callback off.

The CALLBACK_COORDINATES callback is only triggered if the coordinates changed since the last triggering.



219
220
221
222
223
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 219

def set_coordinates_callback_period(period)
  check_validity

  send_request FUNCTION_SET_COORDINATES_CALLBACK_PERIOD, [period], 'L', 8, ''
end

#set_date_time_callback_period(period) ⇒ Object

Sets the period with which the CALLBACK_DATE_TIME callback is triggered periodically. A value of 0 turns the callback off.

The CALLBACK_DATE_TIME callback is only triggered if the date or time changed since the last triggering.



291
292
293
294
295
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 291

def set_date_time_callback_period(period)
  check_validity

  send_request FUNCTION_SET_DATE_TIME_CALLBACK_PERIOD, [period], 'L', 8, ''
end

#set_motion_callback_period(period) ⇒ Object

Sets the period with which the CALLBACK_MOTION callback is triggered periodically. A value of 0 turns the callback off.

The CALLBACK_MOTION callback is only triggered if the motion changed since the last triggering.



273
274
275
276
277
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 273

def set_motion_callback_period(period)
  check_validity

  send_request FUNCTION_SET_MOTION_CALLBACK_PERIOD, [period], 'L', 8, ''
end

#set_status_callback_period(period) ⇒ Object

Sets the period with which the CALLBACK_STATUS callback is triggered periodically. A value of 0 turns the callback off.

The CALLBACK_STATUS callback is only triggered if the status changed since the last triggering.



237
238
239
240
241
 
# File 'lib/tinkerforge/bricklet_gps.rb', line 237

def set_status_callback_period(period)
  check_validity

  send_request FUNCTION_SET_STATUS_CALLBACK_PERIOD, [period], 'L', 8, ''
end