Skip to content

Repository files navigation

TP-Link Router API (supports also Mercusys Router)

Python package for API access and management for TP-Link and Mercusys Routers. See Supported routers

Pypi Downloads Python versions

Installation

pip install tplinkrouterc6u

Dependencies

Usage

  • Enter the host & credentials used to log in to your router management page. Username is admin by default. But you may pass username as third parameter. Some routers have default username - user
  • Use Local Password which is for Log In with Local Password. Login with TP-LINK ID doesnt work
  • If you use https connection - You need to turn on "Local Management via HTTPS" (advanced->system->administration) in the router web UI
from tplinkrouterc6u import (
    TplinkRouterProvider,
    TplinkRouterV1_11,
    TplinkRouterSG, # For routers like Archer BE3600, Archer BE230
    TplinkRouterAX72,
    TplinkRouter,
    TplinkC1200Router,
    TplinkC5400XRouter,
    TPLinkMRClient, # Class for MR series routers which supports old firmwares with AES cipher CBC mode
    TPLinkMRClientGCM, # Class for MR series routers which supports AES cipher GCM mode
    TPLinkMR200Client,
    TPLinkMR6400v7Client,
    TPLinkMR600Client, # Class for MR series that replaced the RSA key exchange with ECIES over NIST P-224
    TPLinkVRClient,
    TPLinkVR400v2Client,
    TplinkVR1200vRouter,
    TPLinkEXClient, # Class for EX series routers which supports old firmwares with AES cipher CBC mode
    TPLinkEXClientGCM, # Class for EX series routers which supports AES cipher GCM mode
    TPLinkRClient, # For routers like TL-R470GP-AC
    TPLinkXDRClient,
    TPLinkDecoClient,
    TplinkDecoE4RRouter,
    TPLinkEAP115Client,
    TPLinkCPE210Client,
    TPLinkSG108EClient,
    TplinkC80Router,
    TplinkWDRRouter,
    TPLinkC50Client,
    TPLinkWR841NClient,
    TplinkRE330Router,
    TplinkC3200Router,
    Connection
)
from logging import Logger
import traceback

# Prefer the provider: it picks a matching client for your router
router = TplinkRouterProvider.get_client('http://192.168.0.1', 'password')
logger = Logger('test')
# You may use a client class directly, e.g.:
# router = TplinkRouter('http://192.168.0.1', 'password')
# You may also pass username if it is different and a logger to log errors as
# router = TplinkRouter('http://192.168.0.1', 'password', 'admin2', logger=logger)
# C5400X / similar: use web encrypted password (see Web Encrypted Password below)
# router = TplinkC5400XRouter('http://192.168.0.1', 'WebEncryptedPassword', logger=logger)

try:
    # Or: with router:  # authorize on enter, logout on exit
    router.authorize()
    # Get firmware info - returns Firmware
    firmware = router.get_firmware()

    # Get status info - returns Status
    status = router.get_status()
    if not status.guest_2g_enable:  # check if guest 2.4G wifi is disable
        router.set_wifi(Connection.GUEST_2G, True)  # turn on guest 2.4G wifi

    # Get IPv6 status (not implemented on every client → NotImplementedError)
    try:
        ipv6_status = router.get_ipv6_status()
        print(ipv6_status.wan_ipv6_addr, ipv6_status.wan_ipv6_gateway)
    except NotImplementedError:
        pass

    # Optional methods (not on every client)
    try:
        reservations = router.get_ipv4_reservations()
        reservations.sort(key=lambda a: a.ipaddr)
        for res in reservations:
            print(f"{res.macaddr} {res.ipaddr:16s} {res.hostname:36} {'Permanent':12}")
    except (AttributeError, NotImplementedError):
        pass

    try:
        leases = router.get_ipv4_dhcp_leases()
        leases.sort(key=lambda a: a.ipaddr)
        for lease in leases:
            print(f"{lease.macaddr} {lease.ipaddr:16s} {lease.hostname:36} {lease.lease_time:12}")
    except (AttributeError, NotImplementedError):
        pass

    router.logout()  # always logout; TP-Link Web Interface only supports up to 1 user logged in
except Exception as e:
    logger.error(traceback.format_exc())

The TP-Link Web Interface only supports up to 1 user logged in at a time (for security reasons, apparently). So before action you need to authorize and after logout. You can also use with router: (calls authorize() / logout() automatically).

