Contextual help tooltips for form fields

[kschiffer]

Summary

As a next step from #2663 and as defined in #3522 we will introduce contextual tooltips for many fields in our forms.

Why do we need this?

To assist and educate users when onboarding entities. See also #3785.

What is already there? What do you see now?

• Content provided by @benolayinka
• Wireframes in New end device registration flow (Console) #3522
• New form UX guidelines of Improve form UX #2813

What is missing? What do you want to see?

• Implement tooltip logic (likely via external module)
• Add tooltip content
• Remove field descriptions that would only repeat tooltip info (should be most of them; more info in Improve form UX #2813)

How do you propose to implement this?

We should make use of a well-tested and production ready react tooltip library. The library should support

• Full styling control
• Toggling via click and hover
• Mobile ready

We will stick with the current icon layout within the field title and only change the functionality to display the tooltip on hover. The link to the glossary will be removed. If necessary the glossary can be referenced inside the tooltip.

Regarding the content, we will not source this from the docs anymore but add the content as intl messages to the Console directly. This module should be co-owned by @benolayinka.

How do you propose to test this?

We can add simple integration tests for this.

Can you do this yourself and submit a Pull Request?

@bafonins

[bafonins]

@benolayinka With #4057 merged we are still missing tooltip content for various fields in the Console. Could you take a look at whats missing and provide descriptions for fields without tooltips?

Not closing this issue because we still have to implement proper handling for mobile devices. For mobile devices the tooltip content should be displayed in modal-like view instead of just popover view.

@benolayinka Also update the milestone if required.

[benolayinka]

Tooltips for device creation

Brand
Description
This is the manufacturer of your end device.

Model
Desc
The particular model of your end device.

Hardware Ver.
Desc
The hardware version of your device.
Location
It should be provided by the manufacturer of your device, or printed on the device packaging.
Absence
Contact the manufacturer or reseller of your device.

Firmware Ver.
Desc
The version of firmware loaded on your device.
Location
The firmware version should be provided by the manufacturer of your device, or printed on the device packaging. It may be possible to upgrade your device firmware to a known version.
Absence
Contact the manufacturer or reseller of your device.

Activation Mode
Desc
OTAA is the preferred and most secure way to connect a device. Devices perform a join-procedure with the network. ABP requires hardcoding the device address and security keys. Multicast is a virtual group of ABP devices which allows all devices to receive the same downlinks. Multicast groups do not support uplinks.
Location
You decide how to activate your devices. Whenever possible, use OTAA.
Glossary
#activation-mode

End device ID
Desc
A unique identifier for your end device.
location
You make it up, so be creative!
link
https://www.thethingsindustries.com/docs/reference/id-eui-constraints/

End device name
desc
An optional human readable name to help you identify your device.
location
You make it up, so be creative!

End device description
desc
An optional description, which can also be used to save notes about the end device.

Frame counter width
desc
Most devices use a 32 bit frame counter to prevent replay attacks. Devices with extremely limited resources are permitted to use 16 bit counters.
location
It should be provided by the device manufacturer.
Absence
Contact your manufacturer or reseller. Most devices use 32 bit counters. Selecting the wrong value will produce errors once the Up or Down frame counter exceeds 16 bits and rolls over.

RX2 Data Rate Index
desc
The data rate used for the RX2 receive window.
location
This should be provided by the device manufacturer. It will also automatically configured by the network for OTAA devices.
absence
Contact your device manufacturer or reseller. For OTAA, this does not need to be manually set and can be ignored.

RX2 Frequency
desc
The frequency used for the RX2 receive window.
location
This should be provided by the device manufacturer. It will also automatically configured by the network for OTAA devices.
absence
Contact your device manufacturer or reseller. For OTAA, this does not need to be manually set and can be ignored.

[benolayinka]

Gateway ID
Desc
A unique identifier for your gateway.
location
You make it up, so be creative!
link
https://www.thethingsindustries.com/docs/reference/id-eui-constraints/

Gateway EUI
Desc
A 64 bit extended unique identifier for your end device.
location
It should be provided to you by the manufacturer, or printed on the gateway packaging.
absence
Contact the manufacturer or reseller.
link
https://www.thethingsindustries.com/docs/reference/id-eui-constraints/

Gateway name
desc
An optional human readable name to help you identify your gateway.
location
You make it up, so be creative!

Gateway description
desc
An optional description, which can also be used to save notes about the gateway.

Require authenticated connection
desc
This will only allow a gateway to connect if it uses a TLS enabled Basic Station or MQTT connection. It will not allow connections from UDP packet forwarders.

Gateway Status
description
This allows information about the gateway to be shared publicly - the location, for example, to display on maps of publicly available LoRaWAN gateways.

Attributes
Desc
Attributes can be used to set arbitrary information about the entity, to be used by scripts, or simply for your own organization.

Frequency Plan
A Frequency Plan defines data rates and channels which comply with the LoRaWAN Regional Parameters for a band or geographical area.
Location
You need to choose a Frequency Plan which adheres to the local regulations of where your gateway is located. It is also important that the end devices in reach of gateway use the same Frequency Plan.
Glossary
#frequency-plan

Schedule downlink late
Description
This legacy feature enables buffering of downlink messages on the network server, for gateways with no downlink queue. Scheduling consecutive downlinks on gateways with no queue will cause only the most recent downlink to be stored.

Duty Cycle (Should be "enforce duty cycle", with enabled checked)
Description
When checked, the Network Server will only schedule messages respecting the duty cycle limitations of the selected frequency plan.

Schedule anytime delay
Description
Adjust the time that the Network Server schedules class C messages in advance. This is useful for gateways that have a known high latency backhaul, like 3G and satellite.

[kschiffer]

Assigned @asmulko to add the new tooltip content provided by @benolayinka.