569
edits
Changes
Monitoring via JSON-RPC linux RutOS (view source)
Revision as of 14:42, 2 August 2023
, 14:42, 2 August 2023no edit summary
<p style="color:red">The information on this page is updated in accordance with the [https://wiki.teltonika-networks.com/view/FW_%26_SDK_Downloads'''00.07.4'''] firmware version .</p>
==Introduction==
==Introduction==
'''JSON-RPC''' is a remote procedure call protocol encoded in JSON. It is a very simple protocol (and very similar to XML-RPC), defining only a few data types and commands. JSON-RPC allows for notifications (data sent to the server that does not require a response) and for multiple calls to be sent to the server which may be answered out of order.
'''JSON-RPC''' is a remote procedure call protocol encoded in JSON. It is a very simple protocol (and very similar to XML-RPC), defining only a few data types and commands. JSON-RPC allows for notifications (data sent to the server that does not require a response) and for multiple calls to be sent to the server which may be answered out of order.
==Using JSON-RPC (Linux)==
==Using JSON-RPC (Linux)==
This section describes how to use JSON-RPC commands with a Linux OS system. To find the guide for Windows users, jump to this section: '''[[{{{link}}}|JSON-RPC on Widnows]]'''
This section describes how to use JSON-RPC commands with a Linux OS system. To find the guide for Windows users, jump to this section [[Monitoring_via_JSON-RPC_windows_RutOS|here]].
===Obtaining a session ID===
===Obtaining a session ID===
To log in to the router via JSON-RPC you must first obtain a Session ID. To do so, you must send an '''HTTP POST''' request to the router. Open the Linux '''Terminal''' app and execute this command:
To log in to the router via JSON-RPC you must first obtain a Session ID. To do so, you must send an '''HTTP POST''' request to the router. Open the Linux '''Terminal''' app and execute this command:
curl -d "{ \"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"call\", \"params\": [ \"00000000000000000000000000000000\", \"session\", \"login\", { \"username\": \"root\", \"password\": \"<span style=color:orange>admin01</span>\" } ] }" http://<span style=color:green>192.168.1.1</span>/ubus
curl -d "{ \"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"call\", \"params\": [ \"00000000000000000000000000000000\", \"session\", \"login\", { \"username\": \"admin\", \"password\": \"<span style=color:orange>admin01</span>\" } ] }" http://<span style=color:green>192.168.1.1</span>/ubus
The section highlighted in orange is the router's admin password. admin01 is the default value, replace it with your router's password. The address highlighted in green is the router's IP address. Replace this value with your router's IP. If you're trying to reach the router from '''[[{{{name}}}_LAN|LAN]]''', use the local IP address (default: 192.168.1.1), if you're trying to reach the router from '''[[{{{name}}} WAN|WAN]]''', use the router's WAN IP address.
The section highlighted in orange is the router's admin password. admin01 is the default value, replace it with your router's password. The address highlighted in green is the router's IP address. Replace this value with your router's IP. If you're trying to reach the router from LAN, use the local IP address (default: 192.168.1.1), if you're trying to reach the router from WAN, use the router's WAN IP address.
[[File:JSON ID.png|border|center|class=tlt-border|835x481px]]
The picture above depicts the process of obtaining a Session ID. The ID itself is encapsulated in a red rectangle. Copy this ID as you will need it to authenticate yourself when using other commands.
The picture above depicts the process of obtaining a Session ID. The ID itself is encapsulated in a blue rectangle. Copy this ID as you will need it to authenticate yourself when using other commands.
===Getting router parameters===
===Getting router parameters===
----
----
Now that you have obtained a Session ID, you can issue commands to the router. Lets start with commands that return information about the router.
Now that you have obtained a Session ID, you can issue commands to the router. Lets start with commands that return information about the router.
====Getting RSSI====
====Getting signal levels====
----
----
This is a command that returns the router's '''[[RSSI]]'''(signal strength) value:
This is a command that returns the router's signal levels value:
curl -d "{ \"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"call\", \"params\": [\"<span style=color:red>a74c8e07646f0da2bfddce35bf3de1f3</span>\", \"file\", \"exec\", { \"command\":\"<span style=color:orange>gsmctl</span>\", \"params\": [\"<span style=color:green>-q</span>\"] } ] }" http://<span style=color:black>192.168.1.1</span>/ubus
curl -d "{ \"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"call\", \"params\": [\"<span style=color:red>a74c8e07646f0da2bfddce35bf3de1f3</span>\", \"file\", \"exec\", { \"command\":\"<span style=color:orange>gsmctl</span>\", \"params\": [\"<span style=color:green>-q</span>\"] } ] }" http://<span style=color:black>192.168.1.1</span>/ubus
Highlighted in red is the Session ID. Replace it with the Session ID that was provided to you. Highlighted in orange is the command that we used for our query and highlighted in green is the parameter for the command: '''gsmctl -q'''.
Highlighted in red is the Session ID. Replace it with the Session ID that was provided to you. Highlighted in orange is the command that we used for our query and highlighted in green is the parameter for the command: '''gsmctl -q'''.
The picture bellow is a visual representation of this example. Encapsulated in a blue rectangle is the answer to the ''gsmctl -q'' query: '''-73 dBm'''.
The picture bellow is a visual representation of this example. Encapsulated in a red rectangle is the answer to the ''gsmctl -q'':
[[Image:Configuration examples json-rpc terminal gsmctl.png|961px|border|class=tlt-border]]
[[File:JSON gsmctl.png|border|center|class=tlt-border|833x481px]]
You can issue almost any Linux command in a similar manner. For example, if you wish to get a list of file names contained in the config folder, the Linux command to do so would be '''ls /etc/config''', which, translated to JSON-RPC, would be:
You can issue almost any Linux command in a similar manner. For example, if you wish to get a list of file names contained in the config folder, the Linux command to do so would be '''ls /etc/config''', which, translated to JSON-RPC, would be:
curl -d "{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"call\", \"params\": [\"a74c8e07646f0da2bfddce35bf3de1f3\", \"file\", \"exec\", {\"command\":\"<span style=color:orange>ls</span>\", \"params\": [\"<span style=color:orange>/etc/config</span>\"] } ] }" http://<span style=color:black>192.168.1.1</span>/ubus
curl -d "{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"call\", \"params\": [\"a74c8e07646f0da2bfddce35bf3de1f3\", \"file\", \"exec\", {\"command\":\"<span style=color:orange>ls</span>\", \"params\": [\"<span style=color:orange>/etc/config</span>\"] } ] }" http://<span style=color:black>192.168.1.1</span>/ubus
[[Image:Configuration examples json-rpc terminal ls.png|961px|border|class=tlt-border]]
[[File:JSON ls config.png|border|center|class=tlt-border|833x481px]]
The command is encapsulated in an orange rectangle and the answer - in a blue one.
The answer is encapsulated in an red rectangle.
===Setting router parameters===
===Setting router parameters===
The ''uci set'' command is used to set router parameters. As an example, lets try to change the router's '''LAN IP address'''. The command to do so looks like this:
The ''uci set'' command is used to set router parameters. As an example, lets try to change the router's '''LAN IP address'''. The command to do so looks like this:
curl -d "{\"jsonrpc\":\"2.0\", \"id\":1, \"method\":\"call\", \"params\":[\"590bde71578da2fabfe77ba86c00e4e5\", \"uci\", \"set\", { \"config\":\"<span style=color:orange>network</span>\", \"type\":\"<span style=color:orange>interface</span>\", \"match\": {\"ipaddr\":\"<span style=color:red>192.168.1.1</span>\"}, \"values\": {\"ipaddr\":\"<span style=color:green>192.168.56.1</span>\"} } ] }" http://<span style=color:black>192.168.1.1</span>/ubus
curl -d "{\"jsonrpc\":\"2.0\", \"id\":1, \"method\":\"call\", \"params\":[\"590bde71578da2fabfe77ba86c00e4e5\", \"uci\", \"set\", { \"config\":\"<span style=color:orange>network</span>\", \"type\":\"<span style=color:orange>interface</span>\", \"match\": {\"ipaddr\":\"<span style=color:red>192.168.1.1</span>\"}, \"values\": {\"ipaddr\":\"<span style=color:green>192.168.11.1</span>\"} } ] }" http://<span style=color:black>192.168.1.1</span>/ubus
The sections highlighted in orange describe the config file's name and section (in this case, network config and interface section). Highlighted in red is the option in the config file that you wish to change (in this case, the router's LAN IP address, '''ipaddr'''). Finally, highlighted in green is the value that will to replace the old value (in this case, change the router's LAN IP address to 192.168.56.1). If the command was issued successfully, you should see a Response like this:
The sections highlighted in orange describe the config file's name and section (in this case, network config and interface section). Highlighted in red is the option in the config file that you wish to change (in this case, the router's LAN IP address, '''ipaddr'''). Finally, highlighted in green is the value that will to replace the old value (in this case, change the router's LAN IP address to 192.168.11.1). If the command was issued successfully, you should see a Response like this:
[[File:JSON change LAN IP.png|border|center|class=tlt-border|833x481px]]
[[Image:Configuration examples json-rpc terminal uci set.png|961px|border|class=tlt-border]]
====UCI COMMIT====
====UCI COMMIT====
'''{"jsonrpc":"2.0","id":1,"result":[0]}'''
'''{"jsonrpc":"2.0","id":1,"result":[0]}'''
====LUCI-RELOAD====
====RELOAD_CONFIG====
----
----
In order for the changes to take effect, use the '''luci-reload''' command which restarts all of the router's services. The luci-reload command looks like this:
In order for the changes to take effect, use the '''reload_config''' command which restarts all of the router's services. The reload_config command looks like this:
curl -d "{\"jsonrpc\":\"2.0\",\"id\":1, \"method\":\"call\", \"params\":[\"428a9fa57f1a391db0bd1b865fa16bb5\", \"file\", \"exec\", {\"command\": \"<span style=color:orange>luci-reload</span>\"} ] }" http://<span style=color:black>192.168.56.1</span>/ubus
curl -d "{\"jsonrpc\":\"2.0\",\"id\":1, \"method\":\"call\", \"params\":[\"428a9fa57f1a391db0bd1b865fa16bb5\", \"file\", \"exec\", {\"command\": \"<span style=color:orange>reload_config</span>\"} ] }" http://<span style=color:black>192.168.56.1</span>/ubus
The command itself is highlighted in orange.
The command itself is highlighted in orange.
The command above will '''enable''' the Ping Reboot function, set the host to ping to '''8.8.4.4''' and ping packet size to '''64'''. The default values are highlighted in orange and the new ones are highlighted in green.
The command above will '''enable''' the Ping Reboot function, set the host to ping to '''8.8.4.4''' and ping packet size to '''64'''. The default values are highlighted in orange and the new ones are highlighted in green.
'''Note: Remember always to use the commands in the order (set, commit, luci-reload)'''
'''Note: Remember always to use the commands in the order (set, commit, reload_config)'''
==Some Additional Commands==
==Some Additional Commands==
If the commands found in the guide above did not suffice your needs, this section provides a list of additional ones. The commands presented in this section will be for both Linux and Windows operating systems. They should be used as syntax examples for your own purposes.
If the commands found in the guide above did not suffice your needs, this section provides a list of additional ones. The commands presented in this section will be for both Linux and Windows operating systems. They should be used as syntax examples for your own purposes.
===WiFi clients list===
===WiFi clients list===
----
----
'''The response''' should look something like this:
'''The response''' should look something like this:
{"jsonrpc":"2.0","id":1,"result":[0,{"results":
{"jsonrpc":"2.0","id":1,"result":[0,{"results":
[{"mac":"<span style=color:green>E4:02:9B:88:09:AA</span>","signal":<span style=color:blue>-32</span>,"noise":<span style=color:blue>-88</span>,"inactive":<span style=color:blue>10</span>,"rx":
[{"mac":"<span style=color:green>E4:02:9B:XX:XX:XX</span>","signal":<span style=color:blue>-32</span>,"noise":<span style=color:blue>-88</span>,"inactive":<span style=color:blue>10</span>,"rx":
{"rate":<span style=color:blue>1000</span>,"mcs":<span style=color:blue>0</span>,"40mhz":<span style=color:blue>false</span>,"short_gi":<span style=color:blue>false</span>},"tx":
{"rate":<span style=color:blue>1000</span>,"mcs":<span style=color:blue>0</span>,"40mhz":<span style=color:blue>false</span>,"short_gi":<span style=color:blue>false</span>},"tx":
{"rate":<span style=color:blue>72200</span>,"mcs":<span style=color:blue>7</span>,"40mhz":<span style=color:blue>false</span>,"short_gi":<span style=color:blue>true</span>}},
{"rate":<span style=color:blue>72200</span>,"mcs":<span style=color:blue>7</span>,"40mhz":<span style=color:blue>false</span>,"short_gi":<span style=color:blue>true</span>}},
{"mac":"<span style=color:green>D8:C7:71:47:90:E1</span>","signal":<span style=color:blue>-12</span>,"noise":<span style=color:blue>-88</span>,"inactive":<span style=color:blue>400</span>,"rx":
{"mac":"<span style=color:green>D8:C7:71:XX:XX:XX</span>","signal":<span style=color:blue>-12</span>,"noise":<span style=color:blue>-88</span>,"inactive":<span style=color:blue>400</span>,"rx":
{"rate":<span style=color:blue>1000</span>,"mcs":<span style=color:blue>0</span>,"40mhz":<span style=color:blue>false</span>,"short_gi":<span style=color:blue>false</span>},"tx":
{"rate":<span style=color:blue>1000</span>,"mcs":<span style=color:blue>0</span>,"40mhz":<span style=color:blue>false</span>,"short_gi":<span style=color:blue>false</span>},"tx":
{"rate":<span style=color:blue>72200</span>,"mcs":<span style=color:blue>7</span>,"40mhz":<span style=color:blue>false</span>,"short_gi":<span style=color:blue>true</span>}}]}]}
{"rate":<span style=color:blue>72200</span>,"mcs":<span style=color:blue>7</span>,"40mhz":<span style=color:blue>false</span>,"short_gi":<span style=color:blue>true</span>}}]}]}
To obtain these values, the Linux '''iwinfo''' command and '''assoclist''' parameter (red) are used. Highlighted in green are the devices connected to the router via WiFi as identified by their MAC addresses. The response information about the connection with the device, such as signal strength, noise, time of inactivity (idle time), rx, tx rate, etc., is highlighted in blue.
To obtain these values, the Linux '''iwinfo''' command and '''assoclist''' parameter (red) are used. Highlighted in green are the devices connected to the router via WiFi as identified by their MAC addresses. The response information about the connection with the device, such as signal strength, noise, time of inactivity (idle time), rx, tx rate, etc., is highlighted in blue.
===WiFi information===
===WiFi information===
----
----
{"jsonrpc":"2.0","id":1,"result":[0,
{"jsonrpc":"2.0","id":1,"result":[0,
{"phy":"<span style=color:blue>phy0</span>","ssid":"<span style=color:blue>HAL9000</span>","bssid":"<span style=color:blue>00:1E:42:16:D6:68</span>","country":"<span style=color:blue>00</span>","mode":"<span style=color:blue>Master</span>","channel":<span style=color:blue>6</span>,"frequency":<span style=color:blue>2437</span>,"txpower":<span style=color:blue>20</span>,
{"phy":"<span style=color:blue>phy0</span>","ssid":"<span style=color:blue>HAL9000</span>","bssid":"<span style=color:blue>00:1E:42:XX:XX:XX</span>","country":"<span style=color:blue>00</span>","mode":"<span style=color:blue>Master</span>","channel":<span style=color:blue>6</span>,"frequency":<span style=color:blue>2437</span>,"txpower":<span style=color:blue>20</span>,
"quality":<span style=color:blue>22</span>,"quality_max":<span style=color:blue>70</span>,"signal":<span style=color:blue>22</span>,"noise":<span style=color:blue>-61</span>,"bitrate":<span style=color:blue>72200</span>,"encryption":
"quality":<span style=color:blue>22</span>,"quality_max":<span style=color:blue>70</span>,"signal":<span style=color:blue>22</span>,"noise":<span style=color:blue>-61</span>,"bitrate":<span style=color:blue>72200</span>,"encryption":
{"enabled":<span style=color:blue>false</span>},"hwmodes":["<span style=color:blue>b</span>","<span style=color:blue>g</span>","<span style=color:blue>n</span>"],"hardware":{"name":"<span style=color:blue>Generic MAC80211</span>"}}]}
{"enabled":<span style=color:blue>false</span>},"hwmodes":["<span style=color:blue>b</span>","<span style=color:blue>g</span>","<span style=color:blue>n</span>"],"hardware":{"name":"<span style=color:blue>Generic MAC80211</span>"}}]}
As with the clients list command described above, to obtain this information the Linux '''iwinfo''' command is used, but this time with the '''info''' parameter (red). The relevant information, such as WiFi SSID, WiFi MAC address, WiFi channel, Encryption type, etc., is highlighted in blue
As with the clients list command described above, to obtain this information the Linux '''iwinfo''' command is used, but this time with the '''info''' parameter (red). The relevant information, such as WiFi SSID, WiFi MAC address, WiFi channel, Encryption type, etc., is highlighted in blue
===Manufacturing information===
===Manufacturing information===
----
----
"805725a19ab0fba6c2b44ecf2f952fb9","file", "exec",
"805725a19ab0fba6c2b44ecf2f952fb9","file", "exec",
{
{
"command":"<span style=color:red>mnf_info</span>", "params":["<span style=color:red>name</span>", "<span style=color:red>sn</span>", "<span style=color:red>mac</span>"]
"command":"<span style=color:red>mnf_info</span>", "params":["<span style=color:red>--name</span>", "<span style=color:red>--batch</span>"]
}
}
]
]
'''Linux:'''
'''Linux:'''
curl -d "{ \"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"call\", \"params\": [ \"805725a19ab0fba6c2b44ecf2f952fb9\",\"file\", \"exec\",{ \"command\":\"<span style=color:red>mnf_info</span>\", \"params\":[\"<span style=color:red>name</span>\", \"<span style=color:red>sn</span>\", \"<span style=color:red>mac</span>\"] } ] }" http://<span style=color:black>192.168.1.1</span>/ubus
curl -d "{ \"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"call\", \"params\": [ \"805725a19ab0fba6c2b44ecf2f952fb9\",\"file\", \"exec\",{ \"command\":\"<span style=color:red>mnf_info</span>\", \"params\":[\"<span style=color:red>--name</span>\", \"<span style=color:red>--batch</span>\"] } ] }" http://<span style=color:black>192.168.1.1</span>/ubus
'''Response:'''
'''Response:'''
{"jsonrpc":"2.0","id":1,"result":[0,{"code":0,"stdout":"<span style=color:blue>RUT950HG12C0</span>\n<span style=color:blue>1367435694</span>\n<span style=color:blue>001e4216d666</span>\n"}]}
{"jsonrpc":"2.0","id":1,"result":[0,{"code":0,"stdout":"<span style=color:blue>"RUT955003XXX</span>\n<span style=color:blue>0105</span>\n<span style=color:blue>001e4216d666</span>\n"}]}
To obtain the manufacturing information the '''mnf_info''' (highlighted in red) command is used. In this case a query was sent asking for the device's Product Code (name), Serial Number (sn) and MAC Address (mac) (highlighted in red in the query; returned values highlighted in blue). Using ''mnf_info'', you can "ask" the router for any type of manufacturing information. Here is the list of possible ''mnf_info'' parameters:
To obtain the manufacturing information the '''mnf_info''' (highlighted in red) command is used. In this case a query was sent asking for the device's Product Code (name), Serial Number (sn) and MAC Address (mac) (highlighted in red in the query; returned values highlighted in blue). Using ''mnf_info'', you can "ask" the router for any type of manufacturing information. Here is the list of possible ''mnf_info'' parameters:
* '''mac''' - returns the router's LAN MAC address
* '''--mac''' - returns the router's LAN MAC address
* '''maceth''' - returns the router's WAN MAC address
* '''--maceth''' - returns the router's WAN MAC address
* '''name''' - returns the router's Product Code
* '''--name''' - returns the router's Product Code
* '''wps''' - returns the router's WPS PIN number
* '''--wps''' - returns the router's WPS PIN number
* '''sn''' - returns the router's Serial number
* '''--sn''' - returns the router's Serial number
* '''batch''' - returns the router's Batch number
* '''--batch''' - returns the router's Batch number
* '''hwver''' - returns the router's Hardware Revision number
* '''--hwver''' - returns the router's Hardware Revision number
* '''simpin''' - returns the router's SIM card's PIN (as it is specified in the '''[[RUT955 Mobile|Mobile]]''' section)
* '''--simpin''' - returns the router's SIM card's PIN (as it is specified in the '''[[RUT955 Mobile|Mobile]]''' section)
* '''blver''' - returns the router's Bootloader version
* '''--blver''' - returns the router's Bootloader version
===GPS Data===
===GPS Data===
----
----
{"jsonrpc":"2.0","id":1,"result":[0,{"code":0,"stdout":"<span style=color:blue>-23.612625\n-46.626355\</span>n"}]}
{"jsonrpc":"2.0","id":1,"result":[0,{"code":0,"stdout":"<span style=color:blue>-23.612625\n-46.626355\</span>n"}]}
The blue part in the code are the Latitude and Longitude.
The blue part in the code are the Latitude and Longitude.
<br>
===Firmware number===
===Firmware number===
----
----
This command ('''file''', '''read''', highlighted in red) is an alternative to the Linux '''cat''' command. All you need is to specify the path (in this case '''/etc/version''', highlighted in red) to the file that you wish to read.
This command ('''file''', '''read''', highlighted in red) is an alternative to the Linux '''cat''' command. All you need is to specify the path (in this case '''/etc/version''', highlighted in red) to the file that you wish to read.
===Reboot===
===Reboot===
----
----
'''Response:'''
'''Response:'''
The success response for this command is an empty message. If the response contains no data, the command was executed successfully.
The success response for this command is an empty message. If the response contains no data, the command was executed successfully.
===Set SIM card information===
===Set SIM card information===
----
----
{"jsonrpc":"2.0","id":1,"result":[<span style=color:blue>0</span>]}
{"jsonrpc":"2.0","id":1,"result":[<span style=color:blue>0</span>]}
The command used is ''uci set'' (highlighted in red). The config file name is '''simcard''', section '''sim1''', options '''mtu''' and '''service''' (configs, sections and options highlighted in orange). The response shown above is a positive response, but don't forget to execute ''uci commit'' and ''luci-reload'' afterwards or else your changes will not take effect.
The command used is ''uci set'' (highlighted in red). The config file name is '''simcard''', section '''sim1''', options '''mtu''' and '''service''' (configs, sections and options highlighted in orange). The response shown above is a positive response, but don't forget to execute ''uci commit'' and ''reload_config'' afterwards or else your changes will not take effect.
==See Also==
You may learn more about UCI commands [[UCI_command_usage|here]].
[[Category: RutOS Configuration Examples]]
[[Category:Router control and monitoring]]
