Dataentry template background
What is it?
The dataentry template contains the template for so called dataentry pages.
Dataentry pages contain the bare technical facts of routers (and other devices) related to OpenWrt/LEDE, and are the datasource for the Table of hardware.
When a dataentry page is either read or changed, the data contained in it is fed into a sqlite database.
To get the data out of this database, simply create datatables / datalists / tagclouds on a page.
For examples, see template_device, datalist-csv or Dataclouds.
For more information on how this works, see https://www.dokuwiki.org/plugin:data
When to use it?
Do create a new dataentry page IF
- you have the information available that is required for a new dataentry
- the device is not yet listed in the Table of Hardware
- the device has versions with differing hardware, compared to an already existing device in the toh, e.g. v1 = 32MB RAM vs. v2 = 64MB RAM.
When not to use it?
Do not create a new dataentry page IF
- the version number increased, but none of the hardware listed in the dataentry has changed
Usage
Creating new entries
- Create new dataentries only after you have checked that your device is not already in the Table of Hardware
- Make sure you have all information available that is required by the Criteria for adding devices to the ToH
- See below for detailed description and allowed / expected values of each field.
Editing existing entries
On the dataentry pages, which you can find in the Table of Hardware, you can edit the values in two ways:
- Preferred: Special “edit” link below the left corner of the dataentry: You will see a form for easy editing the dataentry.
The form avoids accidentially ruining the dataentry structure and also provides dropdowns for easy filling in some values. - Deprecated: Standard dokuwiki “edit” link on the right or “Edit this page” on the top: You will see the dataentry in wiki language.
You can accidentially ruin the dataentry structure.
See below for detailed description and allowed values of each field.
Example
====== Techdata: D-Link DIR-509 A1 ======
~~HIDEPAGE~~
{{page>meta:infobox:dataentry_topnote&noheader&nofooter&noeditbtn&inline&indent&link}}
/*********************************************************
* >>>>>>>> ! <<<<<<<<
* -------- >>>>>>>> W A R N I N G <<<<<<<<--------
* >>>>>>>> ! <<<<<<<<
*
* If you can read this, YOU ARE DOING IT WRONG.
*
* To edit this page in the only right way, do this:
* 1) Click "Cancel", then
* 2) Edit this page ONLY via the lower LEFT edit button.
*
* In case you disobey to the above: You break it, you pay it.
* Thank you for respecting the rules of this wiki.
*
* --- Your wiki administration
*********************************************************/
===== Dataentry =====
---- dataentry techdata ----
Device Type_devicetype : Travel Router # If 'other' -> request new devicetype @wiki admin
Brand : (EXAMPLE) # ===> Mandatory <===
Model : DIR-509 # ===> Mandatory <===
Versions : A1 # List versions comma separated: v1, v1.1, v1.5, v2, v2.5
FCCID_url : # link-scheme: https://fcc.io/yourFCCid
Availability_availability : Available 2017 #
OWrt Supported Since Rev_hidden : https://dev.openwrt.org/changeset/12345 # https://dev.openwrt.org/changeset/xxxxx
OWrt Supported Since Rel_hidden : 14.07 # First official release (i.e. not trunk)
OWrt Supported Current Rel_hidden : 15.05.1 # Current official release (i.e. not trunk)
OWrt Unsupported_hidden : # e.g. '5GHz wifi'; Describe what is not supported
LEDE Supported Since Commit_git : https://git.lede-project.org/?p=source.git;a=commit;h=42914b0b0e47237400a825a54189d707abd86693 # https://git.lede-project.org/?p=source.git;a=commit;h=<commithash>
LEDE Supported Since Rel_releasesince-lede : # First official release (i.e. not trunk)
LEDE Supported Current Rel_releasecurrent-lede : snapshot # Current official release (i.e. not trunk)
LEDE Unsupported : # Describe what is not supported, e.g. '5GHz wifi'
Gluon support_gluonsupport : unknown # Yes, No, Broken, unknown
Target_target : ar71xx # https://openwrt.org/docs/targets
Subtarget : generic # https://openwrt.org/docs/targets
Instruction Set_hidden : MIPS32 # https://en.wikipedia.org/wiki/List_of_instruction_sets
Sub Instruction Set_hidden : MIPS32 24K/E series # --------> Description goes here
Package architecture_pkg-arch : mips_24kc # https://openwrt.org/docs/instructionset
Packages download_pkg-dl : mips_24kc|Download # https://openwrt.org/docs/instructionset
Bootloader_bootloader : U-Boot # https://openwrt.org/docs/techref/bootloader
CPU : Atheros AR1311 # Main CPU/SoC, e.g. Atheros AR9331; Broadcom BCM6361
CPU Cores_numcores_ : 1 # Number of CPU cores
CPU MHz : 400 # pure number without 'MHz'
Flash MB_mbflashs : 8 # CTRL+click for multiselect
RAM MB_mbram : 64 #
Ethernet 100M ports_numethport : 1 # Number of 100Mbit ethernet ports
Ethernet GBit ports_numethport : - # Number of Gbit ethernet ports
Switch : # e.g. Atheros AR8236
Modem_modem : No # Select type of modem
Comments network ports_ : # Comments on Ethernet, Fibre and Modem
VLAN_yesno : ¿ #
WLAN Hardwares : ¿ Atheros AR9285 (onboard) # e.g. Atheros AR5416; separate multiple by comma; add '#x (mini-)PCI(e)' if necessary
WLAN 2.4GHz_wlan24 : b/g/n #
WLAN 5.0GHz_wlan50 : - #
WLAN Comments_ : # MIMO and other WIFI information
Detachable Antennas_numdetachantenna : - # Number of detachable antennas
Bluetooth_bluetooth : # Bluetooth version, e.g. 4.1
USB ports_port-usbs : 1x 2.0 # Number of USB2.0 & 3.0 ports; CTRL+click for multiselect
SATA ports_numsataport : - # Number of SATA or eSATA ports
Comments USB SATA ports_ : # Comments on USB, SATA and eSATA ports
Video port_port-video : # Kind of video port, e.g. LVDS, HDMI, Composite, ...
Audio port_port-audio : # Kind of audio port, e.g. Line out, phone jack, ...
Phone ports_port-phone : # Number or kind of phone ports
Comments AV ports_ : # Comments on Audio, Video, Phone ports
Serial_yesno : Yes #
Serial connection parameters_serialparam : # e.g. 115200 / 8N1
Serial connection voltage_serialvoltage : ¿ # Serial voltage level
JTAG_yesno : No #
LED count_numled : 2 # Number of (user configurable) LEDs
Button count_numbutton : 2 # Number of (user configurable) buttons/switches (other than Power)
GPIOs_numgpio : # Number of accessible GPIOs
Power Supply : 100-240 VAC, 50/60 Hz, 0.3 A # Specifications of Power Supply (Volt, Amp) or Battery (Volt, mAh)
OpenWrt Device Page_hidden : https://wiki.openwrt.org/toh/d-link/dir-505 # https://wiki.openwrt.org/toh/brand/brand_model_version
LEDE Device Page_page : # toh/brand/brand_model_version
Device Techdata_hidden : View/Edit data # ===> Mandatory, must be "View/Edit data" <===
OWrt Forum Topic URL_url : https://forum.openwrt.org/viewtopic.php?id=38742 # forum.openwrt.org/viewtopic.php?id=xxxxx
WikiDevi URL_url : https://wikidevi.com/wiki/D-Link_DIR-505_rev_A1 # wikidevi.com/wiki/yourdevice
OEM Device Homepage URL_url : http://www.dlink.com/uk/en/home-solutions/connect/portable-routers/dir-505-shareport-mobile-companion # yourbrand.com/yourdevice
Firmware OEM Stock URL_url : http://www.dlink.com/uk/en/support/product/dir-505-shareport-mobile-companion # yourbrand.com/yourdevice/stockfirmware
Firmware OWrt Install URL_hidden : https://downloads.openwrt.org/chaos_calmer/15.05.1/ar71xx/generic/openwrt-15.05.1-ar71xx-generic-dir-505-a1-squashfs-factory.bin # downloads.openwrt.org/latest/...factory.bin; If more than 1 file for install/upgrade -> link to download *folder* instead of image
Firmware OWrt Upgrade URL_hidden : https://downloads.openwrt.org/chaos_calmer/15.05.1/ar71xx/generic/openwrt-15.05.1-ar71xx-generic-dir-505-a1-squashfs-sysupgrade.bin # downloads.openwrt.org/latest/...sysupgrade.bin; If more than 1 file for install/upgrade -> link to download *folder* instead of image
Firmware LEDE Install URL_url : https://downloads.openwrt.org/snapshots/targets/ar71xx/generic/lede-ar71xx-generic-dir-505-a1-squashfs-factory.bin # downloads.openwrt.org/snapshots/targets/...; If more than 1 file for install/upgrade -> link to download *folder* instead of image
Firmware LEDE Upgrade URL_url : https://downloads.openwrt.org/snapshots/targets/ar71xx/generic/lede-ar71xx-generic-dir-505-a1-squashfs-sysupgrade.bin # downloads.openwrt.org/snapshots/targets/...; If more than 1 file for install/upgrade -> link to download *folder* instead of image
Picture_img100s : media:example:genericrouter1.png # media:brand:model_general_view.jpg; Single general picture to identify the device; detail pictures to be provided on device page. How to add images: http://openwrt.org/meta/adding_images_to_openwrt_wiki
Comments_ : Additional to reset and WPA buttons it also has a 3 state mode switch AP/Repeater/HS # Anything that is worth mentioning
----
{{section>:meta:template_dataentry_background#conventions_for_dataentry_values&nofooter&noeditbtn}}
Conventions for dataentry values
General nomenclature
Conventions per characteristic
Technical background
- Why this template?
- Automated toh creation with comfortable filtering option through usage of Structured data plugin for Dokuwiki
- Mode of operation (How does this work?)
- required: Dokuwiki Structured data plugin
- required: Dokuwiki sqlite plugin (for structured data plugin)
- required: Dokuwiki Include plugin (for including permanote, see below)
- required: Dokuwiki server: php5-sqlite
- required: dataentry (see above) on device page or on separate technical data page
- required: data pages with
{{page>meta:infobox:dataentry_permanote&noheader&nofooter&noeditbtn}}(this will include an infobox regarding usage of the dataentry in each of the dataentry pages) - required: page/infobox
dataentry_permanote, which contains the permanent usage notes to be included in the data page (see above) - required: wiki page containing a datatable section → see https://www.dokuwiki.org/plugin:data#data_table_output for details
- Why the '_' at the end of 'Status_' and other characteristics ending in 's'?
Why 'ss' where 's' would be the correct spelling? - Why separate technical data pages? Why not include the technical data in the device pages?
- In general, dataentries can be placed either
- on the device page: Anywhere, at the beginning, at the end, in the middle... it doesn't matter. OR
- on separate dataentry page (one dataentry page per device / per device version)
- For different versions of a device, different dataentry files must be created anyways (only one dataentry section per page allowed). This means:
- Separate the technical data (dataentry) from the device page
- Put dataentry pages in separate namespace
techdata(one dataentry page per device / per differing device version)
- Multiple dataentries on the same page are possible, but do not lead to the desired result, see footnote #1: https://www.dokuwiki.org/plugin:data#fn__1
“any additional dataentry on the same page would overwrite any preceding dataentry on this page and so - while many dataentry blocks on one page may be displayed - only the values of the last one would be stored in the SQLite database and could be retrieved as an output by e.g. a datatable”
→ Any HW version with different technical data needs separate dataentry page, in order for the automatedly created toh to work correctly.
- Why the Datatype aliases? What do these aliases do, how do they work?
- By adding a datatype alias like
_modem,_yesno,_brand,_target, etc., you can define valid values for the respective field, which finally leads to the dataentry editor displaying drop down fields instead of simple textboxes. → User can click and select instead of typing in the value → no different spelling, no need to enter¿manually
- Aliases and the valid values are defined in
admin / Data Plugin: Field aliases
Multiple ToHs
Since it is so easy to create a toh, it's no problem to create multiple tables with different content (columns).
The general OpenWrt/LEDE user may only be interested in the columns as shown above, while other users may whish to have other columns (e.g. what flash chip / RAM chip is used). Whatever the user wants to see in this table: Take a subset of characteristics out of the template, put them in a new wiki page, and you're done. It can't be much easier, can it?
Permanent note
Users need to be kept from doing silly things, that could break the functionality of the data plugin. Therefore, a permanent note shall be included in every dataentry page. In order to define and later on edit the permanent note in only one place, we need an infobox:
Content of meta:infobox:dataentry_topnote
===== Usage ===== * Edit the dataentry via the **LEFT** edit button below the box * For adding new dropdown values, contact the wiki admin. * For conventions / allowed values, see below * For general usage help, see [[:meta:template_dataentry_background|Dataentry template background]]
To include the infobox in the dataentry pages, simply add this: {{page>meta:infobox:dataentry_topnote&noheader&nofooter&noeditbtn}}
Including help for column values into datapages
To include detailed help regarding allowed values and formatting etc. in the dataentry pages, simply add this below the dataentry: {{page>:meta:template_dataentry_background#conventions_for_dataentry_values&nofooter&noeditbtn}}
This is the same way as with including the permanent note above and has the advantage, that you can include this big section in each datapage by adding minimal code, and if something needs to be changed, you only need to change one page, which then is automatically included in all available device- and datapages.