Overview

Device Configuration  |  Firmware Upgrade  |  Statistics  |  Other Operations  | Change Log 

API Specs


This article contains general information and some tips regarding the Tachyon RESTful API usage.


Detailed API routes (in OpenAPI/Swagger format) and information regarding available config keys have been moved to our Github page here: Tachyon Networks Public API Docs.


Note: the "Try it now" option will not work from the web browser, but you can copy and paste the generated CURL output and try it from your local terminal.

Building requests


All API requests will be built off of the following base URL format: 

http(s)://<device_ip>:<http_port>/cgi.lua/apiv1/<route>

Where:

  • device_ip is the IP address at at which your device's web configuration UI is accessible

  • http_port is the port on which the local webserver is running. The default is 80 for HTTP, and 443 for HTTPs, but this can be changed via configuration settings.

  • route is the route defined in the API routes section below.


i  Note: The device uses self-signed SSL certificates, so if you wish to use HTTPS, you'll need to choose a client that does not reject self-signed SSL certs.


Authentication & authorization

 

Both the API and the local web interface make use of a cookie-based authentication mechanism reflected in the /login route below.   You will need to fetch an authentication token and include it with any subsequent requests.


Here's an example:

curl -c ./tachyon.cookie -H "Content-type: application/json" -X POST -d '{"username": "root", "password": "admin"}' http://192.168.99.130/cgi.lua/apiv1/login

Response for successful authentication:

{"level":0,"token":"BDFW42LDAAAAAADGHTXPMT6B4VP2I5V4CBYD6MI5DDYQ====","auth":true }

Contents of the tachyon.cookie file:

# Netscape HTTP Cookie File
# https://curl.haxx.se/docs/http-cookies.html
# This file was generated by libcurl! Edit at your own risk.


192.168.99.130    FALSE    /    FALSE    0    token    ATQYHSS7NL2GAKC2HQXAGLV4XZY6NSVZ7GF5ALQ%3D

The value ATQYHSS7NL2GAKC2HQXAGLV4XZY6NSVZ7GF5ALQ%3D is the api_token that you will use in future requests.  This value should be included in the Cookie header.  See below for an example fetching system stats:

curl  -X GET -H "Cookie: api_token=ATQYHSS7NL2GAKC2HQXAGLV4XZY6NSVZ7GF5ALQ%3D" http://192.168.99.130/cgi.lua/apiv1/stats?type=system 

i  Note: Authentication tokens become invalid if inactive for more than 30 minutes, or until the unit is rebooted.


User roles


There are two types or levels of user roles that can be created via the web UI:

  1. Admin (level 0): This role can access and change all settings via the web UI and access all APIv1 routes. For devices that have SSH enabled, the admin user can also access the device over SSH.

  2. Read-only (level 9): This role can fetch system stats, but cannot perform any operations that affect the device.  It can also view the Dashboard page of the web UI.  For devices that have SSH enabled, the guest user can not access the device over SSH.


!   All Tachyon devices ship with a default admin user root/admin, but you should change this default user's password before using your device in production.


Passwords for locsal user accounts


User passwords are formatted in the same manner as a password in a standard Linux /etc/passwd file: 


$HASH_TYPE_ID$SALT$HASH

In order to change a plain-text password into a valid value that can be set in the config, you must use a command or library such as the one shown below in order to generate the password.


Here's an example using the openssl passwd command.  It uses an MD5-based algorithm (ID of 1) as the HASH_TYPE_ID, a SALT made of a random string of up to 16 characters long, and generates a resulting password, including the hash value:


 openssl passwd -1 -salt ydj/osBB admin $1$ydj/osBB$nNVJYoK1VJITbHKFUw1Rf.
  • $1: This is the algorithm ID: MD5 has ID = 1

  • $ydj/osBB: This is the salt.

  • $nNVJYoK1VJITbHKFUw1Rf.: This is the hash.

  • $1$ydj/osBB$nNVJYoK1VJITbHKFUw1Rf.: This is the resulting value that you will set in your configuration JSON.

How to get and set your device's configuration


Make note of the list of available configuration keys for your device.  The list of available keys will differ based on your device's model and firmware version, so select the version that matches to you firmware from the API docs page.  All keys are required unless otherwise noted.  



You can fetch your device's configuration via a simple GET request to the /config route.  


To change your device's configuration, you will POST the full updated config to the /config route. Partial configuration is not supported at this time.


If the dry_run param is set to false, then your device will restart networks settings, or reboot the device, as needed in order to apply the new settings.  This will happen after you receive a response to your request, which will contain information regarding which keys were added, removed, or changed during the update operation, as well as any warnings.


Tips

  • We suggest that you first fetch your device's config, then make changes to it before POSTing the modified config back to the /config route. This will help you make sure you're not missing any required keys or have any other validation issues.

  • If you're unsure that you're setting the correct keys or values, set the dry_run option to true and no changes will be made to the device.  


Note about internal vs public configuration


