dps_requests.txt - (c) 2005 - 2010 Uwe Disch - http://www.disch-systems.de Usage information for dps_requests: dps_requests is a command line application to be run from PHP, Perl, Python, Ruby, Shell or any other server or client side script. dps_requests has the ability to connect to a, local or remote, EIB Driver for Linux and it's components via intranet rsp. internet. If you invoke dps_reqests from the command line with the "-h" argument the output of dps_requests is like this: my-linux:~# ./dps_requests -h dps_requests for Linux: Version 1.03.0016 (c) 2000 - 2010 Uwe Disch. All rights reserved. Free supplement to the EIB Driver for Linux. Compiled with: Linux Kernel: 2.6.8-4-686 i686 GNU/Linux / glibc: 2.3.2 DPS-API: 1.03.0015 / NS-API: 1.03.0015 dps_requests is currently using: NPTL 0.60 / glibc 2.3.2 Short usage information: dps_requests ( RNB | RBU ) ip_addr num_elems [ ( GAn EISn ) ... ] dps_requests LIS ip_addr num_elems [ ( GAn EISn ) ... ] command sleep dps_requests LIF ip_addr num_elems [ ( GAn EISn ) ... ] file sleep *) dps_requests ( MON | MNA ) ip_addr sleep **) dps_requests WRI ip_addr num_elems [ ( GAn EISn Valn ) ... ] dps_requests ( RSN | RPM | CMD ) ip_addr dps_requests WPM ip_addr ( 0 | 1 ) dps_requests ( -h | --help | -v | --version ) *) LIF is experimental, please use with caution! **) MON rsp. MNA needs some seconds to start up and some seconds to shut down. For complete usage information see: http://disch-systems.de/download/dps_requests.txt my-linux:~# Please be reminded that the Windows version only supports a subset of the functions of the Linux version: C:\>dps_requests.exe -h dps_requests for Windows: Version 1.03.0016 (c) 2000 - 2010 Uwe Disch. All rights reserved. Free supplement to the DISCH Gateway IP and to the EIB Driver for Linux. Compiled with: DPS-API: 1.03.0015 Short usage information: dps_requests ( RNB | RBU ) ip_addr num_elems [ ( GAn EISn ) ... ] dps_requests LIS ip_addr num_elems [ ( GAn EISn ) ... ] command sleep dps_requests LIF ip_addr num_elems [ ( GAn EISn ) ... ] file sleep *) dps_requests WRI ip_addr num_elems [ ( GAn EISn Valn ) ... ] dps_requests ( RPM | CMD ) ip_addr dps_requests WPM ip_addr ( 0 | 1 ) dps_requests ( -h | --help | -v | --version ) *) LIF is experimental, please use with caution! For complete usage information see: http://disch-systems.de/download/dps_requests.txt C:\> Installation of dps_requests: Within Linux copy the file dps_requests to a directory of your choice. dps_requests for Windows uses the pthreadGC1.dll pthread library. You will find the already compiled pthread library pthreadGC1.dll within the executable archive pthreads-2005-01-25.exe at these locations either: http://public.planetmirror.com/pub/sourceware/pthreads-win32/ http://disch-systems.de/download/pthreads-2005-01-25.exe Within Windows copy both files, dps_requests.exe and pthreadGC1.dll, to a directory of your choice. Usage example of dps_requests: my-linux:~# ./dps_requests RBU 217.91.62.77 1 3/1/5 7 25.200000 my-linux:~# If your firewall is configured to work with dps_requests, i.e. the ports 2999, 3006 ... 3037 and 4001 ... 4033 are opened for outgoing TCP packets, then this example reads the temperature of an EIB-Pt 100 from our EIB system via internet. dps_requests generally has 11 modes of operation: RNB (Read Non Buffered): Read values of group addresses directly from EIB and output the results to STDOUT. Do return immediately. RBU (Read BUffered): Read values of group address from process image and output the results to STDOUT. Do return immediately. LIS (LIsten and output to Script or program): Listen to group addresses on EIB and run the given script file with all received values as arguments. Do not return immediately. LIF (LIsten and output to File): Listen to group addresses on EIB and output all received values to the given logging file. Do not return immediately. MON (MONitor): Monitor whole EIB and output all received values to standard output. Do not return immediately. User should use MNA instead MON. Only for backward compatibility. MNA (AlterNate Monitor): Monitor whole EIB and output all received values to standard output. Uses the DPSAPI_MonitorInit() and DPSAPI_MonitorExit() functions. Do not return immediately. WRI (WRIte): Write new values to group addresses. Outputs the number of successfully written group addresses to STDOUT. Do not return immediately. RSN (Read Serial Number): Read the serial number of the EIB Driver and output the serial number to STDOUT. Do return immediately. RPM (Read Programming Mode): Read the state of programming mode and output it to STDOUT. Do return immediately. CMD (CoMmanD mode): Opens a command shell that has this simple syntax: ( RNB | RBU ) num_elems [ ( GAn EISn ) ... ] WRI num_elems [ ( GAn EISn Valn ) ... ] BYE Do not return immediately. WPM (Write Programming Mode): Write the state of programming mode. Do return immediately. Each command line argument is separated with two spaces. The arguments of the operational modes of dps_requests are: ip_addr (IP Address): The IP address of the EIB Driver that has access to EIB rsp. that of the Name Server. dps_reqeusts uses the ports from 4001 up to 4033 to communicate with the EIB Driver and the ports 2999 and 3006 up to 3037 to communicate with the Name Server. num_elems (Number of Elements): Number of pairs (for RNB, RBU, LIS and LIF) or tripples (for WRI). A pair is always a group address and an EIS type. A tripple is always a group address, an EIS type and a Value. GAn (Group Address n): A group address can be provided as integer number (i.e. 2345). Furthermore as main group and sub group (i.e. 1/8) or as main group, middle group and sub group (i.e. 7/5/3). n stands for 1 up to num_elems. EISn (EIS type n): The definition of EIS types (EIS = EIB Interworking Standard, i.e. data format definition of group addresses) are given below. EIS types are always provided as integer numbers. n stands for 1 up to num_elems. Valn (Value n): The value has the format of EIS type. n stands for 1 up to num_elems. For definition of EIS types see below. command (Command or script to be run): Target script or program to receive the output of dps_requests. The output is written to the target application while dps_requests is running. For definition of output format see below. Only used with LIS. file (File to be logged into): Logfile where the output of dps_requests is written. The output is written to the target logfile while dps_requests is running. For definition of output format see below. Only used with LIF. sleep (time in seconds): Do not return immediately, but wait the time "sleep" to return. The time sleep can vary from 1 to 65535 seconds. Set to "0" to have dps_requests running forever. Only used with LIS, LIF, MON and MNA. The return values of dps_requests are: 0 (Successful): Request sucessfully done. But, keep in mind that this return value doesn't state anything about the validness of the returned values while reading or that a write was successfully done with the EIB device. 1 (Connect Error): Error while trying to connect to EIB Driver for Linux. Check if EIB Driver for Linux is running. 2 (Argument Error): User provided arguments are wrong. Use dps_requests -h for some simple hints or consult this document. 3 (Other Error): Other errors like a failed disconnect from EIB Driver for Linux, the inability to create the output file in LIF mode, being unable to set a needed environment variable or a CID mismatch in monitor mode. Usage hints about performance: You always should prefer a RBU before a RNB because RBU normally will not send a request to the EIB. RBU has, because of that, greater performance than RNB. RBU is reading out of the process image. If a value is unknown to the process image, a RNB is done instead. If you do several RBU, RNB or WRI within one script, it's a good choice to use command mode CMD. This reduces overhead of starting rsp. ending dps_requests and of connecting rsp. disconnecting EIB Driver. The operational mode WRI has precedence over RNB, RBU, LIS and LIF. Writing not only will slow down reading, but will also block reading until all values are written. Be always reminded, if reading is blocked, there is actually some heavy writing under the way, even from different users. If the EIB Driver is blocking reading, then it is only blocked against the client software, i.e. dps_requests. Learning the process image is working independently. If you try to place too much write requests at a short time frame and the EIB Driver can not write them instantly to the EIB, the write requests are queued up. The queue is capable of queueing up to 1.000 requests. If you once fill up the queue, no more requests are queued until there is free space left. If you experience that your writing is blocked, then you should run less requests. Please be reminded, that the script (or program) that you provide to LIS, must be as short as possible. Your script (or program) is run synchonously to the callback function of the listener and therefore the runtime of the script (or program) must be kept short. Another possibility is to detach the script (or program) from stdin, stdout and stderr at the start of the script (or program). For example at the very beginng of a PHP script that is called from a PHP (cli) interpreter you should do: . Definition of EIS types and their formats: EIS Integer Usage Data type C-style printf ============================================================================== EIS1 1 switching 1 bit " %d " EIS2_P 2 dimming: position 1 bit " %d " EIS2_C 3 dimming: control 4 bit " %d " EIS2_V_P 4 dimming: value percent (%) 1 byte " %f " EIS2_V_D 104 dimming: value degree (°) 1 byte " %f " EIS3 5 time 3 bytes " %s %d:%d:%d " EIS4_F 6 date full format 3 bytes " %d.%d.%d " EIS4_C 106 date century format 3 bytes " %d.%d.%d " EIS5 7 value 2 bytes " %f " EIS6_P 8 scaling percent (%) 1 byte " %f " EIS6_D 108 scaling degree (°) 1 byte " %f " EIS7_M 9 drive control: move 1 bit " %d " EIS7_S 10 drive control: step 1 bit " %d " EIS8_P 11 priority: position 1 bit " %d " EIS8_C 12 priority: control 2 bit " %d " EIS9 13 float value 4 bytes " %iE%i " EIS10_S 14 16-bit counter value signed 2 bytes " %d " EIS10_U 114 16-bit counter value unsigned 2 bytes " %d " EIS11_S 15 32-bit counter value signed 4 bytes " %d " EIS11_U 115 32-bit counter value unsigned 4 bytes " %d " EIS12 16 access 4 bytes " %X " EIS13 17 ASCII character 1 byte " %d " EIS14_S 18 8-bit counter value signed 1 byte " %d " EIS14_U 118 8-bit counter value unsigned 1 byte " %d " EIS15 19 character string <14 bytes " %s " NONEIS_0 20 variable sized datagram <6 bits " 0x%.02X " NONEIS_1 21 variable sized datagram 1 byte " 0x%.02X " NONEIS_2 22 variable sized datagram 2 bytes " 0x%.02X 0x%.02X " NONEIS_3 23 variable sized datagram 3 bytes 3 times NONEIS_1 NONEIS_4 24 variable sized datagram 4 bytes 4 times NONEIS_1 NONEIS_5 25 variable sized datagram 5 bytes 5 times NONEIS_1 NONEIS_6 26 variable sized datagram 6 bytes 6 times NONEIS_1 NONEIS_7 27 variable sized datagram 7 bytes 7 times NONEIS_1 NONEIS_8 28 variable sized datagram 8 bytes 8 times NONEIS_1 NONEIS_9 29 variable sized datagram 9 bytes 9 times NONEIS_1 NONEIS_10 30 variable sized datagram 10 bytes 10 times NONEIS_1 NONEIS_11 31 variable sized datagram 11 bytes 11 times NONEIS_1 NONEIS_12 32 variable sized datagram 12 bytes 12 times NONEIS_1 NONEIS_13 33 variable sized datagram 13 bytes 13 times NONEIS_1 NONEIS_14 34 variable sized datagram 14 bytes 14 times NONEIS_1 Samples of user input and program output for different EIS types and remarks about it: EIS Sample(s) Remark ============================================================================== EIS1 " 1 " binary scheme: 1=on 0=off EIS2_P " 1 " binary scheme: 1=on 0=off EIS2_C " 7 " or " 9 " binary scheme: bit 0 thru 2 stepcode bit 3=1 increasing bit 3=0 decreasing stepcode 0: stop stepcode 1: 100% stepcode 2: 50% stepcode 3: 25% stepcode 4: 12% stepcode 5: 6% stepcode 6: 3% stepcode 7: 1% sample " 7 ": decreasing about 1% sample " 9 ": increasing about 100% EIS2_V_P " 7.123456 " range: 0 .. 100% EIS2_V_D " 7.123456 " range: 0 .. 360° EIS3 " Monday 12:33:07 " weekday: always English language while writing: do not forget to use quotation marks or use "\ " instead EIS4_F " 07.12.2001 " range of year: 1900 .. 2155 EIS4_C " 07.12.01 " range of year: 1990 .. 2089 EIS5 " -7.123456 " reading: fixed divisor 100 writing: fixed multiplier 100 EIS6_P " 7.123456 " range: 0 .. 100% EIS6_D " 7.123456 " range: 0 .. 360° EIS7_M " 1 " binary scheme: 1=move down/close 0=move up/open EIS7_S " 1 " binary scheme: 1=stop/step down 0=stop/step up EIS8_P " 1 " binary scheme: 1=on 0=off EIS8_C " 3 " binary scheme: 0X=no control 10=control disable 11=control enable EIS9 " -45E2 " or " 7.89E-3 " format: IEEE floating point, the "E" represents power to the base of 10 EIS10_S " -32000 " range: -32768 .. 32767 EIS10_U " 65000 " range: 0 .. 65535 EIS11_S " 650000 " range: - 2147483648 .. 2147483647 EIS11_U " 650000 " range: 0 .. 494967295 EIS12 " AB12DC43 " scheme: 8 characters in hexadecimals EIS13 " 128 " scheme: 1 char out of 128 chars EIS14_S " -127 " range: -128 .. 127 EIS14_U " 255 " range: 0 .. 255 EIS15 " hello world! " scheme: has variable length with up to 14 bytes (ASCII chars) NONEIS_0 " 31 " input scheme: 0 .. 31 output scheme: up to 5 bits with hexadecimal representation NONEIS_1 " 255 " input scheme: 0 .. 255 " 0xFF 0x00 " output scheme: 1 hexadecimal byte value NONEIS_2 " 255:0 " input scheme: 0 .. 255 separated with ":" " 0xFF 0x00 " output scheme: 2 hexadecimal byte values NONEIS_3 " 255:0:128 " input scheme: 0 .. 255 separated with ":" " 0xFF 0x00 0x80 " output scheme: 3 hexadecimal byte values NONEIS_4 " 255:0:128:127 " input scheme: 0 .. 255 separated with ":" " 0xFF 0x00 0x80 0x7F " output scheme: 4 hexadecimal byte values NONEIS_5 up to NONEIS_14 are similar to NONEIS_2 up to NONEIS_4. Usage hints about EIS types: While writing you will not receive a warning about mismatched EIS types, i.e. the real EIS type is different from that you think. TP-UART is not sending back error messages if EIS types are mismatched. To check EIS types it is recommended to read them. If you read buffered or non buffered with a mismatched EIS type, then you will possibly receive a timeout error instead a warning about mismatching EIS types. Usage hints about group addresses: Writing to non exisisting group addresses will not produce an error. Be always careful to use correct group addresses while writing. TP-UART is not sending back error messages if group addresses are not existing. To check group addresses it is recommended to read them. Usage hints about monitors: If you use the monitors (MON|MNA) and if you close dps_requests with ^C you must consider that the monitors need some time to shut down. While this time it is impossible to start a new monitor. See the output of ./dps_requests -h for an estimation about the needed time. Output format of monitor mode and alternate monitor mode: Monitor mode outputs all received EIB datagrams in this format: GA [ Val | ( Valn ... ) ] PA EIS Qual Time While the output fields are defined in that way: GA (Group Address): A group address is always returned as main group, middle group and sub group (i.e. 7/5/3). PA (Physical Address): The physical address of the sender of the datagram. Val | Valn (Value or Value n): The value has the format of EIS type. If the EIS type is unknown, then the value is given as hexadecimal number. In the latter case n stands for 1 up to count of bytes specified by EIS type. EIS (EIS type): The definition of EIS type. If EIS type is unknown, then the count of bytes or the circumstance, that the EIS type was a bit typed EIS type with less than 6 bit, is returned. For definition of EIS types see above. Qual (Quality): The quality of the received value. Should always be good. Other quality values are uncertain and bad. Time (Timestamp): The Unix time when the datagram was received. Example for EIS5 type: 3/1/5 0x19 0x30 02.01.225 2 Byte good 1132759206 Output format for calling a script or a program: Listen to script or program outputs all received EIB datagrams of the specified group address in this format: GA Val EIS While the output fields are defined in that way: GA (Group Address): A group address is always returned as main group, middle group and sub group (i.e. 7/5/3). Val (Value): The value has the format of EIS type. For definition of format of EIS types please see above. EIS (EIS type): The definition of EIS type. For definition of EIS types see above. Example for EIS5 type: 3/1/5 24.240000 7 Output format of the logfile: Not yet documented. Listen and output to file is beta software and therefore not fully tested. Use at your own risk!