If you got exception - use web encrypted password instead. Check the documentation! or you have TP-link C5400X or similar router you need to get web encrypted password by these actions:

  1. Go to the login page of your router. (default: 192.168.0.1).
  2. Type in the password you use to login into the password field.
  3. Click somewhere else on the page so that the password field is not selected anymore.
  4. Open the JavaScript console of your browser (usually by pressing F12 and then clicking on "Console").
  5. Type document.getElementById("login-password").value;
  6. Copy the returned value as password and use it.

Functions

Not every method is available on every client. Methods below get_ipv6_status that are model-specific (reservations, VPN client, SMS/LTE, …) raise AttributeError / NotImplementedError or are simply missing on unsupported routers.

Function Args Description Return
get_firmware Gets firmware info about the router Firmware
get_status Gets status about the router info including wifi statuses and connected devices info Status
get_ipv4_status Gets WAN and LAN IPv4 status info, gateway, DNS, netmask IPv4Status
get_ipv6_status Gets WAN IPv6 status info, gateway, DNS, site prefix (c6u/SG, MR/EX/VR, C80-style; others raise NotImplementedError) IPv6Status
get_ipv4_reservations Gets IPv4 reserved addresses (static) [IPv4Reservation]
add_ipv4_reservation macaddr: str, ipaddr: str, comment: str = '', enable: bool = True Adds an IPv4 DHCP address reservation
get_ipv4_dhcp_leases Gets IPv4 addresses assigned via DHCP [IPv4DHCPLease]
set_ipv4_dhcps enable: bool Turn the LAN IPv4 DHCP server on or off
set_wifi wifi: Connection, enable: bool Turn on/off host, guest, or IoT wifi bands
reboot reboot router
authorize authorize for actions
logout logout after all is done
get_vpn_status Gets VPN info for OpenVPN and PPTPVPN and connected clients amount VPNStatus
set_vpn vpn: VPN, enable: bool Turn on/off VPN
get_vpn_client_status Gets VPN client status including enabled state, configured servers, and whitelisted devices VpnClientStatus
set_vpn_client enable: bool Turn VPN client on or off
set_vpn_client_server server_id: str, enable: bool Toggle a VPN server on or off; the router handles deactivating all others when one is enabled
set_vpn_client_device mac: str, enable: bool Enable or disable VPN client access for a device by MAC address
send_sms phone_number: str, message: str Send sms for LTE routers
send_ussd command: str Send USSD command for LTE routers str
get_sms Get sms messages from the first page for LTE routers [SMS]
set_sms_read sms: SMS Set sms message read from the first page for LTE routers
delete_sms sms: SMS Delete sms message from the first page for LTE routers
get_lte_status Get lte info for LTE routers LTEStatus
get_lte_serving_cells Get serving cells info for EX series routers [ServingCell]
get_wifi wifi: Connection Get wifi info WifiStatus

Dataclass

