DMPACK User Guide

Lua API

Parts of the DMPACK library are exposed to Lua through a distinct API. Log levels and error codes are registered as named parameters. The GeoCOM API includes named parameters of enumerators and return codes beside functions for request preparation. The GeoCOM functions may be called from the configuration file of dmserial to initialise jobs, for example:

jobs = {
  {
    --
    -- Start and initialisation of station p99.
    -- Attribute `onetime` must be enabled!
    --
    onetime = true,
    delay = 5 * 1000,
    observation = {
      -- Initialise RTS and send responses to dmdb.
      name = "init_tps",
      target_id = "p99",
      receivers = { "dmdb" },
      requests = {
        -- Up to 8 requests are allowed per observation.
        geocom_beep_normal(),
        geocom_set_refraction_mode(1),
        geocom_set_inclination_correction(true),
        geocom_set_user_atr_mode(true),
        geocom_set_target_type(GEOCOM_BAP_REFL_USE),
        geocom_set_prism_type(GEOCOM_BAP_PRISM_ROUND)
    }
  },
  {
    --
    -- Single measurement of target p01 every 10 seconds.
    --
    onetime = false,
    delay = 10 * 1000,
    observation = {
      -- Set position and start measurement, send responses to dmdb.
      name = "get_p01",
      target_id = "p01",
      receivers = { "dmdb" },
      requests = {
        geocom_set_position(gon2rad(0.0), gon2rad(100.0),
                            GEOCOM_AUT_NORMAL, GEOCOM_AUT_TARGET),
        geocom_do_measure(GEOCOM_TMC_DEF_DIST, GEOCOM_TMC_AUTO_INC),
        geocom_get_simple_measurement(3000, GEOCOM_TMC_AUTO_INC)
      }
    }
  }
}

The targets p01 and p99 have to exist in the observation database. The performed observations are forwarded to dmdb.

Parameters

Named log level parameters
#	Name	Level
0	`LL_NONE`	invalid level
1	`LL_DEBUG`	debug level
2	`LL_INFO`	info level
3	`LL_WARNING`	warning level
4	`LL_ERROR`	error level
5	`LL_CRITICAL`	critical level
6	`LL_USER`	user-defined level

Named response value type parameters
#	Name	Type
0	`RESPONSE_TYPE_REAL64`	8-byte signed real
1	`RESPONSE_TYPE_REAL32`	4-byte signed real
2	`RESPONSE_TYPE_INT64`	8-byte signed integer
3	`RESPONSE_TYPE_INT32`	4-byte signed integer
4	`RESPONSE_TYPE_LOGICAL`	1-byte boolean
5	`RESPONSE_TYPE_BYTE`	byte
6	`RESPONSE_TYPE_STRING`	byte string

Functions

The following utility functions are exported to convert units:

deg2gon(deg) – Converts degrees to gradians.
deg2rad(deg) – Converts degrees to radiants.
gon2deg(gon) – Converts gradians to degrees.
gon2rad(gon) – Converts gradians to radiants.
rad2deg(rad) – Converts radiants to degrees.
rad2gon(rad) – Converts radiants to gradians.

The Lua functions may be called inside of configuration files. For testing, load the shared library libdmpack.so first, for example:

-- Import the shared library `libdmpack.so`.
-- The file must be located in the Lua search path.
require("libdmpack")

-- Convert angle from [deg] to [gon]. Output: 400.0
gon = deg2gon(360.0)
print(gon)

GeoCOM

The GeoCOM API for Lua is used to automate the creation of observation requests in DMPACK configuration files. The Lua function names do not match the official GeoCOM API names. All functions start with prefix geocom_, all named parameters with GEOCOM_. The names of the requests are set to the name of the respective function without prefix.

Comparison between the Leica GeoCOM API and the DMPACK GeoCOM API for Lua
Leica GeoCOM API	DMPACK GeoCOM API
`AUS_GetUserAtrState`	geocom_get_user_atr_mode
`AUS_GetUserLockState`	geocom_get_user_lock_mode
`AUS_SetUserAtrState`	geocom_set_user_atr_mode
`AUS_SetUserLockState`	geocom_set_user_lock_mode
`AUT_ChangeFace`	geocom_change_face
`AUT_FineAdjust`	geocom_fine_adjust
`AUT_GetFineAdjustMode`	geocom_get_fine_adjust_mode
`AUT_GetSearchArea`	geocom_get_search_area
`AUT_GetUserSpiral`	geocom_get_user_spiral
`AUT_LockIn`	geocom_lock_in
`AUT_MakePositioning`	geocom_set_position
`AUT_PS_EnableRange`	geocom_ps_enable_range
`AUT_PS_SearchNext`	geocom_ps_search_next
`AUT_PS_SearchWindow`	geocom_ps_search_window
`AUT_PS_SetRange`	geocom_ps_set_range
`AUT_ReadTimeout`	geocom_get_timeout
`AUT_ReadTol`	geocom_get_tolerance
`AUT_Search`	geocom_get_search
`AUT_SetFineAdjustMode`	geocom_set_fine_adjust_mode
`AUT_SetSearchArea`	geocom_set_search_area
`AUT_SetTimeout`	geocom_set_positioning_timeout
`AUT_SetTol`	geocom_set_tolerance
`AUT_SetUserSpiral`	geocom_set_user_spiral
`BAP_GetATRSetting`	geocom_get_atr_setting
`BAP_GetMeasPrg`	geocom_get_measurement_program
`BAP_GetPrismDef`	geocom_get_prism_definition
`BAP_GetRedATRFov`	geocom_get_reduced_atr_fov
`BAP_GetTargetType`	geocom_get_target_type
`BAP_GetUserPrismDef`	geocom_get_user_prism_definition
`BAP_MeasDistanceAngle`	geocom_measure_distance_angle
`BAP_SearchTarget`	geocom_search_target
`BAP_SetATRSetting`	geocom_set_atr_mode
`BAP_SetAtmCorr`	geocom_set_atmospheric_correction
`BAP_SetAtmPpm`	geocom_set_atmospheric_ppm
`BAP_SetMeasPrg`	geocom_set_measurement_program
`BAP_SetPrismType`	geocom_set_prism_type
`BAP_SetPrismType2`	geocom_set_prism_type_v2
`BAP_SetRedATRFov`	geocom_set_reduced_atr_fov
`BAP_SetTargetType`	geocom_set_target_type
`BAP_SetUserPrismDef`	geocom_set_user_prism_definition
`BMM_BeepAlarm`	geocom_beep_alarm
`BMM_BeepNormal`	geocom_beep_normal
`COM_GetBinaryAvailable`	geocom_get_binary_mode
`COM_GetDoublePrecision`	geocom_get_double_precision
`COM_GetSWVersion`	geocom_get_geocom_version
`COM_NullProc`	geocom_null
`COM_SetBinaryAvailable`	geocom_set_binary_mode
`COM_SetDoublePrecision`	geocom_set_double_precision
`COM_SwitchOffTPS`	geocom_switch_off
`COM_SwitchOffTPS`	geocom_switch_on
`CSV_CheckPower`	geocom_get_power
`CSV_GetDateTimeCentiSec`	geocom_get_date_time_centi
`CSV_GetDateTime`	geocom_get_date_time
`CSV_GetDeviceConfig`	geocom_get_device_config
`CSV_GetInstrumentName`	geocom_get_instrument_name
`CSV_GetInstrumentNo`	geocom_get_instrument_number
`CSV_GetIntTemp`	geocom_get_internal_temperature
`CSV_GetReflectorlessClass`	geocom_get_reflectorless_class
`CSV_GetSWVersion`	geocom_get_software_version
`CSV_SetDateTime`	geocom_set_date_time
`EDM_GetEglIntensity`	geocom_get_egl_intensity
`EDM_Laserpointer`	geocom_set_laser_pointer
`EDM_SetEglIntensity`	geocom_set_egl_intensity
`FTR_AbortDownload`	geocom_abort_download
`FTR_AbortList`	geocom_abort_list
`FTR_Delete`	geocom_delete
`FTR_Download`	geocom_download
`FTR_List`	geocom_list
`FTR_SetupDownload`	geocom_setup_download
`FTR_SetupList`	geocom_setup_list
`IMG_GetTccConfig`	geocom_get_image_config
`IMG_SetTccConfig`	geocom_set_image_config
`IMG_TakeTccImage`	geocom_take_image
`IOS_BeepOff`	geocom_beep_off
`IOS_BeepOn`	geocom_beep_on
`MOT_ReadLockStatus`	geocom_get_lock_status
`MOT_SetVelocity`	geocom_set_velocity
`MOT_StartController`	geocom_start_controller
`MOT_StopController`	geocom_stop_controller
`SUP_GetConfig`	geocom_get_config
`SUP_SetConfig`	geocom_set_config
`TMC_DoMeasure`	geocom_do_measure
`TMC_GeoPpm`	geocom_get_geometric_ppm
`TMC_GetAngSwitch`	geocom_get_angle_correction
`TMC_GetAngle1`	geocom_get_angle_complete
`TMC_GetAngle5`	geocom_get_angle
`TMC_GetAtmCorr`	geocom_get_atmospheric_correction
`TMC_GetAtmPpm`	geocom_get_atmospheric_ppm
`TMC_GetCoordinate`	geocom_get_coordinate
`TMC_GetEdmMode`	geocom_get_edm_mode
`TMC_GetFace`	geocom_get_face
`TMC_GetFullMeas`	geocom_get_full_measurement
`TMC_GetHeight`	geocom_get_height
`TMC_GetInclineSwitch`	geocom_get_inclination_correction
`TMC_GetPrismCorr`	geocom_get_prism_constant
`TMC_GetPrismType`	geocom_get_prism_type
`TMC_GetPrismType2`	geocom_get_prism_type_v2
`TMC_GetRefractiveMethod`	geocom_get_refraction_mode
`TMC_GetSignal`	geocom_get_signal
`TMC_GetSimpleCoord`	geocom_get_simple_coordinates
`TMC_GetSimpleMea`	geocom_get_simple_measurement
`TMC_GetSlopeDistCorr`	geocom_get_slope_distance_correction
`TMC_GetStation`	geocom_get_station
`TMC_IfDataAzeCorrError`	geocom_get_atr_error
`TMC_IfDataIncCorrError`	geocom_get_inclination_error
`TMC_QuickDist`	geocom_get_quick_distance
`TMC_SetAngSwitch`	geocom_set_angle_correction
`TMC_SetEdmMode`	geocom_set_edm_mode
`TMC_SetGeoPpm`	geocom_set_geometric_ppm
`TMC_SetHandDist`	geocom_set_distance
`TMC_SetHeight`	geocom_set_height
`TMC_SetInclineSwitch`	geocom_set_inclination_correction
`TMC_SetOrientation`	geocom_set_orientation
`TMC_SetPrismCorr`	geocom_set_prism_constant
`TMC_SetRefractiveMethod`	geocom_set_refraction_mode
`TMC_SetStation`	geocom_set_station

geocom_abort_download()

Returns request for FTR_AbortDownload procedure. Creates request to abort or end the file download command.

geocom_abort_list()

Returns request for FTR_AbortList procedure. Creates request to abort or end the file list command.

geocom_beep_alarm()

Returns request for BMM_BeepAlarm procedure. Creates request to output an alarm signal (triple beep).

geocom_beep_normal()

Returns request for BMM_BeepNormal procedure. Creates request to output an alarm signal (single beep).

geocom_beep_off()

Returns request for IOS_BeepOff procedure. Creates request to stop an active beep signal.

geocom_beep_on(intensity)

intensity (integer) – Intensity of the beep signal.

Returns request for IOS_BeepOn procedure. Creates request for continuous beep signal of given intensity from 0 to 100. The constant GEOCOM_IOS_BEEP_STDINTENS sets the intensity to 100.

geocom_change_face(pos_mode, atr_mode)

pos_mode (integer) – Position mode (GEOCOM_AUT_POSMODE).
atr_mode (integer) – ATR mode (GEOCOM_AUT_ATRMODE).

Returns request for AUT_ChangeFace procedure. Creates request for turning the telescope to the other face.

If pos_mode is GEOCOM_AUT_NORMAL, the instrument uses the current value of the compensator. For positioning distances > 25 gon, this mode might tend to inaccuracy. If set to GEOCOM_AUT_PRECISE, it tries to measure the exact inclination of the target. Tends to long positioning time.

If atr_mode is GEOCOM_AUT_POSITION, the instrument uses conventional positioning to other face. If set to GEOCOM_AUT_TARGET, it tries to position into a target in the destination area. This mode requires activated ATR.

geocom_delete(device_type, file_type, day, month, year, file_name)

device_type (integer) – Internal memory or memory card (GEOCOM_FTR_DEVICETYPE).
file_type (integer) – Type of file (GEOCOM_FTR_FILETYPE).
day (integer) – Day of month (DD).
month (integer) – Month (MM).
year (integer) – Year (YY).
file_name (string) – Name of file to delete.

Returns request for FTR_Delete procedure. Creates request for deleting one or more files. Wildcards may be used to delete multiple files. If the deletion date is valid, only files older than the deletion date are deleted.

geocom_do_measure(tmc_prog, inc_mode)

tmc_prog (integer) – Measurement program (GEOCOM_TMC_MEASURE_PRG).
inc_mode (integer) – Inclination measurement mode (GEOCOM_TMC_INCLINE_PRG).

Returns request for TMC_DoMeasure procedure. Creates request for trying a distance measurement. This command does not return any values. If a distance measurement is performed in measurement program GEOCOM_TMC_DEF_DIST, the distance sensor will work in the set EDM mode.

geocom_download(block_number)

block_number (integer) – Block number to download (0 – 65535).

Returns request for FTR_Download procedure. Creates request to get a single block of data. The geocom_setup_download() function has to be called first. The block sequence starts with 1. The download process will be aborted if the block number is set to 0. The maximum block number is 65535. The file size is therefore limited to 28 MiB. The function should not be used inside of configuration files.

geocom_fine_adjust(search_hz, search_v)

search_hz (number) – Search range, Hz axis [rad].
search_v (number) – Search range, V axis [rad].

Returns request for AUT_FineAdjust procedure. Creates request for automatic target positioning.

The procedure positions the telescope onto the target prosm and measures the ATR Hz and V deviations. If the target is not within the visible area of the ATR sensor (field of view), a target search will be executed. The target search range is limited by the parameter search_v in V direction, and by parameter search_hz in Hz direction. If no target was found, the instrument turns back to the initial start position.

The Fine Adjust Lock-in towards a target is terminated by this procedure call. After positioning, the lock mode will be active. The timeout of the operation is set to 5 seconds, regardless of the general position timeout settings. The position tolerance depends on the previously selected find adjust mode.

The tolerance settings have no influence to this operation. The tolerance settings and the ATR precision depend on the instrument class and the used EDM mode.

geocom_get_angle(inc_mode)

inc_mode (integer) – Inclination measurement mode (GEOCOM_TMC_INCLINE_PRG).

Returns request for TMC_GetAngle5 procedure. Creates request for returning a simple angle measurement. The function starts an angle measurement and returns the results.

geocom_get_angle_complete(inc_mode)

inc_mode (integer) – Inclination measurement mode (GEOCOM_TMC_INCLINE_PRG).

Returns request for TMC_GetAngle1 procedure. Creates request for returning a complete angle measurement. The function starts an angle and, depending on the configuration, an inclination measurement, and returns the results.

geocom_get_angle_correction()

Returns request for TMC_GetAngSwitch procedure. Creates request for getting the angular correction status.

geocom_get_atmospheric_correction()

Returns request for TMC_GetAtmCorr procedure. Creates request for getting the atmospheric correction parameters

geocom_get_atmospheric_ppm()

Returns request for TMC_GetAtmPpm procedure. Creates request for getting the atmospheric ppm correction factor.

geocom_get_atr_error()

Returns request for TMC_IfDataAzeCorrError procedure. Creates request for getting the ATR error status.

geocom_get_atr_setting()

Returns request for BAP_GetATRSetting procedure. Creates request for getting the current ATR low-vis mode.

geocom_get_binary_mode()

Returns request for COM_GetBinaryAvailable procedure. Creates request for getting the binary attribute of the server.

geocom_get_config()

Returns request for SUP_GetConfig procedure. Creates request for getting the power management configuration status. The power timeout specifies the time after which the device switches into the mode indicated by response autopwr.

geocom_get_coordinate(wait_time, inc_mode)

wait_time (integer) – Delay to wait for the distance measurement to finish [msec].
inc_mode (integer) – Inclination measurement mode (GEOCOM_TMC_INCLINE_PRG).

Returns request for TMC_GetCoordinate procedure. Creates request for getting the coordinates of a measured point.

This function conducts an angle and, in dependence of the selected inc_mode, an inclination measurement, and the calculates the coordinates of the measured point with the last distance. The argument wait_time specifies the delay to wait for the distance measurement to finish. Single and tracking measurements are supported. The quality of the result is returned in the GeoCOM return code.

geocom_get_date_time()

Returns request for CSV_GetDateTime procedure. Creates request for getting the current date and time of the instrument. A possible response may look like %R1P,0,0:0,1996,'07','19','10','13','2f'.

geocom_get_date_time_centi()

Returns request for CSV_GetDateTimeCentiSec procedure. Creates request for getting the current date and time of the instrument, including centiseconds.

geocom_get_device_config()

Returns request for CSV_GetDeviceConfig procedure. Creates request for getting the instrument configuration.

geocom_get_double_precision()

Returns request for COM_GetDoublePrecision procedure. Creates request for getting the double precision setting – the number of digits to the right of the decimal point – when double floating-point values are transmitted.

geocom_get_edm_mode()

Returns request for TMC_GetEdmMode procedure. Creates request for getting the EDM measurement mode.

geocom_get_egl_intensity()

Returns request for EDM_GetEglIntensity procedure. Creates request for getting the value of the intensity of the electronic guide light (EGL).

geocom_get_face()

Returns request for TMC_GetFace procedure. Creates request for getting the face of the current telescope position.

geocom_get_fine_adjust_mode()

Returns request for AUT_GetFineAdjustMode procedure. Creates request for getting the fine adjustment positioning mode.

geocom_get_full_measurement(wait_time, inc_mode)

wait_time (integer) – Delay to wait for the distance measurement to finish [msec].
inc_mode (integer) – Inclination measurement mode (GEOCOM_TMC_INCLINE_PRG).

Returns request for TMC_GetFullMeas procedure. The GeoCOM function returns angle, inclination, and distance measurement data, including accuracy and measurement time. This command does not issue a new distance measurement. A distance measurement has to be started in advance. If the distance is valid, the function ignores wait_time and returns the results immediately. If no valid distance is available, and the measurement unit is not activated, the angle measurement result is returned after the waiting time.

geocom_get_geocom_version()

Returns request for COM_GetSWVersion procedure. Creates request for getting the GeoCOM server software version.

geocom_get_geometric_ppm()

Returns request for TMC_GeoPpm procedure. Creates request for getting the geometric ppm correction factor.

geocom_get_height()

Returns request for TMC_GetHeight procedure. Creates request for getting the current reflector height.

geocom_get_image_config(mem_type)

mem_type (integer) – Memory device type (GEOCOM_IMG_MEM_TYPE).

Returns request for IMG_GetTccConfig procedure. Creates request to read the current image configuration. The response subfunc is a binary combination of the following settings:

1 – Test image.
2 – Automatic exposure time selection.
4 – Two-times sub-sampling.
8 – Four-times sub-sampling.

geocom_get_inclination_correction()

Returns request for TMC_GetInclineSwitch procedure. Creates request for getting the dual-axis compensator status

geocom_get_inclination_error()

Returns request for TMC_IfDataIncCorrError procedure. Creates request for getting the inclination error status.

geocom_get_instrument_name()

Returns request for CSV_GetInstrumentName procedure. Creates request for getting the Leica-specific instrument name.

geocom_get_instrument_number()

Returns request for CSV_GetInstrumentNo procedure. Creates request for getting the factory defined instrument number.

geocom_get_internal_temperature()

Returns request for CSV_GetIntTemp procedure. Creates request for getting the internal temperature of the instrument, measured on the mainboard side.

geocom_get_lock_status()

Returns request for MOT_ReadLockStatus procedure. Creates request for returning the condition of the Lock-In control.

geocom_get_measurement_program()

Returns request for BAP_GetMeasPrg procedure. Creates request for getting the distance measurement mode of the instrument.

geocom_get_power()

Returns request for CSV_CheckPower procedure. Creates request for checking the available power.

geocom_get_prism_constant()

Returns request for TMC_GetPrismCorr procedure. Creates request for getting the prism constant.

geocom_get_prism_definition(prism_type)

prism_type (integer) – Prism type (GEOCOM_BAP_PRISMTYPE).

Returns request for BAP_GetPrismDef procedure. Creates request for getting the default prism definition.

geocom_get_prism_type()

Returns request for TMC_GetPrismType procedure. Creates request for getting the default prism type.

geocom_get_prism_type_v2()

Returns request for TMC_GetPrismType2 procedure. Creates request for getting the default or user prism type.

geocom_get_quick_distance()

Returns request for TMC_QuickDist procedure. Creates request for returning the slope distance and both angles. The function starts an EDM tracking measurement, and waits until a distance has been measured. Then, it returns the angles and the slope distance, but no coordinates. If no distance could be measured, only angles and an error code are returned. A measurement may be aborted by calling geocom_do_measure().

geocom_get_reduced_atr_fov()

Returns request for BAP_GetRedATRFov procedure. Creates request for getting the reduced ATR field of view.

geocom_get_reflectorless_class()

Returns request for CSV_GetReflectorlessClass procedure. Creates request for getting the RL type. The function returns the class of the reflectorless and long-range distance measurement of the instrument.

geocom_get_refraction_mode()

Returns request for TMC_GetRefractiveMethod procedure. Creates request for getting the refraction model. The function is used to get the current refraction model. Changing the method is not indicated on the interface of the instrument.

geocom_get_search_area()

Returns request for AUT_GetSearchArea procedure. Creates request for getting the dimensions of the PowerSearch window. This command is valid for all instruments, but has only effects for instruments equipped with PowerSearch.

geocom_get_signal()

Returns request for TMC_GetSignal procedure. Creates request for getting the EDM signal intensity. The function can only perform a measurement if the signal measurement mode is activated. Start the signal measurement with geocom_do_measure() in mode GEOCOM_TMC_SIGNAL. After the measurement, the EDM must be switched off with mode GEOCOM_TMC_CLEAR. While measuring, there is no angle data available.

geocom_get_simple_coordinates(wait_time, inc_mode)

wait_time (integer) – Delay to wait for the distance measurement to finish [msec].
inc_mode (integer) – Inclination measurement mode (GEOCOM_TMC_INCLINE_PRG).

Returns request for TMC_GetSimpleCoord procedure. The API function returns the cartesian coordinates if a valid distance is set. The argument wait_time sets the maximum time to wait for a valid distance. Without a valid distance, the coordinates are set to 0.0, and an error is returned. The coordinate calculation requires inclination results. The argument inc_mode sets the inclination measurement mode.

geocom_get_simple_measurement(wait_time, inc_mode)

wait_time (integer) – Delay to wait for the distance measurement to finish [msec].
inc_mode (integer) – Inclination measurement mode (GEOCOM_TMC_INCLINE_PRG).

Returns request for TMC_GetSimpleMea procedure. The API function returns the angles and distance measurement data. The argument wait_time sets the maximum time to wait for a valid distance. If a distance is available, the wait time is ignored.

geocom_get_slope_distance_correction()

Returns request for TMC_GetSlopeDistCorr procedure. The function returns the total ppm value (atmospheric ppm + geometric ppm) plus the current prism constant.

geocom_get_software_version()

Returns request for CSV_GetSWVersion procedure. Creates request for getting the system software version of the instrument.

geocom_get_station()

Returns request for TMC_GetStation procedure. Creates request for getting the station coordinates of the instrument.

geocom_get_target_type()

Returns request for BAP_GetTargetType procedure. Creates request for getting the EDM type. The function returns the current EDM type (GEOCOM_BAP_TARGET_TYPE) for distance measurements: reflector (IR) or reflectorless (RL).

geocom_get_timeout()

Returns request for AUT_ReadTimeout procedure. Creates request for getting the timeout for positioning. The function returns the maximum time to perform positioning.

geocom_get_tolerance()

Returns request for AUT_ReadTol procedure. The function returns the positioning tolerances of the Hz and V instrument axis.

geocom_get_user_atr_mode()

Returns request for AUS_GetUserAtrState procedure. Creates request for getting the status of the ATR mode.

geocom_get_user_lock_mode()

Returns request for AUS_GetUserLockState procedure. Creates request for getting the status of the lock mode.

geocom_get_user_prism_definition(name)

name (string) – Prism name.

Returns equest of BAP_GetUserPrismDef procedure. Creates request for getting the user prism definition.

geocom_get_user_spiral()

Returns request for AUT_GetUserSpiral procedure. The function returns the current dimensions of the searching spiral. Requires at least a TCA instrument.

geocom_list(next)

next (bool) – First or next entry.

Returns request for FTR_List procedure. Creates request for listing file information.

geocom_lock_in()

Returns request for AUT_LockIn procedure. Creates request for starting the target tracking. The API function will start the target tracking if the lock mode has been activated through geocom_set_user_lock_mode(). The geocom_fine_adjust() call must have finished successfully before executing this function.

geocom_measure_distance_angle(dist_mode)

dist_mode (integer) – Distance measurement program (GEOCOM_BAP_MEASURE_PRG).

Returns request for BAP_MeasDistanceAngle procedure. Creates request for measuring Hz, V angles and a single distance. The API function measures angles and a single distance depending on the distance measurement mode dist_mode. It is not suited for continuous measurements (lock mode and TRK mode), and uses the current automation settings.

geocom_null()

Returns request for COM_NullProc procedure. Creates request for checking the communication.

geocom_ps_enable_range(enabled)

enabled (bool) – Enable PowerSearch.

Returns request for AUT_PS_EnableRange procedure. The function enabled or disables the predefined PowerSearch window including the PowerSearch range limits set by API call geocom_ps_set_range() (requires GeoCOM robotic licence). If enabled is false, the default range is set to ≤ 400 m.

geocom_ps_search_next(direction, swing)

direction (integer) – Searching direction (GEOCOM_AUT_CLOCKWISE or GEOCOM_AUT_ANTICLOCKWISE).
swing (bool) – Searching starts –10 gon to the given direction.

Returns request for AUT_PS_SearchNext procedure. The function executes the 360° default PowerSearch and searches for the next targets. A previously defined PowerSearch window of geocom_set_search_area() is not taken into account. Use API call geocom_ps_search_window() first.

geocom_ps_search_window()

Returns request for AUT_PS_SearchWindow procedure. Creates request for starting PowerSearch. The function starts PowerSearch in the window defined by API calls geocom_set_search_area() and geocom_ps_set_range() (requires GeoCOM robotic licence).

geocom_ps_set_range(min_dist, max_dist)

min_dist (integer) – Min. distance to prism (≥ 0) [m].
max_dist (integer) – Max. distance to prism (≤ 400, ≥ min_dist + 10) [m].

Returns request for AUT_PS_SetRange procedure. Creates request for setting the PowerSearch range.

geocom_search(search_hz, search_v)

search_hz (number) – Horizontal search region [rad].
search_v (number) – Vertical search region [rad].

Returns request for AUT_Search procedure. The function performs an automatic target search within the given search area (requires GeoCOM robotic licence). The search is terminated once the prism appears in the field of view of the ATR sensor. If no prism is found in the specified area, the instrument turns back into the initial position. For an exact positioning onto the prism centre, use the fine-adjust API call geocom_fine_adjust() afterwards. If the search range of the API function geocom_fine_adjust() is expanded, target search and fine positioning are done in one step.

geocom_search_target()

Returns request for BAP_SearchTarget procedure. Creates request for searching a target. The function searches for a target in the ATR search window.

geocom_set_angle_correction(incline, stand_axis, collimation, tilt_axis)

incline (bool) – Enable inclination correction.
stand_axis (bool) – Enable standard axis correction.
collimation (bool) – Enable collimation correction.
tilt_axis (bool) – Enable tilt axis correction.

Returns request for TMC_SetAngSwitch procedure. Creates request for turning angle corrections on or off.

geocom_set_atmospheric_correction(lambda, pressure, dry_temp, wet_temp)

lambda (number) – Wave-length of EDM transmitter [m].
pressure (number) – Atmospheric pressure [mbar].
dry_temp (number) – Dry temperature [°C].
wet_temp (number) – Wet temperature [°C].

Returns request for BAP_SetAtmCorr procedure. Creates request for setting the atmospheric correction parameters. The argument lambda should be queried with API call geocom_get_atmospheric_correction().

geocom_set_atmospheric_ppm(atm_ppm)

atm_ppm (number) – Atmospheric ppm correction factor [ppm].

Returns request for BAP_SetAtmPpm procedure. Creates request for setting the atmospheric ppm correction factor.

geocom_set_atr_mode(atr_mode)

atm_mode (integer) – ATR low-vis mode (GEOCOM_BAP_ATRSETTING).

Returns request for BAP_SetATRSetting procedure. Creates request for setting the ATR low-vis mode.

geocom_set_binary_mode(enabled)

enabled (bool) – Enable binary communication.

Returns request for COM_SetBinaryAvailable procedure. Creates request for setting the binary attribute of the server. The function sets the ability of the GeoCOM server to handle binary communication (not supported by DMPACK).

geocom_set_config(auto_power, timeout)

auto_power (integer) – Power-off mode (GEOCOM_SUP_AUTO_POWER).
timeout (integer) – Timeout [msec].

Returns request for SUP_SetConfig procedure. Creates request for setting the power management configuration. The argument timeout sets the duration after which the instrument switches into the mode auto_power when no user activity occured (key press, GeoCOM communication). The value must be between 60,000 m/s (1 min) and 6,000,000 m/s (100 min).

geocom_set_date_time(year, month, day, hour, minute, second)

year (integer) – Year (YYYY).
month (integer) – Month (MM).
day (integer) – Day of month (DD).
hour (integer) – Hour (hh).
minute (integer) – Minute (mm).
second (integer) – Second (ss).

Returns request for CSV_SetDateTime procedure. Creates request for setting the date and time of the instrument.

geocom_set_distance(slope_dist, height_offset, inc_mode)

slope_dist (number) – Slope distance [m].
height_offset (number) – Height offset [m].
inc_mode (integer) – Inclination measurement mode (GEOCOM_TMC_INCLINE_PRG).

Returns request for TMC_SetHandDist procedure. The function is used to set the manually measured slope distance and height offset for a following measurement. Additionally, an inclination and an angle measurement are started to determine the coordinates of the target. The vertical angle is corrected to π/2 or 3π/2, depending on the face of the instrument. The previously measured distance is cleared.

geocom_set_double_precision(ndigits)

ndigits (integer) – Number of digits right to the comma.

Returns request for COM_SetDoublePrecision procedure. The function sets the precision – the number of digits right of the decimal – when double floating-point values are transmitted. The default precision is 15 digits. The setting is only valid for the ASCII transmission mode. Trailing zeroes will not be sent by the instrument. For example, if ndigits is set to 3 and the exact value is 1.99975, the resulting value will be 2.0.

geocom_set_edm_mode(edm_mode)

edm_mode (integer) – EDM measurement mode (GEOCOM_EDM_MODE).

Returns request for TMC_SetEdmMode procedure. Creates request for setting the EDM measurement mode. The EDM mode set by this function is used by geocom_do_measure() in mode GEOCOM_TMC_DEF_DIST.

geocom_set_egl_intensity(intensity)

intensity (integer) – EGL intensity (GEOCOM_EDM_EGLINTENSITY_TYPE).

Returns request for EDM_SetEglIntensity procedure. Creates request for setting the intensity of the electronic guide light.

geocom_set_fine_adjust_mode(adj_mode)

adj_mode (integer) – Fine adjust positioning mode (GEOCOM_AUT_ADJMODE).

Returns request for AUT_SetFineAdjustMode procedure. The function sets the positioning tolerances relating to angle accuracy or point accuracy for the fine adjust (requires GeoCOM robotic licence). If a target is near or held by hand, it is recommended to set the adjust mode to GEOCOM_AUT_POINT_MODE. The argument adj_mode has to be either GEOCOM_AUT_NORM_MODE or GEOCOM_AUT_POINT_MODE.

geocom_set_geometric_ppm(enabled, scale_factor, offset, height_ppm, individual_ppm)

enabled (bool) – Enable geometric ppm calculation.
scale_factor (number) – Scale factor on central meridian.
offset (number) – Offset from central meridian [m].
height_ppm (number) – Ppm value due to height above reference.
individual_ppm (number) – Individual ppm value.

Returns request for TMC_SetGeoPpm procedure. Creates request for setting the geometric ppm correction factor.

geocom_set_height(height)

height (number) – Reflector height [m].

Returns request for TMC_SetHeight procedure. Creates request for setting a new reflector height.

geocom_set_image_config(mem_type, image_number, quality, sub_function, prefix)

mem_type (integer) – Memory device type (GEOCOM_IMG_MEM_TYPE).
image_number (integer) – Actual image number.
quality (integer) – JPEG compression factor (0 – 100).
sub_function (integer) – Additional sub-functions to call.
prefix (string) – File name prefix.

Returns request for IMG_SetTccConfig procedure. Creates request for setting the image configuration. The argument sub_function may be a binary combination of the following settings:

1 – Test image.
2 – Automatic exposure-time selection.
3 – Two-times sub-sampling.
4 – Four-times sub-sampling.

geocom_set_inclination_correction(enabled)

enabled (bool) – Enable dual-axis compensator.

Returns request for TMC_SetInclineSwitch procedure. Creates request for turning the dual-axis compensator on or off.

geocom_set_laser_pointer(enabled)

enabled (bool) – Enable laser pointer.

Returns request for EDM_Laserpointer procedure. Creates request for turning the laser pointer on or off. The function is only available on models which support reflectorless distance measurement.

geocom_set_measurement_program(bap_prog)

bap_prog (integer) – Measurement program (GEOCOM_BAP_USER_MEASPRG).

Returns request for BAP_SetMeasPrg procedure. The function sets the distance measurement program, for example, for API call geocom_measure_distance_angle(). The RL EDM type programs are not available on all instruments. Changing the measurement program may change the EDM type as well (IR, RL).

geocom_set_orientation(hz)

hz (number) – Horizontal orientation [rad].

Returns request for TMC_SetOrientation procedure. Creates request for orientating the instrument in horizontal direction. The API function is a combination of an angle measurement to get the horizontal offset and setting the angle offset afterwards, in order to orientate to a target. Before the new orientation can be set, an existing distance must be cleared by calling API function geocom_do_measure() with argument GEOCOM_TMC_CLEAR.

geocom_set_position(hz, v, pos_mode, atr_mode)

hz (number) – Horizontal angle [rad].
v (number) – Vertical angle [rad].
pos_mode (integer) – Position mode (GEOCOM_AUT_POSMODE).
atr_mode (integer) – ATR mode (GEOCOM_AUT_ATRMODE).

Returns request for AUT_MakePositioning procedure. Creates request for turning the telescope to a specified position.

If pos_mode is GEOCOM_AUT_NORMAL, uses the current value of the compensator. For positioning distances > 25 gon, this mode might tend to inaccuracy. If set to GEOCOM_AUT_PRECISE, tries to measure the exact inclination of the target (tends to long position time).

If atr_mode is GEOCOM_AUT_POSITION, uses conventional position to other face. If set to GEOCOM_AUT_TARGET, tries to position into a target in the destination area. This mode requires activated ATR.

geocom_set_positioning_timeout(time_hz, time_v)

time_hz (number) – Timeout in Hz direction [sec].
time_v (number) – Timeout in V direction [sec].

Returns request for AUT_SetTimeout procedure. This function sets the maximum time to perform a positioning. The timeout is reset on 7 seconds after each power on. Valid value for hz and v are between 7 [sec] and 60 [sec].

geocom_set_prism_constant(prism_const)

prism_const (number) – Prism constant [mm].

Returns request for TMC_SetPrismCorr procedure. Creates request for setting the prism constant. The API function geocom_set_prism_type() overwrites this setting.

geocom_set_prism_type(prism_type)

prism_type (integer) – Prism type (GEOCOM_BAP_PRISMTYPE).

Returns request for BAP_SetPrismType procedure. Creates request for setting the default prism type. This function sets the prism type for measurement with a reflector (GEOCOM_BAP_PRISMTYPE). It overwrites the prism constant set by API call geocom_set_prism_constant().

geocom_set_prism_type_v2(prism_type, prism_name)

prism_type (integer) – Prism type (GEOCOM_BAP_PRISMTYPE).
prism_name (string) – Prism name (required if prism type is GEOCOM_BAP_PRISM_USER).

Returns request for BAP_SetPrismType2 procedure. Creates request for setting the default or user prism type. This function sets the default or the user prism type for measurements with a reflector. It overwrites the prism constant set by geocom_set_prism_constant(). The user defined prism must have been added with API call geocom_set_user_prism_definition() beforehand.

geocom_set_reduced_atr_fov(enabled)

enabled (bool) – Use reduced field of view.

Returns request for BAP_SetRedATRFov procedure. Creates request for setting the reduced ATR field of view. If enabled is true, ATR uses reduced field of view (about 1/9), full field of view otherwise.

geocom_set_refraction_mode(mode)

mode (integer) – Refraction data method (1 or 2).

Returns request for TMC_SetRefractiveMethod procedure. Creates request for setting the refraction model. Mode 1 means method 1 for the rest of the world, mode 2 means method for Australia.

geocom_set_search_area(center_hz, center_v, range_hz, range_v, enabled)

center_hz (number) – Search area center Hz angle [rad].
center_v (number) – Search area center V angle [rad].
range_hz (number) – Search area range Hz angle [rad].
range_v (number) – Search area range V angle [rad].
enabled (bool) – Enable search area.

Returns request for AUT_SetSearchArea procedure. The function sets the position and dimensions of the PowerSearch window, and activates it. The API call is valid for all instruments, but has effects only for those equipped with PowerSearch (requires GeoCOM robotic licence).

geocom_set_station(easting, northing, height, instr_height)

easting (number) – E coordinate [m].
northing (number) – N coordinate [m].
height (number) – H coordinate [m].
instr_height (number) – Instrument height [m].

Returns request for TMC_SetStation procedure. Creates request for setting the station coordinates of the instrument.

geocom_set_target_type(target_type)

target_type (integer) – Target type (GEOCOM_BAP_TARGET_TYPE).

Returns request for BAP_SetTargetType procedure. Creates request for setting the EDM type.

The function sets the current EDM type (GEOCOM_BAP_TARGET_TYPE) for distance measurements: reflector (IR) or reflectorless (RL). For each EDM type, the EDM mode used last is remembered and actived if the EDM type is changed. If EDM type IR is selected, the automation mode used last is activated automatically. The API function geocom_set_measurement_program() can also change the target type. The EDM type RL is not available on all instruments.

geocom_set_tolerance(hz, v)

hz (number) – Positioning tolerance in Hz direction [rad].
v (number) – Positioning tolerance in V direction [rad].

Returns request for AUT_SetTol procedure. Creates request for setting the positioning tolerances.

This function sets the position tolerances of the Hz and V instrument axes (GeoCOM robotic licence required). The tolerances must be in the range of 1 [cc] (1.57079E-06 [rad]) to 100 [cc] (1.57079E-04 [rad]).

The maximum resolution of the angle measurement system depends on the instrument accuracy class. If smaller positioning tolerances are required, the positioning time can increase drastically

geocom_set_user_atr_mode(enabled)

enabled (bool) – Enable ATR state.

Returns request for AUS_SetUserAtrState procedure. Creates request for setting the status of the ATR state.

The function activates or deactivates the ATR mode (requires GeoCOM robotic licence). If enabled is true, ATR mode is activated, and if lock mode is enabled while the API call is made, lock mode will change to ATR mode. If enabled is false, ATR mode is deactivated, and if lock mode is enabled then it stays enabled.

geocom_set_user_lock_mode(enabled)

enabled (bool) – Enable lock state.

Returns request for AUS_SetUserLockState procedure. Creates request for setting the status of the lock state.

The function activated or deactivates the lock mode (GeoCOM robotic licence required). If enabled is true, lock mode is activated. In order to lock and follow a moving target, call API function geocom_lock_in(). If enabled is false, lock mode is deactivated. Tracking of a moving target will be aborted, and the manual drive wheel is activated.

geocom_set_user_prism_definition(prism_name, prism_const, refl_type, creator)

prism_name (string) – Prism name.
prism_const (number) – Prism constant [mm].
refl_type (integer) – Reflector type (GEOCOM_BAP_REFLTYPE).
creator (string) – Name of creator.

Returns request for BAP_SetUserPrismDef procedure. Creates request for setting a user prism definition.

geocom_set_user_spiral(hz, v)

hz (number) – ATR search window in Hz direction [rad].
v (number) – ATR search window in V direction [rad].

Returns request for AUT_SetUserSpiral procedure. The function sets the dimensions of the ATR search window (GeoCOM robotic licence required).

geocom_set_velocity(omega_hz, omega_v)

omega_hz (number) – Velocity in Hz direction [rad/sec].
omega_v (number) – Velocity in V direction [rad/sec].

Returns request for MOT_SetVelocity procedure. Creates request for driving the instrument with constant speed.

The function is used to set up the velocity of the motorisation (GeoCOM robotic licence required). The API function geocom_start_controller() must have been called with argument GEOCOM_MOT_OCONST before.

The velocity in horizontal and vertical direction are in [rad/sec]. The maximum velocity is ±3.14 rad/sec for TM30/TS30, and ±0.79 rad/sec for TPS1100/TPS1200.

geocom_setup_download(device_type, file_type, file_name, block_size)

device_type (integer) – Device type (GEOCOM_FTR_DEVICETYPE).
file_type (integer) – File type (GEOCOM_FTR_FILETYPE).
file_name (string) – File name with extension.
block_size (integer) – Block size.

Returns request for FTR_SetupDownload procedure. Creates request for setting up a file download. The function has to be called before geocom_download(). If the file type is GEOCOM_FTR_FILE_UNKNOWN, an additional file path is required.

The argument device_type must be one of the following:

GEOCOM_FTR_DEVICE_INTERNAL – Internal memory module (path /ata1a/).
GEOCOM_FTR_DEVICE_PCPARD – External memory card (path /ata0a/).

The argument file_type is usually GEOCOM_FTR_FILE_IMAGES. The maximum value for block_size is GEOCOM_FTR_MAX_BLOCKSIZE.

geocom_setup_list(device_type, file_type, search_path)

device_type (integer) – Device type (GEOCOM_FTR_DEVICETYPE).
file_type (integer) – File type (GEOCOM_FTR_FILETYPE).
search_path (string) – Optional search path, required for file type GEOCOM_FTR_FILE_UNKNOWN.

Returns request for FTR_SetupList procedure. Creates request for setting up file listing. The function sets up the device type, file type, and search path. It has to be called before geocom_list().

geocom_start_controller(start_mode)

start_mode (integer) – Controller start mode (GEOCOM_MOT_MODE).

Returns request for MOT_StartController procedure. Creates request for starting the motor controller. If this function is used in combination with API call geocom_set_velocity(), the controller mode has to be GEOCOM_MOT_OCONST.

The argument start_mode must be one of the following:

GEOCOM_MOT_POSIT – Relative positioning.
GEOCOM_MOT_OCONST – Constant speed.
GEOCOM_MOT_MANUPOS – Manual positioning (default setting).
GEOCOM_MOT_LOCK – “Lock-in” controller.
GEOCOM_MOT_BREAK – “Brake” controller.
GEOCOM_MOT_TERM – Terminates the controller task.

geocom_stop_controller(stop_mode)

stop_mode (integer) – Controller stop mode (GEOCOM_MOT_STOPMODE).

Returns request for MOT_StartController procedure. Creates request for stopping the motor controller.

The argument stop_mode must be one of the following:

GEOCOM_MOT_NORMAL – Slow down with current acceleration.
GEOCOM_MOT_SHUTDOWN – Slow down by switching off power supply.

geocom_switch_off(stop_mode)

stop_mode (integer) – Switch-off mode (GEOCOM_COM_TPS_STOP_MODE).

Returns request for COM_SwitchOffTPS procedure. Creates request for turning the instrument off.

The argument stop_mode has to be one of the following:

GEOCOM_COM_TPS_STOP_SHUT_DOWN – Power down instrument.
GEOCOM_COM_TPS_STOP_SLEEP – Sleep mode (not supported by TPS1200).

geocom_switch_on(start_mode)

start_mode (integer) – Switch-on mode (GEOCOM_COM_TPS_STARTUP_MODE).

Returns request for COM_SwitchOnTPS procedure. Creates request for turning the instrument on.

The argument start_mode has to be one of the following:

GEOCOM_COM_TPS_STARTUP_LOCAL – Not supported by TPS1200.
GEOCOM_COM_TPS_STARTUP_REMOTE – Online mode (RPC is enabled).

geocom_take_image(mem_type)

mem_type (integer) – Memory type (GEOCOM_IMG_MEM_TYPE).

Returns request for IMG_TakeTccImage procedure. Creates request for capturing a telescope image.

The memory type mem_type has to be one of the following:

GEOCOM_IMG_INTERNAL_MEMORY – Internal memory module.
GEOCOM_IMG_PC_CARD – External memory card.