alias - Manage Alias Configuration Files

Description

The alias command manages alias configuration files that map channel names to more user-friendly aliases. This allows you to upload custom alias files, download existing ones, and activate specific configurations.

Syntax

alias [options]

Options

Options Details

• --upload: Uploads a local alias/config file to the hardware but does NOT activate it
• --download: Downloads an alias file from hardware to your local system
• activate: Activates a previously uploaded alias file (makes it the active configuration)

Examples

List Available Alias Files

alias

Output:

Available Alias files:
default.config
custom_aliases.xml
production_v1.config

Upload an Alias File

alias --upload "C:\configs\my_aliases.xml"

Output:

Available Alias files:
default.config
custom_aliases.xml
my_aliases.xml
Uploaded C:\configs\my_aliases.xml

Download an Alias File

alias --download "custom_aliases.xml"

The system will prompt for destination:

Available Alias files:
default.config
custom_aliases.xml
Enter destination file name (default is current directory): C:\backup\aliases.xml
Downloaded custom_aliases.xml

Activate an Alias File

alias --activate "custom_aliases.xml"

Output:

Available Alias files:
default.config
custom_aliases.xml
Activated custom_aliases.xml

Combined Operations

# Upload and activate in two steps
alias --upload "production.config"
alias --activate "production.config"

Output Format

Available Alias files:
filename1.config                                             
filename2.xml                                                
filename3.config                                             
[Operation messages]

Output Colors

• Dark Gray: Alias file names (padded to 60 characters)
• Green: Success messages
• Red: Error messages

Behavior

Upload Process

1. Validates file exists locally
2. Removes quote characters from path
3. Uploads file to hardware
4. File becomes available but NOT active
5. Reports success

Download Process

1. Lists available files
2. Prompts for local destination path
3. If no path entered, saves to current directory with original filename
4. Downloads file from hardware
5. Reports success

Activate Process

1. Loads the specified config file
2. Applies aliases to channels
3. Channel names change to their aliases
4. Reports success

File Formats

Alias files typically use:

• XML format (.xml extension)
• Config format (.config extension)

Content structure maps NetName to Alias:

<Channel NetName="CH_VOLTAGE_01" Alias="MainPower_5V" />
<Channel NetName="CH_GPIO_12" Alias="LED_Status" />

Use Cases

Development vs Production Aliases

# Development environment
alias --activate "dev_aliases.config"
list  # Shows development-friendly names

# Production environment
alias --activate "prod_aliases.config"
list  # Shows production standard names

Backup Configuration

# Backup current alias configuration
alias --download "current.config"
# Destination: C:\backups\aliases_2024_01_15.config

Deploy New Configuration

# Upload new configuration
alias --upload "C:\projects\new_aliases.xml"

# Test it
alias --activate "new_aliases.xml"
list --filter ".*"  # Verify all aliases

# If issues, revert
alias --activate "default.config"

Multi-Environment Setup

# Lab environment
alias --upload "lab_aliases.config"
alias --activate "lab_aliases.config"

# Test environment
alias --upload "test_aliases.config"
alias --activate "test_aliases.config"

# Production
alias --upload "prod_aliases.config"
alias --activate "prod_aliases.config"

Important Notes

⚠️ Upload vs Activate: Uploading does NOT activate. You must explicitly activate after upload.

⚠️ Channel References: After activating aliases, use the alias names in other commands:

alias --activate "my_aliases.xml"
# Now use alias names:
get --channel "FriendlyName"  # Not the NetName

⚠️ File Persistence: Alias files persist across resets and reboots

Error Handling

File Not Found (Upload)

alias --upload "missing.xml"

File missing.xml does not exist

Solution: Verify file path is correct

Invalid Alias File

If hardware rejects the file format, it will not appear in the available files list.

Solution: Validate XML/config file structure

Download Prompt

The download operation prompts for destination interactively. Cannot be automated in script mode.

Best Practices

1. Version Control: Keep alias files in version control
2. Naming Convention: Use descriptive names (project_v1.config, not config1.config)
3. Backup Before Changes: Download current config before activating new one
4. Test First: Test new aliases in development before production
5. Document Mappings: Keep separate documentation of NetName→Alias mappings

Workflow Example

Complete workflow for updating aliases:

# 1. Backup current configuration
alias --download "current.config"
# Save to: C:\backups\config_backup_20240115.config

# 2. Upload new configuration
alias --upload "C:\configs\updated_aliases.xml"

# 3. Verify upload
alias
# Confirm "updated_aliases.xml" appears in list

# 4. Activate new configuration
alias --activate "updated_aliases.xml"

# 5. Verify aliases work
list
get --channel "NewAliasName"

# 6. If problems, revert
# alias --activate "current.config"

Channel Name Resolution

After activating aliases, commands accept:

• Alias names: User-friendly names from alias file
• NetNames: Original hardware names (still work)
• Regex patterns: Match against aliases OR NetNames

alias --activate "friendly.config"

# All these may work:
get --channel "MainPower"           # Alias
get --channel "CH_VOLTAGE_01"       # NetName
get --channel "Main.*"              # Regex on alias

See Also

• init - Initialize connection (required before using alias)
• list - View channels with their current aliases
• conf - Configure channel properties
• module - Module management (modules may have default aliases)