Field Description Type
hardware_version Returns like - Archer C6U str
model Returns like - Archer C6U v1.0 str
firmware_version Returns like - 1.1.3 Build 3425243 str
Field Description Type
wan_macaddr router wan mac address str, None
wan_macaddress router wan mac address macaddress.EUI48, None
lan_macaddr router lan mac address str, None
lan_macaddress router lan mac address macaddress.EUI48, None
wan_ipv4_addr router wan ipv4 address str, None
wan_ipv4_address router wan ipv4 address ipaddress.IPv4Address, None
lan_ipv4_addr router lan ipv4 address str, None
lan_ipv4_address router lan ipv4 address ipaddress.IPv4Address, None
wan_ipv4_gateway router wan ipv4 gateway str, None
wan_ipv4_gateway_address router wan ipv4 gateway address ipaddress.IPv4Address, None
wan_ipv6_enabled Is WAN IPv6 enabled bool, None
wan_ipv6_addr router wan ipv6 address str, None
lan_ipv4_dhcp_enable Is LAN IPv4 DHCP server enabled bool, None
wired_total Total amount of wired clients int
wifi_clients_total Total amount of host wifi clients int
guest_clients_total Total amount of guest wifi clients int
clients_total Total amount of all connected clients int
iot_clients_total Total amount of all iot connected clients int, None
guest_2g_enable Is guest wifi 2.4G enabled bool, None
guest_5g_enable Is guest wifi 5G enabled bool, None
guest_6g_enable Is guest wifi 6G enabled bool, None
iot_2g_enable Is IoT wifi 2.4G enabled bool, None
iot_5g_enable Is IoT wifi 5G enabled bool, None
iot_6g_enable Is IoT wifi 6G enabled bool, None
wifi_2g_enable Is host wifi 2.4G enabled bool, None
wifi_5g_enable Is host wifi 5G enabled bool, None
wifi_6g_enable Is host wifi 6G enabled bool, None
wan_ipv4_uptime Internet Uptime int, None
mem_usage Memory usage in percentage between 0 and 1 float, None
cpu_usage CPU usage in percentage between 0 and 1 float, None
conn_type Connection type str, None
devices List of all connected devices list[Device]
Field Description Type
type client connection type (2.4G or 5G, guest wifi or host wifi, wired) Connection
macaddr client mac address str
macaddress client mac address macaddress
ipaddr client ip address str
ipaddress client ip address ipaddress
hostname client hostname str
packets_sent total packets sent int, None
packets_received total packets received int, None
down_speed download speed int, None
up_speed upload speed int, None
tx_rate transmit rate (Mbps) int, None
rx_rate receive rate (Mbps) int, None
online_time client online time (seconds) float, None
traffic_usage total traffic usage (bytes) int, None
signal Signal strength int, None
active Is active device bool
ap_name ap_name str
ssid ssid str
frequency frequency str
Field Description Type
macaddr client mac address str
macaddress client mac address macaddress
ipaddr client ip address str
ipaddress client ip address ipaddress
hostname client hostname str
enabled enabled bool
Field Description Type
macaddr client mac address str
macaddress client mac address macaddress
ipaddr client ip address str
ipaddress client ip address ipaddress
hostname client hostname str
lease_time ip address lease time str
Field Description Type
wan_macaddr router WAN mac address str, None
wan_macaddress router WAN mac address macaddress.EUI48, None
wan_ipv4_ipaddr router WAN IPv4 address str, None
wan_ipv4_ipaddress router WAN IPv4 address ipaddress.IPv4Address, None
wan_ipv4_gateway router WAN gateway IP address str, None
wan_ipv4_gateway_address router WAN gateway IP address ipaddress.IPv4Address, None
wan_ipv4_conntype router connection type str
wan_ipv4_netmask router WAN IP netmask str, None
wan_ipv4_netmask_address router WAN IP netmask ipaddress.IPv4Address, None
wan_ipv4_pridns router primary dns server str, None
wan_ipv4_pridns_address router primary dns server ipaddress.IPv4Address, None
wan_ipv4_snddns router secondary dns server str, None
wan_ipv4_snddns_address router secondary dns server ipaddress.IPv4Address, None
lan_macaddr router LAN mac address str, None
lan_macaddress router LAN mac address macaddress.EUI48, None
lan_ipv4_ipaddr router LAN IP address str, None
lan_ipv4_ipaddress router LAN IP address ipaddress.IPv4Address, None
lan_ipv4_dhcp_enable router LAN DHCP enabled bool
lan_ipv4_netmask router LAN IP netmask str, None
lan_ipv4_netmask_address router LAN IP netmask ipaddress.IPv4Address, None
remote router remote bool, None
Field Description Type
wan_ipv6_enabled Is WAN IPv6 enabled bool, None
wan_ipv6_conn_status WAN IPv6 connection status (e.g. Connected, Disabled) str, None
wan_ipv6_conntype WAN IPv6 connection type str, None
wan_ipv6_addr_type WAN IPv6 address acquisition type (e.g. DHCPv6) str, None
wan_ipv6_addr router WAN IPv6 address str, None
wan_ipv6_gateway router WAN IPv6 gateway str, None
wan_ipv6_pridns router primary IPv6 DNS server (unlike IPv4, returns address object, not str) ipaddress.IPv6Address, None
wan_ipv6_snddns router secondary IPv6 DNS server (unlike IPv4, returns address object, not str) ipaddress.IPv6Address, None
ipv6_site_prefix IPv6 site prefix str, None
ipv6_site_prefix_length IPv6 site prefix length str, None

Not all fields are filled by every client:

  • c6u / SG / C5400X / C1200: wan_ipv6_enabled, wan_ipv6_conntype, wan_ipv6_addr, wan_ipv6_gateway, wan_ipv6_pridns, wan_ipv6_snddns, wan_ipv6_conn_status, ipv6_site_prefix
  • MR / EX / VR / MR200 / C50 / WR841 / C3200: wan_ipv6_enabled, wan_ipv6_conn_status, wan_ipv6_addr_type, wan_ipv6_conntype, wan_ipv6_addr, wan_ipv6_gateway, wan_ipv6_pridns, wan_ipv6_snddns, ipv6_site_prefix, ipv6_site_prefix_length
  • C80: wan_ipv6_enabled, wan_ipv6_conn_status, wan_ipv6_addr_type, wan_ipv6_addr, wan_ipv6_gateway, wan_ipv6_pridns, wan_ipv6_snddns, ipv6_site_prefix, ipv6_site_prefix_length
