The Telnet M2M API interface is very simple. NETIO 4x products support Telnet connections and a limited command set at port 1234. This default port can be changed in the web configuration interface. The Telnet M2M API interface is disabled by default and needs to be explicitly enabled.
The protocol can be easily implemented in a custom program (it only needs to open a TCP socket, send a batch of commands to set the outputs, check the output states, and close the TCP socket) or tested in a standard Telnet terminal program.
A user program can invoke “cmd” to set the socket states (e.g. with a batch command). Another option is to implement the TCP protocol (Telnet) to a custom application and send the control strings through a TCP connection.
Supported devices: NETIO 4All, NETIO PowerPDU 4C, NETIO 4, PowerCable Modbus, PowerBOX 3Px, PowerPDU 4PS. PowerDIN 4Pz, PowerBOX 4Kx, PowerPDU 8QS
Configuring NETIO 4x electrical power sockets
In the NETIO 4x web administration, go to the M2M API Protocols section and enable Telnet/KSHELL. If necessary, modify the Port number. Click Save Changes.
Creating user for Telnet communication
We recommend to create a dedicated user for Telnet communication.
To create a user, follow these steps:
1) In the web administration, go to the Users section and add a new user by clicking the grey Create User button.
2) Enter a username and a password.
3) On the Privileges tab, click more..
4) Only leave log in and control outputs checked.
5) Save the user by clicking the green Create User button at the bottom of the screen.
These user credentials can now be used to access the device via Telnet.
Command-line example (Windows)
1) In Windows Vista, Windows 7 and higher versions, Telnet needs to be enabled first. Open Control Panels, go to Programs and Features and then to Turn Windows features on or off. Check the Telnet Client box and click OK.
2) Connect to your NETIO 4x device with this command: telnet <NETIO IP> <Port>. The response will look like: 100 HELLO 00000000 - KSHELL V1.5:
Command example (remember to change the IP address to match your device):
Reply example:
3) After the connection is established, log in using the login command (see below)
If the correct username and password is entered, the response is: 250 OK
Example for admin / admin:
4) Now you can control your NETIO device with the commands described below.
Note: Telnet is automatically disconnected after 60 seconds of inactivity. To prevent automatic log-off, use the noop command – this resets the connection timeout to 60 seconds.
List of commands for Telnet in power sockets NETIO
-
login <username> <password>
- Log in as a user.
- <username> is your login name, <password> is your password.
- Example to log in as admin / admin: login admin admin
- To see the list of users or create new users and assign privileges, go to the Users section.
-
quit
- Logs out and terminates the telnet session.
-
noop
- Resets the connection timeout to 60 seconds.
- Does not have any function (No-operation).
- port list [xxxx]
- Controls all sockets at once.
- Without parameters, lists the socket states.
-
List of parameters:
- 0 - turns the socket off
- 1 - turns the socket on
- 2 - briefly turns the socket off (if the socket was off, the command turns it on)
- 3 - briefly turns the socket on (if the socket was on, the command turns it off)
- 4 - toggles the socket state
- 5 - leaves the socket state unchanged
- i – restarts the socket (maintained for backwards compatibility)
-
u – leaves the socket state unchanged (maintained for backwards compatibility)
- Example – turn all sockets on: port list 1111
- Example – turn on sockets 1 and 3, turn off socket 4 and toggle socket 2: port list 1410
- Example – turn on sockets 2 and 3 and leave sockets 1 and 4 unchanged: port list 5115
- Note: All “x” in the command need to be replaced with an actual parameter. If the state of a particular socket should not change, use “5” as the parameter. For example, port list 10x1 is not a valid command.
-
port <output> <action>
- Controls one particular socket.
- <output> is the socket number
- <action> is one of the possible parameters
- If <action> is omitted, the command prints the socket state.
-
Parameters:
- 0 - turns the socket off
- 1 - turns the socket on
- 2 - briefly turns the socket off (if the socket was off, the command turns it on)
- 3 - briefly turns the socket on (if the socket was on, the command turns it off)
- 4 - toggles the socket state
- 5 - leaves the socket state unchanged
- i – restarts the socket (maintained for backwards compatibility)
-
u – leaves the socket state unchanged (maintained for backwards compatibility)
- Example – turn on socket 1: port 1 1
- Example – turn off socket 3: port 3 0
- Each command must be terminated with the CR and LF characters (0D and 0A in ASCII). In the terminal, these symbols are inserted by pressing Enter.
- Example: Log in, switch on sockets 1 and 2, and log out:
Third-party software
Checked software: Hercules, PuTTY, Linux Telnet, Windows Telnet
Note: Some terminals don't support Backspace.
PuTTY example:
Controlling the sockets with a single command
- Outputs can be also controlled with commands expressed as hexadecimal values. To encode that the “Enter” key should be pressed, use CR+LF (0D0A).
- This method is useful for controlling the device over a TCP socket.
- The hexadecimal string is created by concatenating individual commands (as described above) and converting each character to its hexadecimal representation according to the ASCII table (see for example https://www.asciitable.com). The Enter key that separates individual commands is encoded as 0D0A.
- Example – turn on socket 4:
- Yellow color marks the “Enter keypresses“ that delimit individual commands
-
Hexadecimal representations of the most common commands:
- login - 6C6F67696E
- 1 – 31
- 2 – 32
- 3 – 33
- 4 - 34
- port - 706F7274
- port list - 706F7274206C697374
- quit - 71756974
Example in Hercules – log in, switch on socket 4, and log out.
-
Command:
login netiotelnet
telnet 321
port 4 1
quit - As a single command: 6C6F67696E206E6574696F74656C6E65742074656C6E65743332310D0A706F7274203420310D0A71756974
FAQ:
1) Is it possible to set the delay for actions 2 (short Off) and 3 (short On) over Telnet?
No, the delay cannot be changed in the Telnet (KSHELL) protocol. The default delay is used. However, the default delay can be changed in the web interface.
2) Is it possible to increase the connection timeout to more than 60 seconds?
No, it is necessary to keep the connection alive with noop commands.
3) When using the Telnet type M2M API, the NETIO 4x smart sockets device is a TCP client or a TCP server?
When the Telnet M2M protocol is enabled, NETIO smart sockets listen as a TCP server at the configured port. A TCP connection is established by a TCP client (in this AN, that would be e.g. PuTTY or Hercules utility).
4) Is the Telnet KSHELL protocol in NETIO 4x smart sockets compatible with the legacy KOUKAAM products?
The legacy versions of NETIO products were produced by Koukaam company. The KSHELL (Koukaam Shell) protocol is compatible with these products:
- NETIO 230A
- NETIO 230B
5) I don't consider Telnet secure. Can I simply disable it?
Yes. Other M2M protocols can be used for secure communication. By default, Telnet is disabled.
6) What is the password for the Telnet M2M API? Can I use the default admin/admin?
The Telnet M2M API currently uses the same user credentials as the web configuration interface (Users tab). Therefore, it is possible to use the default admin/admin credentials. The option to create a separate user for the Telnet M2M will be added in a future firmware version.
7) Is it possible to read the consumption data over Telnet?
In the current firmware version the consumption cannot be read over Telnet. This function will be added in a future firmware version.
Supported FW versions:
3.0.0 and later (Firmware archive)
Also applicable to older FW versions – FW 2.3.2, 2.3.4, 2.3.5, 2.3.6, with some differences::
- Port cannot be changed
- The only supported parameters for socket control are 0, 1, i, u
Supported devices: