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:

-- Prototype observation of target 99.
observ = {
  target_id = "target-99",
  receiver = "dmdb"
}

-- Initialisation of robotic total station.
job1 = {
  onetime = true,
  delay = 5 * 1000,
  group = {
    geocom_beep_normal(observ),
    geocom_set_refraction_mode(observ, 1),
    geocom_set_inclination_correction(observ, true),
    geocom_set_user_atr_mode(observ, true),
    geocom_set_target_type(observ, GEOCOM_BAP_REFL_USE),
    geocom_set_prism_type(observ, GEOCOM_BAP_PRISM_ROUND)
  }
}

-- Prototype observation of target 1.
observ = {
  target_id = "target-01",
  receiver = "dmdb"
}

-- Single measurement of target every 10 seconds.
job2 = {
  onetime = false,
  delay = 10 * 1000,
  group = {
    geocom_set_position(observ, gon2rad(0.0), gon2rad(100.0), GEOCOM_AUT_NORMAL, GEOCOM_AUT_TARGET),
    geocom_do_measure(observ, GEOCOM_TMC_DEF_DIST, GEOCOM_TMC_AUTO_INC),
    geocom_get_simple_measurement(observ, 3000, GEOCOM_TMC_AUTO_INC)
  }
}

The targets target-01 and target-99 have to exist in the observation database. The performed observations are forwarded to dmdb. To send the observations using dmserial, add the jobs table to the configuration table, for example:

-- dmserial.conf
dmserial = {
  node = "dummy-node",   -- Sensor node id (required).
  sensor = "sensor-rts", -- Sensor id (required).
  path = "/dev/ttyUSB0", -- TTY device path.
  baudrate = 115200,     -- TTY baud rate.
  bytesize = 8,          -- TTY byte size (5, 6, 7, 8).
  parity = "none",       -- TTY parity (`none`, `even`, `odd`).
  stopbits = 1,          -- TTY stop bits (1, 2).
  timeout = 5,           -- TTY timeout in seconds (max. 25).
  jobs = { job1, job2 }  -- Jobs to perform.
}

Parameters

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.

The first argument of the Lua functions shall be a prototype observation or an empty table. The prototype may pre-set the target id or the receiver.

