International Light Technologies ILT1000 Api Manual

Hide thumbs Also See for ILT1000:

Operation manual (9 pages)

Application notes (19 pages)

page of 50

/ 50
Bookmarks

Quick Links

Download this manual See also: Operating Manual

Revision Table

May 8 2015

v1.5

May 15 2015

v1.6

June 30 2015

v1.7

August 11 2015

v1.8

August 21 2015

v1.9

ILT1000, ILT5000 API Documenta on

Ini al Release under this form, capturing ﬁrmware revisions up to and including 3.0.5.8

Added setwireless command

Updated ge*lash to add return value of -513 when asking for a minimum light level

•

that could not be measured in the given range (Rf + voltage sensi vity) due to

satura on below the minimum light level

added setsample metemp func onality to change sample me without saving to ﬂash

•

added usecalfactortemp func onality to change sample me without saving to ﬂash

•

added usefeedbackrestemp func onality to change sample me without saving to ﬂash

•

ﬁxed typo where getambientlevel API was listed as setambientlevel

•

moved setwﬂisten API to OEM commands

•

Added startpeak, stoppeak, getpeak, star ntegrate, stopintegrate, ge ntegrate

•

Added conﬁgbackup, conﬁgrestore to OEM commands

•

Page 1

Need help?

Do you have a question about the ILT1000 and is the answer not in the manual?

Questions and answers

Summary of Contents for International Light Technologies ILT1000

