Port Learning Guide¶

Table of Contents¶

Overview
Creating Port Projects
Entry System
Enum Definitions
Rule System

Overview¶

Port operates by reflecting messages in the most recently updated repository. This quick start guide will help you understand how to create, configure, and manage Port projects effectively.

Port provides a comprehensive ecosystem for:

Feature	Description
Entry-based Communication	Structured data exchange between components
Package Integration	Modular architecture with reusable components
Real-time Monitoring	Live project status and logging capabilities
Remote Management	SSH and web-based administration
IoT Integration	MQTT protocol support for device communication

Creating Port Projects¶

Project Structure Overview¶

Port projects are organized hierarchically with a clear folder structure:

Component	Description
Root Folder	Contains project configuration and `*.enum` files
Category Folders	Organize messages by functional areas
Page Files	Individual `*.page` files defining entry

Repository Setup¶

The Port project structure is simple and straightforward. Follow these steps to create your first project:

Create Project Directory: Start with a dedicated project folder
Initialize Project: Use port new [project-name] to generate project files
Add Category: Create sub-folders for message organization
Define Messages: Add *.page files to group folders
Configure Types: Specify text, num, and enum data types
Deploy: Use port push to store project configuration

Repository Naming Rules

Repository names cannot contain special characters and must follow operating system directory naming conventions.

Creating a New Project¶

Create Project

Command:

port new [project-name]

Category Management¶

Categorys serve as logical containers for related messages. Each group can contain multiple message files, enabling organized and abstracted message management.

Adding Categorys¶

Add Category

Benefits of Categorys:

Benefit	Description
Organization	Logical separation of message types
Maintainability	Easier to locate and edit related messages
Scalability	Support for large projects with many messages
Abstraction	Simplified management of complex message relationships

Sample Project Structure¶

Project Structure

Download Sample: Download Sample Project

Entry System¶

Entry Definition Syntax¶

Messages are the core communication units in Port. Each message is defined using a specific syntax:

[key] [datatype] [option...]

Components:

Component	Description
`[key]`	Unique identifier within the message group
`[datatype]`	Data type specification (text, num, enum)
`[option...]`	Additional attributes and configurations

Data Types¶

Port supports three primary data types for message definitions:

Name	Range	Description
char	`0~255`	Fixed-length string type with maximum 255 characters for text storage
num	`-1.7e+308 ~ +1.7e+308`	Floating-point type supporting wide range of decimal values
enum	`0 ~ 65535`	User-defined fixed list from `.enum` files with efficient storage

Entry Attributes¶

Attributes provide additional functionality and behavior for messages:

Attribute	Description
pkg	Real-time synchronization with external libraries (see package documentation)
backup	Automatic database backup with restore on application restart
property	Custom property specifications for message configuration
rule	Value validation and management rules
logging	Automatic logging support for message operations

Special Characters

Message documents should not use special characters in identifiers.

Entry Examples¶

BulbOnOff     enum.OffOn  pkg:Bulb1.OffOn
RoomTemp1     num         pkg:Heater1.Temp  property:{"MIN":0,"MAX":300,"Arguments":"C"}
RoomTemp2     num         pkg:Heater1.Temp  property:{"MIN":0,"MAX":300,"Arguments":"F"}

Explanation:

Variable	Type	Description
BulbOnOff	Enum	Enum-based control linked to Bulb1 package
RoomTemp1	Numeric	Numeric temperature in Celsius with validation range
RoomTemp2	Numeric	Numeric temperature in Fahrenheit with validation range

Enum Definitions¶

Enum Syntax¶

Enums provide a way to define fixed sets of named values, improving code readability and reducing errors.

Format:

[key] [item-name:number_key] [item-name:number_key] ...

Components:

Component	Description
`[key]`	Unique enum identifier
`[item-name]`	Descriptive name for enum value
`[number_key]`	Numeric value associated with the item

Enum Benefits¶

Enums are particularly useful for:

Use Case	Description
Fixed Value Sets	Days of the week, months, status codes
Code Clarity	Self-documenting code with named constants
Error Prevention	Type safety instead of raw numeric values
Maintenance	Centralized value management

Enum Examples¶

TFalse      True:0      False:1
FTrue       False:0     True:1
OffOn       Off:0       On:1
OnOff       On:0        Off:1

Use Cases:

Use Case	Description
Boolean States	True/False, On/Off toggles
Status Indicators	Active/Inactive, Enabled/Disabled
Mode Selection	Manual/Automatic, Local/Remote

Rule System¶

Rule Definition¶

Rules provide conditional logic for message validation and automatic actions. They are defined in *.rule files within group folders.

SetTrigger Rules¶

SetTrigger rules control user modification permissions through conditional validation.

Syntax¶

set("<Input Condition>", "<Validation Condition>");

Components:

Component	Description
Input Condition	Logical expression specifying the input to validate
Validation Condition	Expression that must evaluate to true for acceptance

SetTrigger Examples¶

set("room1.BulbOnOff==Off", "(room1.RoomTemp1>=20)&&(room2.RoomTemp2>=20)")
set("room1.RoomTemp2>=30", "room2.RoomTemp2>=5")

GetTrigger Rules¶

GetTrigger rules execute automatic actions when specified conditions are met.

Syntax¶

get("<Trigger Condition>", "<Action Script>");

Components:

Component	Description
Trigger Condition	Boolean expression for condition evaluation
Action Script	Instructions executed when condition is true

GetTrigger Examples¶

get("(room1.RoomTemp1>=0)&&(room2.RoomTemp2>=0)", "room1.BulbOnOff=Off;room2.BulbOnOff=Off;")

Rule Benefits¶

Benefit	Description
Validation	Enforce business logic and data integrity
Automation	Trigger actions based on system state
Safety	Prevent invalid configurations
Efficiency	Reduce manual intervention needs