2.2.46. Geographic Location Command Class, version 2 [NEVER CERTIFIED]¶

Warning

THIS COMMAND CLASS HAS NEVER BEEN CERTIFIED

This command class has never been implemented and certified by a Z-Wave product. Therefore, this Command Class definition MAY be updated in a non-backwards compatible manner, or even removed.

Consult with the Z-Wave Alliance Application Work Group if you consider implementing this Command Class.

Z-Wave Geographic Location command class, version 2 adds the ability to report or store the GPS coordinates of a device with centimeter resolution. Sensor networks using Z-Wave Long Range (ZWLR) can be spread across an area of over 12 square miles. A reliable method of locating sensors in this large area is provided using Geographic Location Command Class, version 2.

The accuracy of most low-cost GPS receivers is only a few meters. Expensive GPS receivers can achieve centimeter resolution but those would typically not be used in an Internet of Things (IoT) application. There are two implementations of Geographic Location: 1) A device with its own GPS receiver; 2) a device which is assigned its GPS location at inclusion or commissioning. GPS receivers are expensive both in cost and power consumption. Applications such as tracking the movement of glaciers, tracking of farm equipment, or any application where the node will move may include a GPS receiver. Lower cost applications such as sensor networks may utilize a phone app during commissioning to assign the GPS location of the sensor. Moisture/temperature sensors in a vineyard or orchard would typically use this lower cost method where the location is fixed at commissioning time.

Geographic Location can simplify RF range testing as the exact GPS location of the device can be reported back to the controller as it is moved around an area. Heat maps can be generated showing exactly where the DUT is on a map with additional data such as transmit power and RSSI.

2.2.46.1. Z-Wave Geographic Location Command Class V2 obsoletes V1¶

This Geographic Location Command Class, version 2 obsoletes version 1 as no Z-Wave device was certified with Geographic Location, version 1. Version 1 has only seven bits of resolution resulting in 1+ kilometer of resolution.

2.2.46.2. Multi Channel Considerations¶

Multi Channel End Points SHOULD NOT support the Geographic Location Command Class. The location is for the entire device making Geographic Location apply to the root device and not specific endpoints.

2.2.46.3. Geographic Location V2 Features¶

Signed fixed point decimal longitude and latitude encoding with 23 bits of fraction yielding centimeter resolution
Altitude in centimeters
Status byte with read-only bit and GPS quality fields

2.2.46.4. Geographic Location V2 Examples¶

The table below gives a few examples of the NMEA sentence from a GPS receiver, the hex value stored in Geographic Location CC V2 and the conversion back to floating point. Note that due to floating point round off differences, the least significant digit might be slightly different.

Table 2.253 Geographic Location examples¶
Location	North most point of the Eiffel Tower Paris France
NMEA	$GPGGA,220333.093,4851.542,N,00217.669,E,1,12,1.0,37.0,M,0.0,M,,*55
Hexadecimal	Lat=0x0125b1a1, Lon=0x186df4cd, Alt=0x0e7a
GPS Decimal	48.859032, 2.294483, 37.06
Location	Death Valley US, 87m below sea level
NMEA	$GPGGA,220333.093,3613.846,N,11647.047,W,1,12,1.0,-86.9,M,0.0,M,,*64
Hexadecimal	Lat=0x121d89c3, Lon=0xc59ba211, Alt=0xffde07
GPS Decimal	36.230766, -116.784119, -86.97
Location	Sydney Opera House Australia
NMEA	$GNGGA,221800.175,3351.398,S,15112.920,E,1,12,1.0,4.214,M,0.0,M,,*6F
Hexadecimal	Lat=0xef1259d7, Lon=0x4b9b900a, Alt=0x0001a5
GPS Decimal	-33.856632, 151.215332, 4.21
Location	Christ Redeemer Statue Brazil
NMEA	$GPGGA,221800.175,2257.114,S,04312.624,W,1,12,1.0,703.0333,M,0.0,M,,*5E
Hexadecimal	Lat=0xf4862825, Lon=0xea65119d, Alt=0x01129f
GPS Decimal	-22.951900, -42.210400, 703.03
Location	McMurdo Station Antarctica
NMEA	$GPGGA,221800.175,7750.807777,S,16640.261234,E,1,12,1.0,118.111,M,0.0,M,,*78
Hexadecimal	Lat=0xd9139c2e, Lon=0x5355e400, Alt=0x002e2
GPS Decimal	-77.846794, 166.671021, 118.11

2.2.46.5. Geographic Location Set Command¶

\requirement{CC:008C.02.01.11.001}{0}

This command is used to set latitude, longitude and altitude in devices that do not have a GPS receiver. Devices without a GPS receiver MUST set the RO bit of the Report Status byte to 0. If a device has a GPS receiver (RO bit of the Report Status byte=1), this command MUST be ignored.

\requirement{CC:008C.02.01.11.002}{0}

On factory reset or exclusion a non-GPS device (RO=0) MUST set all values to an invalid value.