Page 1 ILT1000, ILT5000 API Documenta on Revision Table May 8 2015 v1.5 Ini al Release under this form, capturing ﬁrmware revisions up to and including 3.0.5.8 May 15 2015 v1.6 Added setwireless command June 30 2015 v1.7 Updated ge*lash to add return value of -513 when asking for a minimum light level •...
Page 2 ILT1000, ILT5000 API Documenta on The ILTx000 device uses a simple text-based API for communica on with user applica ons, as well as for use with a basic terminal server. Document Conven on The API table below contains two columns. In the ﬁrst column is the API/command name. In the second column is the API/command’s deﬁni on.
Page 3 o A programmable GPIO pin with current boost, used to control a detector bias voltage (see set0vbias, set5vbias, and getbias) o A programmable digital trigger output (see seGriggerout) o A digital trigger input (see geGriggerin) Theory of Opera on Below is the Theory of Opera on for interfacing with the device using the API deﬁned further below. The device responds to a number of commands (together known as the command-line API) delivered via the USB port.
Page 4 Regarding me-outs for command responses, “get” commands will typically respond within 100ms. “set” commands that store their conﬁgura on in ﬂash memory can take up to 5 seconds to respond. Other special commands like “se*actorydark”, “setuserdark”, and “captureﬂash” can take longer to respond. Be careful not to expect an immediate response from the device.
Page 5 captureflash Syntax: capture flash [trigger type] [trigger level] [minimum light Support Star ng in Firmware level] [timeout period] [voltage sensitivity] [trigger offset Version: 3.0.5.8 time] [integration time] [save to flash] [save only above minimum light level] Support Ending in Firmware What it does: Version: N/A This command enters a mode where only values are sent back in response to a command.
Page 6 captureflash Error return value(s): -500 if missing ﬁelds (Con nued) -501 if bad trigger type. Must be 0-3. -502 if bad trigger level. Must be “low” or “high” -503 if bad minimum light level. Must be greater than 0. -504 if bad meout period. Must be 0-300. -505 if bad voltage sensi vity.
Page 7 echooff Syntax: echooff Support Star ng in Firmware Version: 2.0.0.3 What it does: This command enters a mode where only values are sent back in response to a command. Support Ending in Firmware This is the default mode on power up of the device, and the mode used for programming Version: N/A by an applica on.
Page 8 erasecalfactor Syntax: erasecalfactor [calibra on number, 1-20] Support Star ng in Firmware Version: 2.0.0.3 What it does: This command erases the calibra on data associated with the calibra on factor. This Support Ending in Firmware includes the calibra on factor descrip on, the current-to-irradiance mul plier, and the Version: N/A satura on current.
Page 9 eraselogdata Syntax: eraselogdata Support Star ng in Firmware Version: 2.0.0.3 What it does: This command erases any log data that has been stored in the device’s ﬂash memory. See Support Ending in Firmware also startlogdata and stoplogdata. Version: N/A Normal return value(s): 0 on success Error return value(s): -500 if logging is currently ac ve (must use stoplogdata ﬁrst)
Page 10 getambienttemp Syntax: (Gen2, Gen3) getambienttemp Support Star ng in Firmware What it does: Version: 2.0.0.3 This command returns the ambient temperature as sensed by the device. This diﬀers from gettemp which returns the internal temperature of the microcontroller. Support Ending in Firmware Version: N/A Normal return value(s): Temperature in degrees F (x100 for ﬁrmware <...
Page 11 getauxserialno Syntax: getauxserialno Support Star ng in Firmware Version: 2.0.0.3 What it does: This command returns the auxiliary serial number of the device. The serial number is Support Ending in Firmware stored in one- me-programmable memory at the me of manufacture. Version: N/A Normal return value(s): Device serial number...
Page 12 getcalfactor Syntax: getcalfactor [op onal, calibra on factor, 1-20] Support Star ng in Firmware Version: 2.0.0.3 What it does: Without the op onal parameter, this command returns the calibra on factor currently in Support Ending in Firmware use. With the op onal parameter, this command returns the calibra on factor details for Version: N/A a par cular calibra on factor.
Page 13 getdarkmode Syntax: getdarkmode Support Star ng in Firmware Version: 2.0.0.3 What it does: This command returns the dark mode currently in use by the device. The dark mode can Support Ending in Firmware be NO DARK (there is no considera on for photodiode dark current), FACTORY DARK (the Version: N/A dark current set at the factory), or USER DARK (the dark current set with setuserdark).
Page 14 getecaldate Syntax: (Gen3) getecaldate Support Star ng in Firmware What it does: Version: 3.0.5.3 This command returns the sensor last date electrical cal (ecal) was performed, in epoch me. If an ecal as never performed, this api returns 0. Support Ending in Firmware Version: N/A Normal return value(s): 0 if ecal was never performed...
Page 15 getflash Syntax: getflash Support Star ng in Firmware Version: 3.0.5.8 What it does: This command returns the results of the captureﬂash command, including the following Support Ending in Firmware data: Version: N/A Peak: This is the peak light level sensed during the ﬂash capture Average: This is the average light level sensed over the integra on period Integra on: This is the integra on of the light level over the integra on period Time Above 10 Percent of Peak: This is the me (in seconds) that the signal was above...
Page 16 getfriendlyname Syntax: getfriendlyname Support Star ng in Firmware Version: 3.0.5.4 What it does: This command returns the device’s “friendly name”. Support Ending in Firmware Version: N/A Normal return value(s): Device friendly name or “NOT-DEFINED” if the friendly name has not yet been saved Error return value(s): getfwversion Syntax:...
Page 17 See command output for the par cular ﬁrmware version. Error return value(s): Example return: Base Serial Number = 10002201407300019 Vendor Serial Number = ILT100000002 Model Name = ILT1000-V02 Friendly Name = Right Generation = 2 FW Version = 3.0.5.8 Dark mode (0=No,1=Factory,2=User) = 1...
Page 18 getintegrate Syntax: getintegrate Support Star ng in Firmware Version: 3.0.7.0 What it does: This command returns the integrated light level that started with startintegrate. Support Ending in Firmware The integral is calculated as the average light level since the beginning of Version: N/A startintegrate, mul plied by the me in seconds (resolu on of 10ms).
Page 19 getirrthresholdlow Syntax: getirrthresholdlow Support Star ng in Firmware Version: 2.0.1.0 What it does: This command returns the irradiance value (or light level), below which data will not be Support Ending in Firmware logged. It is set with setirrthresholdlow. Version: N/A Normal return value(s): Minimum irradiance value for data logging, returned in scien ﬁc nota on.
Page 20 getlogdata Syntax: getlogdata Support Star ng in Firmware Version: 2.0.0.3 What it does: This command returns the log data stored in ﬂash memory. This command can be run Support Ending in Firmware during an ac ve logging session (and datalogging will con nue) or aOer a session is Version: N/A stopped with stoplogdata or, star ng in version 3.0.5.8, aOer captureflash is used with the op on to save data to ﬂash.
Page 21 getmodelname Syntax: getmodelname Support Star ng in Firmware Version: 2.0.0.3 What it does: This command returns the model name of the device. Support Ending in Firmware Version: N/A Normal return value(s): Device model name Error return value(s): getod Syntax: getod Support Star ng in Firmware Version: 2.0.0.3 What it does:...
Page 22 getsampletime Syntax: getsampletime Support Star ng in Firmware Version: 3.0.5.4 What it does: This command returns the sample me in milliseconds (see setsampletime). Note Support Ending in Firmware that if the sample me is set for automa c (setsampletime 0) this command will Version: N/A return the actual sample in me currently in use.
Page 23 gettrans Syntax: gettrans Support Star ng in Firmware Version: 2.0.0.3 What it does: This command returns the percent transmission, mul plied by 10. Because percent Support Ending in Firmware transmission is a rela ve measurement, this command requires that the 100% (0.00 OD) Version: N/A seJng is established with set100perc.
Page 24 getuserdark Syntax: getuserdark Support Star ng in Firmware Version: 2.0.0.3 What it does: This command returns the dark voltage at the various transimpedance ampliﬁer gain Support Ending in Firmware stages, as set by the user with setuserdark. Version: N/A Normal return value(s): On Gen1 products: The dark voltage in microvolts, of the two voltage gain stages.
Page 25 getvoltage Syntax: getvoltage Support Star ng in Firmware Version: 2.0.0.3 Shortcut: gv (support for this shortcut star ng in 3.0.5.4) Support Ending in Firmware Version: N/A What it does: This command returns the voltage output of the transimpedance ampliﬁer, aOer it is passed through the automa c-gain-control circuit.
Page 26 getvref Syntax: getvref Support Star ng in Firmware Version: 2.0.0.3 What it does: This command returns the reference voltage for the device’s A/D converter. This Support Ending in Firmware command can be used as a diagnos c if there is ever a suspicion that the voltage Version: N/A reference is faulty.
Page 27 help Syntax: help Support Star ng in Firmware Version: 2.0.0.3 What it does: This command list the most common commands, along with their expected return value. Support Ending in Firmware Version: N/A Normal return value(s): List of common commands and return values. Error return value(s): set0vbias Syntax:...
Page 28 set100perc Syntax: set100perc Support Star ng in Firmware Version: 2.0.0.3 What it does: Prior to 3.0.5.3, this command read the detectors voltage level (and by inference its Support Ending in Firmware current and irradiance level) and sets this as the 100% value to use in Op cal Density and Version: N/A %Transmission calcula ons.
Page 29 setambientlevel Syntax: setambientlevel Support Star ng in Firmware Version: 3.0.5.8 What it does: This command sets the exis ng current and light-level reading as zero, eﬀec vely Support Ending in Firmware elimina ng ambient light/power levels from subsequent readings. Version: N/A Normal return value(s): 0 on success Error return value(s):...
Page 30 setcalfactor Setcalfactor [calibration factor, 1-20] [desc.] [sensitivity Support Star ng in Firmware factor] [saturation current uA] What it does: Version: 2.0.0.3 This command deﬁnes the par cular calibra on factor details. Details include the Support Ending in Firmware calibra on factor descrip on (up to 100 characters), the sensi vity factor (Light Level = Version: N/A Detector Current / Sensi vity Factor), and satura on current in microamps.
Page 31 setcurrentloop Syntax: (Gen2, Gen3) setcurrentloop log setcurrentloop midpoint Support Star ng in Firmware setcurrentloop [min picoamps] [max picoamps] Version: 2.0.0.5 setcurrentloop [0-24] What it does: Support Ending in Firmware This command controls the 4-20mA current loop output of devices that support such a Version: N/A current loop.
Page 32 setdatetime Syntax: (Gen2, Gen3) setdatetime 12/05/2013 19:02:05 Support Star ng in Firmware What it does: Version: 2.0.0.3 This command sets the real me clock’s date and me. It accepts either of the following formats: Support Ending in Firmware mm/dd/yyyy hh:mm:ss Version: N/A mm/dd/yy hh:mm:ss The device is designed such that this date/ me seJng is UTC/GMT me.
Page 33 sethiaveraging Syntax: sethiaveraging Support Star ng in Firmware Version: 2.0.0.3 What it does: This command sets the averaging to be performed by the device to high, resul ng in Support Ending in Firmware approximately 1 sample every 2 seconds. This mode provides the highest amount of over- Version: N/A sampling, or noise reduc on.
Page 34 setirrthresholdlow Syntax: setirrthresholdlow [calibrated reading] Support Star ng in Firmware Version: 2.0.1.0 What it does: This command sets the minimum irradiance value (calibrated reading) to use in Support Ending in Firmware conjunc on with data logging. When set, and irradiance is being monitored with data Version: N/A logging, data will not be recorded unless the irradiance level meets this threshold.
Page 35 setsamplecount Syntax: setsamplecount [1 – 200] Support Star ng in Firmware Version: 2.0.0.6 What it does: This command sets the number of samples taken by the Analog-to-Digital converter when Support Ending in Firmware reading the voltage from the transimpedance ampliﬁer. This is the immiedate averaging Version: 3.0.5.3 done on the input signal, before addi onal averaging is done by the set*averaging commands.
Page 36 setsampletime Syntax: setsampletime 0 Support Star ng in Firmware Version: 3.0.5.4 setsampletime [10 - 15000] Support Ending in Firmware What it does: Version: N/A This command sets the sample me used by the Analog-to-Digital converter when reading the voltage from the transimpedance ampliﬁer in milliseconds. setsampletime 0 sets the sample me to automa c, resul ng in 500ms for high level signals and up to 2 seconds for lower signals.
Page 37 setsimpleirrcal Syntax: setsimpleirrcal [current-to-irradiance mul plier, x 1,000,000] Support Star ng in Firmware Version: 2.0.0.3 What it does: This command sets a simple mul plier to be used to convert detector current to Support Ending in Firmware irradiance. In the absence of factory-deﬁned calibra on factors, it is the easiest method to Version: 3.0.5.3 establish a user-deﬁned irradiance value from detector current.
Page 38 setuserdark Syntax: setuserdark Support Star ng in Firmware Version: 2.0.0.3 What it does: This command captures the detector voltage signal, at all automa c-gain-control stages, Support Ending in Firmware and stores the values in device ﬂash memory. When used in conjunc on with Version: N/A useuserdark, all subsequent readings will have this value removed automa cally.
Page 39 startintegrate Syntax: startintegrate Support Star ng in Firmware Version: 3.0.7.0 What it does: This command starts integra ng the light level at high-speed to capture fast pulses. The Support Ending in Firmware integrated light-level is returned with getintegrate and the integra on is halted with Version: N/A stopintegrate.
Page 40 startlogdata Syntax: startlogdata [variable bitmask] [logging period – see below] [seconds since 1970] Support Star ng in Firmware Version: 2.0.0.3 What it does: This command deﬁnes the logging parameters, and immediately starts logging. This Support Ending in Firmware command cannot be run when either a logging session is already ac ve, a session has Version: N/A been stopped (with stoplogdata) but the log data has not yet been erased with eraselogdata,or a captureﬂash session has completed with saved data that has not...
Page 41 startlogdata (cont) Error return value(s): -500 missing parameters -501 session already started. Must use stoplogdata and eraselogdata to start new. -502 errors with the variable bit mask Persist through power-cycle: Yes. Common usage is to use startlogdata, disconnect the device from the computer, connect the device to a baGery or AC-power in the lab or ﬁeld, and the device will con nue logging on power up using me-stamps that are rela ve to the start me.
Page 42 stoplogdata Syntax: stoplogdata Support Star ng in Firmware Version: 2.0.0.3 What it does: This command stops a log session that was started with startlogdata. Note that, Support Ending in Firmware because date- me-stamping is rela ve to the start me set with startlogdata, Version: N/A logging cannot be restarted aOer a stoplogdata.
Page 43 usecalfactor Syntax: usecalfactor [calibra on number, 0-20] Support Star ng in Firmware Version: 2.0.0.3 What it does: This command selects a par cular calibra on factor (see setcalfactor), which in turn Support Ending in Firmware will deﬁne the detector current-to-irradiance mul plier as well as the detector satura on Version: N/A current.
Page 44 usefeedbackres Syntax: (Gen2, Gen3) usefeedbackres [resistor selection 0-4] usefeedbackres Support Star ng in Firmware Version: 2.0.0.3 What it does: For Gen2 devices, which have 3 available feedback resistors, this command selects the Support Ending in Firmware resistor to be used as follows: Version: N/A 0: have the device automa cally select a resistor based on light-level 1: use feedback resistor #1, usually the lowest value resistor...
Page 45 usenodark Syntax: usenodark Support Star ng in Firmware Version: 2.0.0.3 What it does: This command will eliminate any dark current considera on. Support Ending in Firmware Version: N/A Normal return value(s): 0 on success Error return value(s): Persist through power-cycle: useuserdark Syntax: useuserdark...
Page 46 OEM Only configbackup Syntax: configbackup Support Star ng in Firmware Version: 3.0.6.8 What it does: This command saves a copy of the device conﬁgura on (stored in Sector G) to another Support Ending in Firmware area of the device (Sector B). In the even that Sector G becomes corrupted or Version: N/A misconﬁgured, the factory seJngs can be restored from Sector B with configrestore.
Page 47 setauxserialno Syntax: setauxserialno [up to 30 non-space characters] Support Star ng in Firmware Version: 2.0.0.3 What it does: This command is used by the OEM to set their own serial number. This number is wriGen Support Ending in Firmware into write-once memory on the device, so EXTREME care must be taken to set this Version: N/A properly.
Page 48 setfactorydark Syntax: setfactorydark Support Star ng in Firmware Version: 2.0.0.3 What it does: This command is used by the manufacturer. It captures the detector signal, at all Support Ending in Firmware automa c-gain-control stages, and stores the values in device ﬂash memory. When used Version: N/A in conjunc on with usefactorydark, the default dark mode, all subsequent readings will have this value removed automa cally.
Page 49 setfeedbackres Syntax (Gen1 devices): setfeedbackres [feedback resistor value, i.e. Rf, in kOhms x 10] Support Star ng in Firmware Syntax (Gen2 devices): Version: 2.0.0.3 setfeedbackres [Resistor 1 kOhms x 10] [Resistor 2 kOhms x 10] [Resistor 3 kOhms x Support Ending in Firmware Version: N/A Syntax (Gen3 devices): setfeedbackres [Resistor 1 kOhms x 10] [Resistor 2 kOhms x 10] [Resistor 3 kOhms x...
Page 50 setwflisten setwflisten on Support Star ng in Firmware setwflisten off Version: 3.0.5.3 setwflisten tempon setwflisten tempoff Support Ending in Firmware Version: N/A What it does: This command disables any listening for commands on the secondary serial port. This is the port that the wireless (WiFly) part uses, but may be used by other devices in the future, including 3 -party connec on to the device.

This manual is also suitable for:

Ilt5000