Natlink

Natlink is an OpenSource extension module for the speech recognition program dragon. Natlink is required for add on packages such as Unimacro, Vocola2, and Dragonfly.

Status

Natlink code has been updated from Python 2 to Python 3. It is relatively stable, but not released per se as a stable release. Only Dragonfly is supported at this time.

Enabling Unimacro and Vocola(2) is not yet implemented.

Instructions for End Users

Preinstall requirements

DNS 13, DPI 14, and DPI 15 or derivative of the same versions
Install Python 3.8.X 32 bit on your system, and select add Python to Path.
Make sure any previous versions of Natlink are unregistered and uninstalled. (Dragon must be close during that process.)

Natlink Install via CLI

Close Dragon if open
Open Command Prompt/PowerShell as administrator
Upgrade pip: pip install --upgrade pip
pip install natlink from PyPI
natlinkconfig_cli # should auto setup and register itself.
(Optional) type u to see all CLI options
Set Natlink UserDirectory: type n C:\path-to-your-grammars-folder. Modify this path to where your dragonfly grammars are.
Restart Dragon and the "Messages from Natlink" window should start with Dragon.

Natlink Install via GUI

The program natlinkconfig, being the GUI version, can be launched from a PowerShell running as in elevated mode (Admin Privileges). After the natlink.pyd file has been registered and Natlink is enabled, further configuration can be done. Note: unfortunately, Vocola and Unimacro cannot be enabled for the time being.

Troubleshooting On non-administrator accounts:

You may need to manually delete natlink.pyd as administrator after closing the CLI
Running terminal as administrator changes the user account causing a mismatch between user directories between administrator/non-administrator. This impacts where your settings are stored for natlink.
- Fix:- Create an OS environment variable DICTATIONTOOLBOXUSER pointing to a directory to store .natlink.

Support

Review current issues
Join us on

Info

By default, config files for Natlink are stored in the .natlink subdirectory of the Home directory (something like C:\Users\User).
- When you want to change this default location, specify a valid directory in the environment variable DICTATIONTOOLBOXUSER:
  - For example C:\Users\Your-User-Name\Documents.
  - You can also choose C:\Users\Your-User-Name\Documents\.dictationtoolbox.
- The .natlink directory (with config file natlinkstatus.ini) will be created in the Home or DICTATIONTOOBOXUSER directory.
- If natlink is properly registered, the natlink.pyd file path location stored in natlinkstatus.ini in the .natlink directory
- Other config info, from natlinkconfig or natlinkconfig_cli will be stored in the same config file natlinkstatus.ini.

Instructions for Developers

Also read Read the docs
Natlink and other packages are all installed as packages in (\python38-32)\Lib\site-packges.
As all packages (the root directory) are recognised in the PythonPath, we do not need a special reference in the registry any more, that points to the natlinkcore directory where natlink.pyd is copied to (in the natlinkconfig program) and registered.
For all these packages we need qualified imports, for example: === from natlinkcore import natlink === from dtactions import sendkeys

Your local git repository can be anywhere conveninent. It no longer needs to be in a specific location relative to other dictation-toolbox packages.

Install as per the instructions for end users, to get any python prequisites in.
Install flit pip install flit. This is a python package build tool that is required for developer workflow.
Uninstall the packages you wish to develop. i.e pip if you want to work on natlink: pip uninstall natlink and answer yes to all the questions about removing files from your python scripts folder.
Build the Python packages. In the root folder of your natlink repository, run build_package in your shell. This creates the package.
At this step, if you have any untracked files in your git repository, you will have to correct them with a git add command or adding those files to .gitignore.
The cool part: `flit install --symlink'. This will install natlink into site-packages by symolically linking site-packages/natlink to the src/natlink folder of your git repository. You can edit the files in site-packages/natlink or in your git repository area as you prefer - they are the same files, not copies.

Oddly, when you follow this workflow and register natlink by running startnatlinkcofig or natlinkconfigfunctions, even though the python paths those commands pickup, you will find that the natlinkcorepath will be in our git repository.

If you uninstall natlink, and install it with pip, and reregister natlink, you will find the core diretory is recognized as a subfolder of site-packages.

FAQ for compiling with Visual Studio

If you need to build natlinksource (the C++ code) refer to the readme.md in the NatlinkSource folder.

Notes About Packaging for Developers

This is because there are import statements in macrosystem/core import natlink. So modules trying to import from a natlink folder break. This is particularly problematic for scripts end-users might run while setting up natlink. This probably won't be resolved by moving natlink.pyd to another folder or name.

The package is specified in pyproject.toml and built with flit. The build_package command (a batch file in the root folder of natlink) builds a source distribution.

Several scripts are specfied in pyproject.toml in the scripts section. Scripts are automatically generated and placed in the python distribution "Scripts" folder. Those scripts are then available in the system path for users to run. Note the flit install --symlink will install scripts as batchfiles; pip install natlink ... will install scripts as .exe files.

Version numbers of the packages must be increased before your publish to Python Packaging Index. These are specified in init.py in src/natlink. Don't bother changing the version numbers unless you are publishing.

This will publish to Python Packaging Index: publish_package_pypy.

If you are going to publish to a package index, you will need a .pypirc in your home directory. If you don't have one, it is suggested you start with pypirc_template as the file format is rather finicky.

Debugging

A lot of extra diagnostic information is written using outputDebugString (from pydebugstring.output import outputDebugString).
You can add extra diagnostic information to natlink or your own code and leave it in. To view this diagnostic information you an use DebugView from https://docs.microsoft.com/en-us/sysinternals/. There are some diagnostics for natlink startup that are always available if you start DebugView.

If you want to attach a python debugger, the instructions are in a word document "debugging python instructions.doc" in natlinkcore.