Table 2.254 Geographic Location Set Command, version 2¶
7	6	5	4	3	2	1	0
Command Class = COMMAND_CLASS_GEOGRAPHIC_LOCATION (0x8C)
Command = GEOGRAPHIC_LOCATION_SET (0x01)
Longitude Sign	Longitude Integer (7:1)
Longitude Integer (0)	Longitude Fraction (22:16)
Longitude Fraction (15:8)
Longitude Fraction (7:0)
Latitude Sign	Latitude Integer (7:1)
Latitude Integer (0)	Latitude Fraction (22:16)
Latitude Fraction (15:8)
Latitude Fraction (7:0)
Altitude (23:16) MSB
Altitude (15:8)
Altitude (7:0) LSB

Longitude (32 bit signed fixed point with 23 bits of fraction)

\requirement{CC:008C.02.01.33.002}{0}

Longitude is a 32-bit fixed point signed twos-complement value from -180.0 to +180.0. The sign is the most significant bit. The next 8 bits are the integer portion. The remaining 23 bits are the fraction. Zero is at the prime meridian in Greenwich England. Positive values are east of the prime meridian, negative values are west. The default value upon factory reset, exclusion or if the GPS receiver does not have a valid location MUST be 0x7FFFFFFF which is an invalid value of +256.0. Longitude can be converted to a floating point value using Javascript with a command similar to: const longitude=payload.readInt32BE(0) / (1 << 23); .

Latitude (32 bit signed fixed point with 23 bits of fraction)

Latitude is a 32-bit fixed point signed twos-complement value from -90.0 to +90.0. The sign is the most significant bit. The next 8 bits are the integer portion. The remaining 23 bits are the fraction. Zero is at the equator with north being positive and south being negative. The rules for Longitude apply to Latitude and conversion is similar.

Altitude (24 bit signed integer)

\requirement{CC:008C.02.01.33.003}{0}

Altitude is a twos-complement signed 24-bit integer value in centimeters above/below mean sea level. Altitude is often less accurate in most GPS receivers than the longitude or latitude. Typical altitude accuracy is 10 meters or less in receivers with 1 meter longitude/latitude resolution. Valid values are from +83km (0x7FFFFF) to -6,378 km (radius of the earth). Upon factory reset, exclusion or setting any invalid value the Altitude MUST be set to 0x800000 (-83km). Conversion using Javascript is similar to: const altitude = payload.readIntBE(8, 3) / 100; where the altitude object is now a signed floating point value in meters. Note the binary value is 3 bytes long.

2.2.46.6. Geographic Location Get Command¶

This command is used to request latitude, longitude and altitude from a device.

\requirement{CC:008C.02.02.11.002}{0}

The Geographic Location Report Command MUST be returned in response to this command.

This command MUST NOT be issued via multicast addressing.

A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods.

Table 2.255 Geographic Location Get Command, version 2¶
7	6	5	4	3	2	1	0
Command Class = COMMAND_CLASS_GEOGRAPHIC_LOCATION (0x8C)
Command = GEOGRAPHIC_LOCATION_GET (0x02)

2.2.46.7. Geographic Location Report Command¶

This command returns latitude, longitude, altitude and status from a device in a Z-Wave network. The command is identical to the SET command with the addition of the STATUS byte at the end.

Table 2.256 Geographic Location Report Command, version 2¶
7	6	3	2
Command Class = COMMAND_CLASS_GEOGRAPHIC_LOCATION (0x8C)
Command = GEOGRAPHIC_LOCATION_REPORT (0x03)
Longitude Sign	Longitude Integer (7:1)
Longitude Integer (0)	Longitude Fraction (22:16)
Longitude Fraction (15:8)
Longitude Fraction (7:0)
Latitude Sign	Latitude Integer (7:1)
Latitude Integer (0)	Latitude Fraction (22:16)
Latitude Fraction (15:8)
Latitude Fraction (7:0)
Altitude (23:16) MSB
Altitude (15:8)
Altitude (7:0) LSB
Quality		Read Only	Reserved

Refer to description under the Geographic Location Set Command.

Longitude & Latitude (32 bits)

See the SET command for details of the Longitude and Latitude values.

Altitude (24 bits)

See the SET command for details of the Altitude.

Status (8 bits)

The Status Byte has several fields which provide additional information on the other values. The STATUS byte is read-only and is NOT included in a SET command.

Quality (4 bits)

\requirement{CC:008C.02.03.11.001}{0}

The Quality field MUST be zero when the Read-Only (RO) bit is 0 indicating a device without a GPS receiver. In systems with a GPS receiver, the Quality field is an indicator of the signal quality of the GPS signal. A minimum of four satellites are required for an accurate GPS reading. A value of less than 4 indicates the coordinates SHOULD be ignored. The Quality field SHOULD contain the number of satellites in use with the last reading. If more than 15 satellites are in use, the Quality field MUST be set to 15.

RECOMMENDATION is to use values 0..3 as error codes:

0 = no GPS receiver communication indicating hardware failure,
1 = NMEA checksum failure indicating communication errors (out of sync or buffer over/under runs),
2 and 3 are reserved but can be used for other error conditions during debug.

Read Only (1 bit)

\requirement{CC:008C.02.03.11.002}{0}

Read Only (RO) is set to one when a GPS receiver is attached to the system indicating the Longitude, Latitude and Altitude values are Read-Only and cannot be SET. When RO=1, SET commands MUST be ignored. RO is zero when the geographic location values are set from an external device, typically a phone application during commissioning.

Reserved (3 bits)

The Reserved bits MUST be ignored.