The device has two configurations - an internal one, and an external/public one.  When you interact with the API, you will be getting and setting the public version of the config.  The internal config is consumed by the system and the web UI, but is not meant to be modified by the end user.  Updating the device's internal configuration is currently not supported. 

Upgrading firmware


Upgrading your device's firmware is a multi-stage process, with the basic steps being:

  1. The device asynchronously downloads the firmware from the user-specified specified URL

  2. The device asynchronously flashes the firmware to the boot bank not currently in use

  3. The device reboots, causing the new firmware to become active


During this process, the device keeps track of the status of the different steps.  This status information is fetchable via a GET request to the /update route.


Here is the process in more detail, with the API routes included:

  1. POST to /login:
    Authenticate using the login route above, and parse out the token from the returned cookie.

  2. PUT device firmware URL to /update:
    Send the device the URL where your firmware is being hosted. This will tell the device to start downloading the firmware, asynchronously.

  3. GET firmware status from /update:
    Poll the device for the firmware file download status. Do not start flashing the firmware until the firmware download step is complete. The response message for this state will have the following format:

    {"status":"SUCCESS","url":"<firmware_file_URL>", "state":"FIRMWARE_DOWNLOAD", "last_changed":1621633518}

  4. POST to /update:
    Tell the device to start asynchronously flashing the recently downloaded firmware file (and if you want to reset to defaults as well). Firmware images are flashed to the alternate bootbank, so this will not affect the normal operation of the device.

  5. GET  /update:
    Poll the device for the firmware flashing status, and wait for the firmware flashing process to complete. While flashing, you'll see a message similar to this one:

    {"status":"IN_PROGRESS","last_changed":1672526537,"state":"FIRMWARE_FLASHING"}

    Do not reboot until the flashing process is complete! 

    The response message once firmware flashing is complete will have the following format:

    {"status":"COMPLETE","last_changed":1621296280,"comment":"Reboot device for the new firmware to become active.","state":"FIRMWARE_FLASHING"}

  6. POST to /reboot:
    Tell the device to reboot in order to switch boot banks and complete the firmware upgrade.

  7. POST to /login:
    Authenticate again after boot up.

  8. GET  /stats?type=system:
    Fetch system version in order to verify the new version is active.


Example Upgrade Utility


There is a python-based bulk firmware upgrade script in the _examples folder of the Tachyon github repo that you can also reference.


Dual Bootbanks


Currently, all Tachyon products have dual bootbanks. If a device fails over to its non-active backup bootbank, it may revert to an older firmware.  Because this may cause problems with driver incompatibility between the AP and STA, you should consider flashing both bootbanks of your device.  This can be done by simply flashing the device two times in a row with your firmware of choice.  


Newer firmwares include the firmware versions of both bootbanks within the system stats output response so that you can confirm the firmwares have been updated successfully. 

Fetching statistics


There are 4 types of stats objects that can be fetched via the API: 


  • System: System information, including version, resources, temperatures, etc.

  • Wireless: Wireless 60 GHz AP and client/peer stats. *(Only applicable for wireless devices).

  • Network: Device IPs, management VLAN and data VLAN information, DNS servers, etc...

  • Ethernet: Ethernet interface stats.  Note: the TNA radio's ethernet ports are part of an internal switch, so it's not obvious which interface stats belong to each physical interface.   Please refer to the private MIB for a more detailed explanation about the TNA device's ethernet port configuration.


Visit the /stats route on the Swagger Specs page for usage examples for your particular device model.  

Other Operations

Speedtest

This operation is only available on TNA-300 series models.


To perform a speedtest between a station and its AP:

  1.  First, POST to the /speedtest route, optionally setting the reverse param to true if you wish to test the RX path instead of TX.

  2. You can then GET the results after a few seconds from the /speedtest route.  This will contain the speed, in Mbps, of the test between the two devices.  See the specs page for example return values.


To perform a speedtest between the AP and a single station:


  1. First, POST to the /speedtest route, optionally setting the reverse param to true if you wish to test the RX path instead of TX, and include the station's wireless mac address in the peer_mac param. The station MAC can be found in the wireless stats or in the dashboard on the Web UI.

  2. You can then GET the results after a few seconds from the /speedtest route.  This will contain the speed, in Mbps, of the test between the two devices.  See the specs page for example return values.


To perform a speedtest between the AP and all stations, you will need to get all wireless peer MACs from the AP's wireless stats, and perform a speed test to them in a serial fashion.


Bridge table


GET the /bridge-table route in order to see a list of MACs in the device's bridge table.   This operation is only available on TNA-300 series models.


Reboot


POST to the /reboot route in order to reboot your device.


PoE Reset 


POST to the /poe_reset to power cycle a port on your TNS-100 switch.  This operation is only available on TNS-100 models.

TNA-300 Series Change Log


Any major changes to the API will be reflected in new parameters or routes to ensure backwards compatibility.


Please refer to the firmware change log to view what changes are available in the API.