Field Description Type
openvpn_enable OpenVPN is enabled bool
pptpvpn_enable PPTPVPN is enabled bool
ipsecvpn_enable IPSEC is enabled bool
openvpn_clients_total OpenVPN clients connected int
pptpvpn_clients_total PPTPVPN clients connected int
Field Description Type
enabled VPN client is enabled bool
servers Configured VPN client servers [VpnClientServer]
devices Devices in the VPN client whitelist [VpnClientDevice]
Field Description Type
id Server identifier str
name Server display name str
protocol VPN protocol VpnClientServerProtocol
active Is this server currently active bool
status Connection status string from router (e.g. "connected") str, None
Field Description Type
macaddr device mac address str
macaddress device mac address EUI48
name device hostname str
enabled Is device routed through VPN client bool
Field Description Type
id message index int
sender sender str
content sms text str
received_at received datetime datetime
unread is message unread bool
Field Description Type
enable is enabled int
connect_status connect status int
network_type network type int
network_type_info Example: 4G LTE str
sim_status sim status int
sim_status_info Example: SIM locked. str
total_statistics total statistics in bytes int
cur_rx_speed current download speed in bytes per second int
cur_tx_speed current upload speed in bytes per second int
sms_unread_count sms unread amount int
sig_level signal level int
rsrp RSRP int
rsrq RSRQ int
snr SNR int
isp_name ISP name str
network_types All possible network types - {0: "No Service", 1: "GSM", 2: "WCDMA", 3: "4G LTE", 4: "TD-SCDMA", 5: "CDMA 1x", 6: "CDMA 1x Ev-Do", 7: "4G+ LTE", 8: "5G NR"} dict
sim_statuses All possible sim statuses - {0: "No SIM card detected or SIM card error.", 1: "No SIM card detected.", 2: "SIM card error.", 3: "SIM card prepared.", 4: "SIM locked.", 5: "SIM unlocked. Authentication succeeded.", 6: "PIN locked.", 7: "SIM card is locked permanently.", 8: "suspension of transmission", 9: "Unopened"} dict
Field Description Type
network_type network type int
band band number int
arfcn absolute radio frequency channel number int
downlink_bandwidth MHz int
downlink_frequency MHz int
downlink_modulation Downlink modulation scheme str
uplink_modulation Uplink modulation scheme str
cqi Channel quality indicator int
ri Rank indicator int
resource_blocks Number of resource blocks allocated in the NR cell int
rsrp dBm int
rsrq dBm int
Field Description Type
enable enable bool
ssid ssid str
hidden hidden bool
encryption encryption str
psk_key psk_key str
portal_enable portal_enable bool
portal_password portal_password str
channel channel int