geocom_abort_download(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_abort_list(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_beep_alarm(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_beep_normal(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_beep_off(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_beep_on(observ, intensity)

• observ (table) – Prototype observation or empty table.

• intensity (integer) – Intensity of the beep signal.

Returns observation 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(observ, pos_mode, atr_mode)

• observ (table) – Prototype observation or empty table.

• pos_mode (integer) – Position mode (GEOCOM_AUT_POSMODE).

• atr_mode (integer) – ATR mode (GEOCOM_AUT_ATRMODE).

Returns observation 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(observ, device_type, file_type, day, month, year, file_name)

• observ (table) – Prototype observation or empty table.

• 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 observation 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(observ, tmc_prog, inc_mode)

• observ (table) – Prototype observation or empty table.

• tmc_prog (integer) – Measurement program (GEOCOM_TMC_MEASURE_PRG).

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

Returns observation 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(observ, block_number)

• observ (table) – Prototype observation or empty table.

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

Returns observation 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(observ, search_hz, search_v)

• observ (table) – Prototype observation or empty table.

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

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

Returns observation 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(observ, inc_mode)

• observ (table) – Prototype observation or empty table.

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

Returns observation 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(observ, inc_mode)

• observ (table) – Prototype observation or empty table.

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

Returns observation 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(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_atmospheric_correction(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_atmospheric_ppm(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_atr_error(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_atr_setting(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_binary_mode(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_config(observ)

• observ (table) – Prototype observation or empty table.

Returns observation 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(observ, wait_time, inc_mode)

• observ (table) – Prototype observation or empty table.

• wait_time (integer) – Delay to wait for the distance measurement to finish [msec].

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

Returns observation 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(observ)

• observ (table) – Prototype observation or empty table.

Returns observation 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(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_device_config(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_double_precision(observ)

• observ (table) – Prototype observation or empty table.

Returns observation 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(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_egl_intensity(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_face(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_fine_adjust_mode(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_full_measurement(observ, wait_time, inc_mode)

• observ (table) – Prototype observation or empty table.

• wait_time (integer) – Delay to wait for the distance measurement to finish [msec].

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

Returns observation 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(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_geometric_ppm(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_height(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_image_config(observ, mem_type)

• observ (table) – Prototype observation or empty table.

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

Returns observation 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(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_inclination_error(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_instrument_name(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_instrument_number(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_internal_temperature(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_lock_status(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_measurement_program(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_power(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_prism_constant(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_prism_definition(observ, prism_type)

• observ (table) – Prototype observation or empty table.

• prism_type (integer) – Prism type (GEOCOM_BAP_PRISMTYPE).

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

geocom_get_prism_type(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_prism_type_v2(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_quick_distance(observ)

• observ (table) – Prototype observation or empty table.

Returns observation 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(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_reflectorless_class(observ)

• observ (table) – Prototype observation or empty table.

Returns observation 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(observ)

• observ (table) – Prototype observation or empty table.

Returns observation 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(observ)

• observ (table) – Prototype observation or empty table.

Returns observation 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(observ)

• observ (table) – Prototype observation or empty table.

Returns observation 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(observ, wait_time, inc_mode)

• observ (table) – Prototype observation or empty table.

• wait_time (integer) – Delay to wait for the distance measurement to finish [msec].

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

Returns observation 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(observ, wait_time, inc_mode)

• observ (table) – Prototype observation or empty table.

• wait_time (integer) – Delay to wait for the distance measurement to finish [msec].

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

Returns observation 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(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_software_version(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_station(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_target_type(observ)

• observ (table) – Prototype observation or empty table.

Returns observation 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(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_tolerance(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_user_atr_mode(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_user_lock_mode(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_get_user_prism_definition(observ, name)

• observ (table) – Prototype observation or empty table.

• name (string) – Prism name.

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

geocom_get_user_spiral(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_list(observ, next)

• observ (table) – Prototype observation or empty table.

• next (bool) – First or next entry.

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

geocom_lock_in(observ)

• observ (table) – Prototype observation or empty table.

Returns observation 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(observ, dist_mode)

• observ (table) – Prototype observation or empty table.

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

Returns observation 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(observ)

• observ (table) – Prototype observation or empty table.

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

geocom_ps_enable_range(observ, enabled)

• observ (table) – Prototype observation or empty table.

• enabled (bool) – Enable PowerSearch.

Returns observation 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(observ, direction, swing)

• observ (table) – Prototype observation or empty table.

• direction (integer) – Searching direction (GEOCOM_AUT_CLOCKWISE or GEOCOM_AUT_ANTICLOCKWISE).

• swing (bool) – Searching starts –10 gon to the given direction.

Returns observation 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(observ)

• observ (table) – Prototype observation or empty table.

Returns observation 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() (observ, requires GeoCOM robotic licence).

geocom_ps_set_range(observ, min_dist, max_dist)

• observ (table) – Prototype observation or empty table.

• min_dist (integer) – Min. distance to prism (≥ 0) [m].

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

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

geocom_search(observ, search_hz, search_v)

• observ (table) – Prototype observation or empty table.

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

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

Returns observation 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(observ)

• observ (table) – Prototype observation or empty table.

Returns observation 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(observ, incline, stand_axis, collimation, tilt_axis)

• observ (table) – Prototype observation or empty table.

• 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 observation for TMC_SetAngSwitch procedure. Creates request for turning angle corrections on or off.

geocom_set_atmospheric_correction(observ, lambda, pressure, dry_temp, wet_temp)

• observ (table) – Prototype observation or empty table.

• 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 observation 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(observ, atm_ppm)

• observ (table) – Prototype observation or empty table.

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

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

geocom_set_atr_mode(observ, atr_mode)

• observ (table) – Prototype observation or empty table.

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

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

geocom_set_binary_mode(observ, enabled)

• observ (table) – Prototype observation or empty table.

• enabled (bool) – Enable binary communication.

Returns observation 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(observ, auto_power, timeout)

• observ (table) – Prototype observation or empty table.

• auto_power (integer) – Power-off mode (GEOCOM_SUP_AUTO_POWER).

• timeout (integer) – Timeout [msec].

Returns observation 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(observ, year, month, day, hour, minute, second)

• observ (table) – Prototype observation or empty table.

• 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 observation for CSV_SetDateTime procedure. Creates request for setting the date and time of the instrument.

geocom_set_distance(observ, slope_dist, height_offset, inc_mode)

• observ (table) – Prototype observation or empty table.

• slope_dist (number) – Slope distance [m].

• height_offset (number) – Height offset [m].

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

Returns observation 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(observ, ndigits)

• observ (table) – Prototype observation or empty table.

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

Returns observation 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(observ, edm_mode)

• observ (table) – Prototype observation or empty table.

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

Returns observation 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(observ, intensity)

• observ (table) – Prototype observation or empty table.

• intensity (integer) – EGL intensity (GEOCOM_EDM_EGLINTENSITY_TYPE).

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

geocom_set_fine_adjust_mode(observ, adj_mode)

• observ (table) – Prototype observation or empty table.

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

Returns observation 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(observ, enabled, scale_factor, offset, height_ppm, individual_ppm)

• observ (table) – Prototype observation or empty table.

• 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 observation for TMC_SetGeoPpm procedure. Creates request for setting the geometric ppm correction factor.

geocom_set_height(observ, height)

• observ (table) – Prototype observation or empty table.

• height (number) – Reflector height [m].

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

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

• observ (table) – Prototype observation or empty table.

• 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 observation 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(observ, enabled)

• observ (table) – Prototype observation or empty table.

• enabled (bool) – Enable dual-axis compensator.

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

geocom_set_laser_pointer(observ, enabled)

• observ (table) – Prototype observation or empty table.

• enabled (bool) – Enable laser pointer.

Returns observation 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(observ, bap_prog)

• observ (table) – Prototype observation or empty table.

• bap_prog (integer) – Measurement program (GEOCOM_BAP_USER_MEASPRG).

Returns observation 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(observ, hz)

• observ (table) – Prototype observation or empty table.

• hz (number) – Horizontal orientation [rad].

Returns observation 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(observ, hz, v, pos_mode, atr_mode)

• observ (table) – Prototype observation or empty table.

• 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 observation 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(observ, time_hz, time_v)

• observ (table) – Prototype observation or empty table.

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

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

Returns observation 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(observ, prism_const)

• observ (table) – Prototype observation or empty table.

• prism_const (number) – Prism constant [mm].

Returns observation 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(observ, prism_type)

• observ (table) – Prototype observation or empty table.

• prism_type (integer) – Prism type (GEOCOM_BAP_PRISMTYPE).

Returns observation 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(observ, prism_type, prism_name)

• observ (table) – Prototype observation or empty table.

• prism_type (integer) – Prism type (GEOCOM_BAP_PRISMTYPE).

• prism_name (string) – Prism name (required if prism type is GEOCOM_BAP_PRISM_USER).

Returns observation 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(observ, enabled)

• observ (table) – Prototype observation or empty table.

• enabled (bool) – Use reduced field of view.

Returns observation 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(observ, mode)

• observ (table) – Prototype observation or empty table.

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

Returns observation 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(observ, center_hz, center_v, range_hz, range_v, enabled)

• observ (table) – Prototype observation or empty table.

• 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 observation 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(observ, easting, northing, height, instr_height)

• observ (table) – Prototype observation or empty table.

• easting (number) – E coordinate [m].

• northing (number) – N coordinate [m].

• height (number) – H coordinate [m].

• instr_height (number) – Instrument height [m].

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

geocom_set_target_type(observ, target_type)

• observ (table) – Prototype observation or empty table.

• target_type (integer) – Target type (GEOCOM_BAP_TARGET_TYPE).

Returns observation 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(observ, hz, v)

• observ (table) – Prototype observation or empty table.

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

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

Returns observation 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(observ, enabled)

• observ (table) – Prototype observation or empty table.

• enabled (bool) – Enable ATR state.

Returns observation 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(observ, enabled)

• observ (table) – Prototype observation or empty table.

• enabled (bool) – Enable lock state.

Returns observation 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(observ, prism_name, prism_const, refl_type, creator)

• observ (table) – Prototype observation or empty table.

• 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 observation for BAP_SetUserPrismDef procedure. Creates request for setting a user prism definition.

geocom_set_user_spiral(observ, hz, v)

• observ (table) – Prototype observation or empty table.

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

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

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

geocom_set_velocity(observ, omega_hz, omega_v)

• observ (table) – Prototype observation or empty table.

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

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

Returns observation 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(observ, device_type, file_type, file_name, block_size)

• observ (table) – Prototype observation or empty table.

• 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 observation 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(observ, device_type, file_type, search_path)

• observ (table) – Prototype observation or empty table.

• 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 observation 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(observ, start_mode)

• observ (table) – Prototype observation or empty table.

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

Returns observation 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(observ, stop_mode)

• observ (table) – Prototype observation or empty table.

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

Returns observation 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(observ, stop_mode)

• observ (table) – Prototype observation or empty table.

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

Returns observation 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(observ, start_mode)

• observ (table) – Prototype observation or empty table.

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

Returns observation 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(observ, mem_type)

• observ (table) – Prototype observation or empty table.

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

Returns observation 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.