Configuration Schema

The configuration is a JSON formatted that contains information about your HotSpot backend connection settings, printer configuration and plans that you want to be able to generate.

Main Sections

Bellow is a structure of the configuration file.

{
  "backend": {},
  "printer": {},
  "share": true,
  "show_config": true,
  "style": {
    "theme": null,
    "dark_mode": null
  },
  "plans": []
}
  • backend - see Backend Connection Settings
  • printer - see Printer Configuration
  • share - boolean, if set to true the app will show share button on voucher screen
  • show_config - boolean, if set to false, user won't be able to see configuration page - the only method to change configuration will be resetting the app and entering new configuration
  • style - Style configuration
    • theme - string or null, one of null, ios, material - when null the app will use default theme for the platform
    • dark_mode - boolean or null - when null the app will automatically switch to dark mode when system is in dark mode (iOS and Web only)
  • plans - array of Plan Configuration

Backend Connection Settings

At this moment the app supports two backends - UniFi and Demo.

Demo Backend

You can use demo backend to test the app or printer integration without need to have UniFi controller running. Vouchers generated with demo backend will be randomly generated and will not be valid.

{
  "backend": {
    "type": "demo",
    "config": {}
  }
}

It doesn't have any configuration options.

UniFi Backend

This connector doesn't require any additional software to be installed on your UniFi controller, nor any proxy server. It uses UniFi API to generate vouchers. It is compatible with standalone UniFi controllers or running on UniFi Dream Machine.