Enum

  • Connection.HOST_2G - host wifi 2.4G
  • Connection.HOST_5G - host wifi 5G
  • Connection.HOST_6G - host wifi 6G
  • Connection.GUEST_2G - guest wifi 2.4G
  • Connection.GUEST_5G - guest wifi 5G
  • Connection.GUEST_6G - guest wifi 6G
  • Connection.IOT_2G - IoT wifi 2.4G
  • Connection.IOT_5G - IoT wifi 5G
  • Connection.IOT_6G - IoT wifi 6G
  • Connection.WIRED - Wired
  • Connection.UNKNOWN - Unknown connection type
  • VPN.OPEN_VPN
  • VPN.PPTP_VPN
  • VPN.IPSEC
  • VpnClientServerProtocol.OPEN_VPN
  • VpnClientServerProtocol.PPTP
  • VpnClientServerProtocol.L2TP_IPSEC
  • Archer A10 v1
  • Archer A20 v1.0
  • Archer A6 (2.0, 4.0)
  • Archer A7 V5
  • Archer A8 (1.0, 2.20)
  • Archer A9 V6
  • Archer AX10 v1.0
  • Archer AX11000 V1
  • Archer AX12 v1.0
  • Archer AX17 v1.0
  • Archer AX1800
  • Archer AX20 (v1.0, v3.0)
  • Archer AX21 (v1.20, v3.0, v4.6)
  • Archer AX23 (v1.0, v1.2)
  • Archer AX3000 V1
  • Archer AX50 v1.0
  • Archer AX53 (v1.0, v2)
  • Archer AX55 (v1.0, V1.60, v4.0)
  • Archer AX58 v1.0
  • Archer AX6000 V1
  • Archer AX72 V1
  • Archer AX73 (V1, V2.0)
  • Archer AX75 V1
  • Archer AX90 V1.20
  • Archer AX95 v1.0
  • Archer AXE16000
  • Archer AXE5400 v1.0
  • Archer AXE75 V1
  • Archer BE220 v1.0
  • Archer BE230 (v1.0, v2.0)
  • Archer BE3600 (v1.0, v1.2, v1.6)
  • Archer BE400 v1.0
  • Archer BE550 (v1.0, V2)
  • Archer BE800 v1.0
  • Archer BE805 (v1.0, v1.20)
  • Archer C1200 (v1.0, v2.0)
  • Archer C2300 (v1.0, v2.0)
  • Archer C24 (1.0, 2.0)
  • Archer C3200 v1
  • Archer C5400X V1
  • Archer C6 (v2.0, v3.0, v3.20, 4.0)
  • Archer C50 v4
  • Archer C60 v2.0
  • Archer C64 1.0
  • Archer C6U v1.0
  • Archer C7 (v4.0, v5.0)
  • Archer C80 (1.0, 2.20)
  • Archer GX90 v1.0
  • Archer MR200 (v2, v5, v5.3, v6.0)
  • Archer MR400 V.4.3
  • Archer MR550 v1
  • Archer MR600 (v1, v2, v3)
  • Archer NX200 (v1.0, v2.0)
  • Archer VR1200v (v1, v2)
  • Archer VR2100v v1
  • Archer VR2800 v1
  • Archer VR400 (v2, v3)
  • Archer VR600 v3
  • Archer VR900v
  • Archer VX1800v v1.0
  • Archer VX231v v1.0
  • BE11000 2.0
  • CPE210 v2.0
  • CPE220 v3.0
  • Deco BE25 1.0
  • Deco E4R 4.0
  • Deco M4 2.0
  • Deco M4R 2.0
  • Deco M5 v3
  • Deco M9 Plus 1.0
  • Deco M9 Pro
  • Deco P7
  • Deco X20
  • Deco X50 v1.3
  • Deco X50-5G (1.20, 2.0)
  • Deco X55 1.0
  • Deco X60 V3
  • Deco X90
  • Deco XE75 (v1.0, v2.0)
  • Deco XE75PRO (v3.0)
  • EAP115 v2.0
  • EX511 v2.0
  • HB810 v2.6
  • HX510 v1.0
  • M8550 v1
  • NE200-Outdoor v1.0
  • NE211-Outdoor v1.0
  • NX510v v1.0
  • NX600 v2.0
  • RE305 4.0
  • RE315 1.0
  • RE330 v1
  • TD-W9960 (v1, V1.20)
  • TL-7DR6430 1.0
  • TL-7DR7270 1.0 (firmware 1.0.18+, new auth)
  • TL-MR100 (v2.0, v3.0)
  • TL-MR100-Outdoor v1.0
  • TL-MR105
  • TL-MR110-Outdoor v1.0
  • TL-MR150 v2
  • TL-MR6400 (v5, v5.3, v7)
  • TL-MR6500v
  • TL-R470GP-AC 4.0
  • TL-R488GPM-AC 2.0
  • TL-SG108E v6.0
  • TL-WA1201 3.0
  • TL-WA3001 v1.0
  • TL-WR841N v14
  • TL-WR844N v1.0
  • TL-WR3002X v1.0
  • TL-WDR3600 V1
  • TL-XDR3010 V2
  • TL-XDR5410 1.0
  • TL-XDR6088 v1.0.30
  • VX420-G2h v1.1
  • VX800v v1
  • XC220-G3v v2.30
  • AC10 1.20
  • Halo H25BE 1.0
  • Halo H3000x 1.0
  • Halo H47BE 2.0
  • Halo H60XR 1.0
  • Halo H80X 1.0
  • ME30 1.0
  • MR47BE v1.0
  • MR50G 1.0
  • MR80X v2.0

Please let me know if you have tested integration with any other model. Open an issue with info about router's model, hardware and firmware versions.

Guidelines CONTRIBUTING.md

Local Development

  • Download this repository.
  • Run pip install -e path/to/repo.
  • Make changes to files within the tplinkrouterc6u directory.
  • Exercise the changes following the "Usage" section above.

The sanity check test.py illustrates a few tests and runs through a list of queries in queries.txt creating logs of the results of each query in the logs folder. This can be used to capture the dictionary output of all cgi-bin form submissions.

Run tests

  • Run python -m unittest discover ./test

Thanks To

About

Python package for API access and management for TP-Link and Mercusys Routers. See supported routers list

Topics

Resources

Contributing

Stars

184 stars

Watchers

4 watching

Forks

Releases

Used by

Contributors

Languages