API Documentation
The API for the IPMSW1 is similar to that used for the KIRA IP/IR modules. Like the KIRA modules this API uses UDP on port 65432 (default) for the data and UDP port 30303 for the discovery.
<space> is an ascii space character 32 (0x20 in hex)
Data port is assumed to be the default 65432 but can be changed on the config web page. If you have changed the port you will need to change in the commands below.
Basic commands
Turn switch on or off
KMS<space>ON(n)
KMS<space>OFF(n)
The above data is sent to the IP address of the switch on UDP port 65432 as ascii text.
To switch on switch 1 send "KMS ON1" to the address of the module on UDP port 65432
To switch off switch 2 send "KMS OFF2" to the address of the module on UDP port 65432
Query switch state
KMS<space>O?
The Above data is sent to the IP address of the switch module on UDP port 65432 as ascii text
To get the switch states snd "KMS O?" to the address of the module on UDP port 65432.
The switch module will return
"Sw 1 is ON\r\n" or "Sw 1 is OFF\r\n"
followed by
"Sw 2 is ON\r\n" or "Sw 2 is OFF\r\n"
\r\n is the control code carrieage return, line feed. So if 1 is on and 2 is off, as text you will see
Sw 1 is ON
Sw is OFF
Disable / enable front panel switches
// KMS SPON or KMS SPOFF
KMS<space>SPON
or
KMS<space>SPOFF
The Above data is sent to the IP address of the switch module on UDP port 65432 as ascii text
It will either enable or disable control of the switches by the panel pushbuttons.
Get date and time
KMS<space>RT
The Above data is sent to the IP address of the switch module on UDP port 65432 as ascii text
The switch will return the date and time as
D+T29/02/12
21:18
There is one in the middle between the date and time and one at the end
Manual Set Date and Time
//KMS MDT
KMS MDT<date as 8 digit ascii><time as 5 digit ascii>
The Above data is sent to the IP address of the switch module on UDP port 65432 as ascii text
Please note the module does not do any validation on the data supplied so it is down to you to make sure your data is good!
Sending this function will automatically set internet time updates to off in the module
EG "KMS MDT22/11/1218:39"
sets the date as November the 22nd and the time as 21 minute to 7 in the evening.
More advanced commands
Startup modes
The delay is always sent even if it is not in use. It is an unsigned char (byte) of between 0 and 255. It is sent as data not as ascii text.
The modes can have one of three values
Get startup modes
//KMS RS
KMS<space>RS
The Above data is sent to the IP address of the switch module on UDP port 65432 as ascii text
The switch will return
STARTUP1(M1)(M1D)2(M2)(M2D) followed by a carriage return and line feed
(M1) = mode of start modse of switch 1 as an unsigned byte.
(M1D) = start delay of switch 1 as an unsigned byte byte
similarly (M2) is mode of switch 2 etc.
Set startup modes
// KMS SS1(M1)(D1)2(M2)(D2)
KMS<space>SS1(M1)(D1)2(M2)D2)
The Above data is sent to the IP address of the switch module on UDP port 65432 MOSTLY as ascii text but the modes and the delays are unsigned bytes.
Timers
Timers are set and read as a series of data bytes. They use the data structure shown below
The "unsigned char switch_is_on :1;" is a bit flag.
There are 8 of these making up the Flags byte.
There are 6 timers, 3 per switch. Timers 0 – 2 relate to the 3 switch 1 timers and timers 3 - 5 relate to the switch 2 timers
day of week
1 = Monday
7 = Sunday
The timers use a fixed data structure as below
typedef struct
{
unsigned char minutes;
unsigned char hours;
unsigned char days;
unsigned char months;
unsigned char years;
unsigned char DayOfWeek;
}TIMER_DATE;
typedef struct
{
struct
{
unsigned char enabled :1;
unsigned char switch_is_on :1;
unsigned char on_during_event:1;
unsigned char repeat_daily :1;
unsigned char repeat_weekly :1;
unsigned char repeat_monthly :1;
unsigned char switch2 :1;
unsigned char event_in_progress :1;
} Flags;
TIMER_DATE start_date;
TIMER_DATE end_date;
}TIMER_DATA;
Get timer info
// KMS T(n)R
n is ascii
n = 0 – 2 for Sw1 timers
n = 3 – 5 for Sw2 timers
The Above data is sent to the IP address of the switch module on UDP port 65432 as ascii text
The switch will return "Timer" + n as ascii digit + 13 bytes,
raw data NOT asccii
byte 1 is flags
6 bytes are start date time
6 bytes are end date time
see structure above for detail of bytes
Set timer
// KMS T(n)S<data>
n is ascii
n = 0 – 2 for Sw1 timers
n = 3 – 5 for Sw2 timers
data is raw data NOT asccii
byte 1 is flags
6 bytes are start date time
6 bytes are end date time
see structure above for detail of bytes
The Above data is sent to the IP address of the switch module on UDP port 65432 as mostly ascii text
get timer enabled
// KMS RE
"KMS RE"
The Above data is sent to the IP address of the switch module on UDP port 65432 as mostly ascii text
The switch returns "ENABLE1<data1>2<data2>
data is raw and will be either zero or one.
set timer enabled
// KMS ET(1)(2)
"KMS ET01"
The Above data is sent to the IP address of the switch module on UDP port 65432 as ascii text
EG "KMS ET01" will enable timers for switch 2 but disable switch 1
Discovery
Discovery commands
All discovery is done using UDP port 30303.
disD
To find what modules are on your local network send "disD" as ascii text on UDP port 30303 to either the IP address of the module – if you know it – or to 255.255.255.255
255.255.255.255 is the broadcast address. To broadcast to just your local subnet use xxx.xxx.xxx.255 where xxx is your local subnet IP address i.e. 192.168.1.255
The module will reply with
NETSWITCH
192.192.192.37
00:04:A3:2A:08:56
4 = IPMSW1
65432
192.192.192.37
255.255.255.0
192.192.192.1
192.168.1.1
192.192.192.1
Sw 1 is ON
Sw 2 is ON
192.192.192.162
DHCP = off
pool.ntp.org
1.80
Keene
Electronics
Discovery reply
This is what they mean
NETSWITCH // host name
192.192.192.37 // module IP address
00:04:A3:2A:08:56 // module MAC address
4 = IPMSW1 // KIRA family ID number and description
65432 // data port
192.192.192.37 // last IP address
255.255.255.0 // subnet mask
192.192.192.1 // gateway IP address
192.168.1.1 // DNS 1
192.192.192.1 // DNS 2
Sw 1 is ON // Sw1 on or off
Sw 2 is ON // Sw2 on or off
192.192.192.162 // current PC address
DHCP = off // DHCP is on or off
pool.ntp.org // Internet time server
1.80 // Firmware version
Keene // current user name
Electronics // current password
Discovery reply // identification of packet
disC
This uses the discovery system to allow access to modules that are not on your current subnet. This can be handy if you can see discovery packets from the module but can't access the web pages because it is not on your subnet.
You need to make sure that nothing is occupying the new IP address before you send this command!
Send "disC" using UDP on port 30303 and set the IP address to broadcast. (255.255.255.255)
On receipt the module will change the first 3 bytes of its IP address to match those of the sender
e.g. Send from PC on 192.168.100.12 on UDP port 30303 to broadcast IP (255.255.255.255)
Module is on 192.168.0.35. After receipt of packet module will be on 192.168.100.35
php
A php code snipit you may find useful (thanks go to Sumit Rai)
<?PHP
//Simple script to turn ON the first switch.
//IP address needs to be specified in place of 192.168.0.143
$socket = socket_create(AF_INET, SOCK_DGRAM, 17) or die("Could not create socket\n");
$message = "KMS ON1";
socket_sendto($socket, $message, strlen($message), 0, "192.168.0.143", "65432");
?>