{
  "backend": {
    "type": "unifi",
    "config": {
      "site": "default",
      "host": "192.168.1.1",
      "port": 443,
      "username": "generator",
      "password": "P@ssw0rd",
      "https": true,
      "udm": true,
      "verify_ssl": false
    }
  }
}
  • site - string, UniFi site name (default for UniFi Dream Machine
  • host - string, UniFi controller hostname or IP address
  • port - integer, UniFi controller port
  • username - string, UniFi controller username
  • password - string, UniFi controller password
  • https - boolean, if set to true the app will use HTTPS to connect to UniFi controller
  • udm - boolean, if set to true the app will adjust API calls for UniFi Dream Machine
  • verify_ssl - boolean, if set to true the app will verify SSL certificate of UniFi controller, disable when using self-signed certificate

Printer Configuration

At this moment the app supports 4 types of printers - Disabled, Sunmi, Bluetooth SPP and Bluetooth BLE.

Printing Disabled

If you don't want to use printer, you can disable it by setting type to disabled.

{
  "printer":{
    "type":"disabled",
    "config":{}
  }
}

It doesn't have any configuration options.

Sunmi Printer

If you have compatible Sunmi device with built-in printer, you can use it to print vouchers. This driver is only supported on Sunmi devices.

{
  "printer":{
    "type": "sunmi",
    "config": {
      "wifi_name": "My HotSpot SSID",
      "template": "default",
      "label_template": "default",
      "autoprint": false
    }
  }
}
  • wifi_name - string, SSID of the Wi-Fi network that will be printed on the voucher
  • template - string, base64 encoded template that will be used to print vouchers - set to default to use built-in template
  • label_template - string, base64 encoded template that will be used to print labels, when your printer is configured in label mode - set to default to use built-in template
  • autoprint - boolean, when set to true the app will automatically print voucher or label after generating it

Bluetooth SPP Printer

When you have Bluetooth printer which supports Serial Port Profile (SPP), you can use it to print vouchers. This driver is only supported on Android devices.

{
  "printer":{
    "type": "bluetooth",
    "config": {
      "address": "00:11:22:33:44:55",
      "wifi_name": "My HotSpot SSID",
      "template": "default",
      "autoprint": false
    }
  }
}
  • address - string, MAC address of the printer
  • wifi_name - string, SSID of the Wi-Fi network that will be printed on the voucher
  • template - string, base64 encoded template that will be used to print vouchers - set to default to use built-in template
  • autoprint - boolean, when set to true the app will automatically print voucher after generating it

Bluetooth BLE Printer

When you have Bluetooth printer which supports Bluetooth Low Energy (BLE) serial port service, you can use it to print vouchers. This method is supported on Android, iOS and partially (due to limited Web USB implementation within internet browsers) in Web app.

{
  "printer": {
    "type": "ble",
    "config": {
      "deviceId": null,
      "wifi_name": "My HotSpot SSID",
      "template": "default",
      "filtered": true,
      "autoprint": false
    }
  }
}
  • deviceId - string, ID of the printer (MAC address on Android, UUID on iOS and browser specific on Web), when set to null the app will show list of available printers when first used and let you choose one - selected printer will be remembered for future uses
  • wifi_name - string, SSID of the Wi-Fi network that will be printed on the voucher
  • template - string, base64 encoded template that will be used to print vouchers - set to default to use built-in template
  • filtered - boolean, when set to true the app will only show printers that advertise serial port service
  • autoprint - boolean, when set to true the app will automatically print voucher after generating it

WebPrint Backend

If you have installed WebPrint server, you can use printers connected to it to print vouchers.

{
  "printer":{
    "type": "webprint",
    "config": {
      "endpoint": "http://example.com/api/web-print",
      "token": "CLIENT_TOKEN",
      "printer": "PRINTER_ULID",
      "type": "escpos",
      "wifi_name": "My HotSpot SSID",
      "template": "default",
      "autoprint": false
    }
  }
}
  • endpoint - string, URL of the WebPrint server
  • token - string, client token for WebPrint server
  • printer - string, ULID of the printer or empty string to use first available printer of type described in type parameter
  • type - string, type of the printer configured in WebPrint server
  • wifi_name - string, SSID of the Wi-Fi network that will be printed on the voucher
  • template - string, base64 encoded template that will be used to print vouchers - set to default to use built-in template
  • autoprint - boolean, when set to true the app will automatically print voucher after generating it

If you don't want to use built-in templates, you can create your own. You can pass base64 encoded template to the app using template or label_template parameter in printer configuration. You can check default templates generation sources for reference.

You can use following placeholders in the template:

  • {{plan.name}} - Plan name
  • {{plan.id}} - Plan ID
  • {{plan.description}} - Plan description
  • {{plan.use_limit}} - Plan use limit
  • {{plan.valid_minutes}} - Plan validity time
  • {{plan.voucher_removed_after}} - Plan voucher removal time
  • {{plan.data_quota}} - Plan data quota
  • {{plan.upload_speed}} - Plan upload speed
  • {{plan.download_speed}} - Plan download speed
  • {{code}} - Voucher code
  • {{expires}} - Voucher expiration date
  • {{id}} - Voucher ID
  • {{wifi}} - Wi-Fi network name

Plan Configuration

You can configure plans that will be available in the app by editing plans array.

{
  "plans": [
    {
      "Id": "basic-net",
      "Description": "6h 5Gb 10Mbit 8h-expire",
      "Name": "Basic.NET",
      "UseLimit": 1,
      "ValidMinutes": 360,
      "VoucherRemovedAfter": 480,
      "DataQuota": 5120,
      "UploadSpeed": 2048,
      "DownloadSpeed": 10240
    }
  ]
}
  • Id - string, unique ID of the plan
  • Description - string, description of the plan
  • Name - string, name of the plan
  • UseLimit - number, number of devices the plan can be used
  • ValidMinutes - number, number of minutes the voucher is valid
  • VoucherRemovedAfter - number, number of minutes after the voucher should be recycled
  • DataQuota - number, data quota in MB
  • UploadSpeed - number, upload speed in Kbit/s
  • DownloadSpeed - number, download speed in Kbit/s

Default Plans

For my own use I have prepared a set of default plans that you can use as a starting point for your configuration.

{
  "plans": [
    {
      "Id": "ondemand-net",
      "Description": "2h 1Gb 5Mbit 6h-expire",
      "Name": "OnDemand.NET",
      "UseLimit": 1,
      "ValidMinutes": 120,
      "VoucherRemovedAfter": 360,
      "DataQuota": 1024,
      "UploadSpeed": 1024,
      "DownloadSpeed": 5120
    },
    {
      "Id": "event-net",
      "Description": "8h 10Gb 10Mbit 10Devices 12h-expire",
      "Name": "Event.NET",
      "UseLimit": 10,
      "ValidMinutes": 480,
      "VoucherRemovedAfter": 720,
      "DataQuota": 10240,
      "UploadSpeed": 2048,
      "DownloadSpeed": 10240
    },
    {
      "Id": "simple-net",
      "Description": "1h 1Gb 5Mbits 3h-expire",
      "Name": "Simple.NET",
      "UseLimit": 1,
      "ValidMinutes": 60,
      "VoucherRemovedAfter": 180,
      "DataQuota": 1024,
      "UploadSpeed": 1024,
      "DownloadSpeed": 5120
    },
    {
      "Id": "basic-net",
      "Description": "6h 5Gb 10Mbit 8h-expire",
      "Name": "Basic.NET",
      "UseLimit": 1,
      "ValidMinutes": 360,
      "VoucherRemovedAfter": 480,
      "DataQuota": 5120,
      "UploadSpeed": 2048,
      "DownloadSpeed": 10240
    },
    {
      "Id": "standard-net",
      "Description": "12h 10Gb 10Mbps 15h-expire",
      "Name": "Standard.NET",
      "UseLimit": 1,
      "ValidMinutes": 720,
      "VoucherRemovedAfter": 900,
      "DataQuota": 10240,
      "UploadSpeed": 2048,
      "DownloadSpeed": 10240
    },
    {
      "Id": "daily-net",
      "Description": "1d 10Gb 10Mbps 1d-expire",
      "Name": "Daily.NET",
      "UseLimit": 1,
      "ValidMinutes": 1440,
      "VoucherRemovedAfter": 1560,
      "DataQuota": 10240,
      "UploadSpeed": 2048,
      "DownloadSpeed": 10240
    },
    {
      "Id": "premium-net",
      "Description": "1d 25Gb 25Mbps 1d-expire",
      "Name": "Premium.NET",
      "UseLimit": 1,
      "ValidMinutes": 1440,
      "VoucherRemovedAfter": 1560,
      "DataQuota": 25600,
      "UploadSpeed": 25600,
      "DownloadSpeed": 25600
    },
    {
      "Id": "unlimited-net",
      "Description": "31d 100Gb 50Mbit 7d-expire",
      "Name": "Unlimited.NET",
      "UseLimit": 1,
      "ValidMinutes": 44640,
      "VoucherRemovedAfter": 10080,
      "DataQuota": 102400,
      "UploadSpeed": 10240,
      "DownloadSpeed": 51200
    }
  ]
}
Edit this page on GitHub
Table of Contents