A basic React UI for the formulas defined in Semtech's LoRa Modem Designer's Guide (AN1200.13), showing the airtime for data rates as used in the frequency plans of The Things Network (TTN), and showing the limitations that apply to the TTN public network.
See it in action on https://avbentem.github.io/airtime-calculator.
Next versions may include:
The frequency plans from which the data rates are shown, are those of The Things Network. They are based on the frequency plans and the LoRaWAN Regional Parameters v1.0.2rB, and defined in config.json.
Some frequency plans have very different data rates for uplinks and downlinks; for those distinct "regions" are defined in this application, like for US902 (uplink) and US902 DL (downlink). Others share (most) of the data rates, like EU868.
Both countries and the LoRaWAN specifications may define maximum duty cycle or maximum dwell time limitations: when some frequency plan can be used in several countries, different countries may still impose different legal limitations. And:
It's important to keep in mind that the duty cycle limitations described in the tables of the specifications are LoRaWAN-imposed limitations, and not legal limitations. If you build commercial devices and want them to be LoRaWAN certified, they need to comply with the specification. Development devices don't have to be fully compliant with the specification. Any device (whether LoRaWAN or not, gateway or node, commercial or development) needs to be compliant with the legal limitations that apply in your country.
[...]
The LoRaWAN-imposed duty cycle applies to nodes only. Gateways are technically just LoRa devices, not LoRaWAN, so the LoRaWAN specification doesn’t apply to them. The regulatory duty cycle limitations typically apply to any transmitter.
Like for AS923:
The LoRaWAN 1% maximum duty cycle only applies to 923.20 and 923.40 MHz.
The 400 ms maximum dwell time may not apply for Australia.
The LoRaWAN specification(s) defines multiple options for the maximum payload size, like depending on dwell time settings, and with or without support for a possible repeater encapsulation.
In the early specifications, these choices are quite confusing as often smaller maximum values are listed when no maximum dwell times apply. However, the February 2020 LoRaWAN Regional Parameters RP002-1.0.1 states that no MACPayload may be larger than 230 bytes, regardless of dwell time limitations, and in that version the numbers have been adjusted as well.
This calculator uses the maximum payload sizes from RP002-1.0.1, which allow for a possible repeater encapsulation and do not take maximum dwell times into account. If the device will never operate under a repeater then the maximum size could be a bit larger. If dwell times have been defined then those will generate warnings in the calculator regardless the maximum payload size, allowing users to whom those dwell times do not apply to still see the correct (higher) maximum payload sizes.
Changing the payload size does not always affect the number of symbols that make up the LoRa packet payload and header, or not for all data rates. For example, this is very visible for application payload sizes of 12 versus 13 bytes. This is the expected outcome, caused by the LoRa radio modulation, interleaving and forward error correction. The graph below the grid visualizes this.
Semtech's LoRa Modem Designer's Guide (AN1200.13) defines some more parameters, especially preamble length (to detect the signal), coding rate (CR, for forward error correction), header mode (to include a LoRa header with details such as coding rate, payload length and CRC), and low data rate optimisation mode (to avoid issues with drift of the crystal reference oscillator due to either temperature change or motion). For LoRaWAN, these are not configurable, so are not exposed as a user input (except for CR, if a non-default value is set through the URL).
For LoRaWAN, the preamble length is always 8, CR is always 4/5, the LoRa-level header is always included, and low data rate optimisation mode is active for SF11 and SF12 on 125 kHz.
The browser's copy event is mapped as follows:
If any text is selected, copy that. This is handled by the browser.
Otherwise, when a tooltip is active, copy its text. This yields both HTML and plain text formats. On a desktop browser you'll need the keyboard to copy a tooltip.
Or else, copy the results. This only supports HTML.
For the line breaks in the results grid, this uses a format that is very specific to the automatic
conversion from HTML to Markdown in Discourse, like as used on the TTN Forum: Discourse replaces
<br> with \n but then rejects \n in table cells. As a workaround, <br> is
outputted as <br>, which is handled as expected in Discourse's editor but needs some editing
when pasted elsewhere. Of course, using the static results is not quite useful anyhow.
For text/plain no URL is added, as Discourse prefers the plain text content if
that is longer than the HTML.
This application was created with sharable URLs in mind, so almost every user input yields an updated URL:
/<network>/<region>[/<parameters>], e.g. /ttn/eu868 and /ttn/us902/6,14,cr48.
<parameters> is a comma-separated list, and defines:
cr45, cr46, cr47, cr48LinkAdrReqDefault values are not included in the <parameters> segment; this currently applies to:
cr45: as fixed for LoRaWANWhen all parameters use their defaults, the <parameters> segment and its slash are excluded.
To serve this single-page application from GitHub Pages, some trickery with a JavaScript redirect in a custom 404 page is needed. Unfortunately, some browsers (such as Brave) may try to be helpful and show an option like "Do you want to check if a saved version is available on the Wayback Machine?" even when properly executing the expected redirect. It's unclear why the final 200 OK removes the banner for some sites in Brave, but not for GitHub Pages.
This project was bootstrapped with Create React App.
To use a limited bundle for Plotly (removing about 690 kB from the build), while using the typings
of the full bundle, a paths alias configuration is used in tsconfig.json.
However, during testing or building, Create React App would boldly remove that:
> react-scripts build
The following changes are being made to your tsconfig.json file:
- compilerOptions.paths must not be set (aliased imports are not supported)
...
TypeScript error in /src/components/result/Graph.tsx(1,20):
Could not find a declaration file for module 'plotly.js-basic-dist'To mitigate that, some trickery with extends is used instead. This will still show the same
message for npm test and npm run build, and will even pretty-format the base tsconfig.json,
but in the end it won't touch the extends and use tsconfig-paths.json.
In the project directory, run:
npm install
Downloads all dependencies. You can safely ignore the warnings about missing peer dependencies.
npm start
Runs the app in the development mode. Open http://localhost:3000 to view it in the browser. The page will reload if you make edits. You will also see any lint errors in the console.
npm test
Launches the test runner in the interactive watch mode. See the Create React App documentation on running tests for details.
npm test -- --coverage
Single test run with coverage.
npm run lint, npm run lint:es, npm run lint:style or npm run lint:pretty
Manually run all linters and Prettier, or run only those for code, styleheets, or the remaining files. Unlike the pre-commit hook (see below), this is not limited to staged files.
npm run build
Runs the linters, and (only) if all succeed builds the app with minimized bundles for production
into the build folder.
To ensure URLs like /ttn/eu868/1,2 can be loaded without first loading the bare /, see for
example the Apache .htaccess file.
To build for a subfolder, set "homepage": "/some/path/to/airtime-calculator" in package.json.
This will not affect the development server, which will always load from the root folder. For
deployment in the root folder, set it to "/" or don't set it at all. See also the Create React
App documentation about deployment.
A pre-commit hook ensures that linting errors and formatting errors cannot be committed. To allow Prettier rules to supersede any formatting rules that might be defined by a linter, it is configured to run as a plugin for both ESLint and stylelint, and to explicitly run for the few file types not handled by either of those.
Note that the pre-commit hook uses lint-staged, which temporarily hides unstaged changes to partially staged files. This may make your IDE show warnings about files that were changed outside of the IDE.
Beware that Sourcetree might silently skip the pre-commit hook.
Enable Stylelint in Languages and Frameworks | Style Sheets | Stylelint, and optionally disable
the standard inspections in Editor | Inspections | CSS. (For example, WebStorm does not like
@import-normalize; in App.scss, but using // noinspection CssInvalidAtRule
already suppresses that specific inspection in this code.)
The Prettier settings in .prettierrc.yaml define trailingComma: es5. After
being prompted "Use code style based in Prettier for this project?" in WebStorm, this will yield
Coding Style | Punctuation | Trailing comma: Add when multiline. Unfortunately this also applies
to function parameters, which adds an excessive comma when hitting Option-Command-L for Reformat
Code (but not for Option-Shift-Command-P for Reformat with Prettier). To avoid that, manually set
WebStorm to use Trailing comma: Keep.
The editor settings in .editorconfig define max_line_length, which is used
when hitting Option-Command-L for Reformat Code, but not when using Option-Shift-Command-P for
Reformat with Prettier.