L5XJS

KO | EN

gitlite — search

#javascript #ai #typescript #llm #deep-learning #macos #java #awesome #cli #kubernetes #vue #awesome-list #security #ios

(★ 40)

A simple API designed to build and parse Allen Bradley *.L5X* files to empower users to automate PLC code generation.

L5XJS Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# L5XJS

A modern TypeScript library for building and parsing Allen Bradley *.L5X* files to automate PLC code generation.

## 🚀 Version 2.0 - Now with TypeScript!

This major release brings full TypeScript support, modern ES2020 syntax, improved type safety, and a cleaner API.

## Prerequisites

- Node.js 18+ or 20+
- TypeScript 5.0+ (for development)

## Installation

```bash
npm install l5x-js
```

## Quick Start

```typescript
import { Document, Tag, Member } from 'l5x-js';

// Create a new L5X document
const doc = new Document();

// Create tags
const boolTag = new Tag({
  name: 'StartButton',
  datatype: 'BOOL',
  description: 'Start button input'
});

const intTag = new Tag({
  name: 'Counter',
  datatype: 'DINT',
  description: 'Production counter'
});

// Add tags to document
doc.addTag(boolTag);
doc.addTag(intTag);

// Generate L5X XML
console.log(doc.toString());
```

## Advanced Example: Excel to L5X Automation

This example demonstrates how to read tag data from an Excel file and automatically generate PLC ladder logic rungs. This is particularly useful for converting alarm lists, I/O schedules, or tag databases into PLC code.

```typescript
import { Document, Program, Routine, Rung } from 'l5x-js';
import * as xlsx from 'xlsx';

// Define configuration constants
const WORKSHEET_NAME = 'IO_Schedule';
const ROUTINE_NAME = 'AutoGeneratedLogic';

// Read Excel file containing tag definitions
const workbook = xlsx.readFile('./Tags.xlsm');
const worksheet = workbook.Sheets[WORKSHEET_NAME];
const tagData = xlsx.utils.sheet_to_json(worksheet);

// Initialize L5X document structure
const doc = new Document();
const program = new Program({ name: 'MainProgram' });
const routine = new Routine({ name: ROUTINE_NAME });

// Build the hierarchy: Document -> Program -> Routine
program.addRoutine(routine);
doc.addProgram(program);

// Generate ladder logic rungs from Excel data
for (const row of tagData) {
  const tagName = row['Tag'] as string;
  const isInput = row['Input/Output'] === 'Input';
  
  // Create ladder logic based on I/O type:
  // Input:  |---||---------(tagName)---|  (XIC -> OTE)
  // Output: |----|tagName|-------()----|  (XIC -> OTE)
  const rungContent = isInput 
    ? `XIC()OTE(${tagName});`           // Examine if closed, output energize
    : `XIC(${tagName})OTE();`;          // Examine if closed, output energize
  
  // Create and add rung to routine
  const rung = new Rung({ logic: rungContent });
  routine.addRung(rung);
}

// Set import target for Rockwell software
doc.setTarget(routine);

// Export L5X file ready for Studio 5000 import
doc.export(`./${WORKSHEET_NAME}_Generated.L5X`);

console.log(`Generated ${tagData.length} rungs in ${ROUTINE_NAME}`);
```

### What This Example Does:

1. **Reads Excel Data**: Imports tag information from an Excel spreadsheet containing I/O definitions
2. **Creates PLC Structure**: Builds a complete L5X document with Program and Routine containers
3. **Generates Ladder Logic**: Automatically creates ladder rungs based on whether tags are inputs or outputs
4. **Exports L5X File**: Produces a file ready for import into Rockwell Automation Studio 5000

### Excel File Format Expected:
| Tag | Input/Output | Description |
|-----|--------------|-------------|
| StartButton | Input | Main start button |
| StopButton | Input | Emergency stop |
| RunningLight | Output | Status indicator |

This automation can save hours of manual PLC programming when dealing with large I/O lists or repetitive logic patterns.

## API Documentation

### Document Class

The main class for creating and manipulating L5X files.

#### Constructor

```typescript
new Document(filepath?: string)
```

**Parameters:**
- `filepath` (optional): Path to existing L5X file to load

**Examples:**
```typescript
// Create new document
const doc = new Document();

// Load existing document
const doc = new Document('./existing.L5X');
```

#### Methods

##### `addTag(tag: Tag): void`

Adds a tag to the controller.

```typescript
const tag = new Tag({ name: 'MyTag', datatype: 'BOOL' });
doc.addTag(tag);
```

##### `getTags(): Tag[]`

Returns all tags in the document.

```typescript
const tags = doc.getTags();
tags.forEach(tag => console.log(tag.name));
```

##### `toString(): string`

Generates the L5X XML string.

```typescript
const xmlContent = doc.toString();
```

##### `findOne(type: string, attributes?: object): XmlElement | null`

Finds the first element of specified type.

```typescript
const controller = doc.findOne('Controller');
const specificTag = doc.findOne('Tag', { Name: 'MyTag' });
```

##### `findAll(type: string, attributes?: object): XmlElement[]`

Finds all elements of specified type.

```typescript
const allTags = doc.findAll('Tag');
const boolTags = doc.findAll('Tag', { DataType: 'BOOL' });
```

### Tag Class

Represents PLC tags with type safety and validation.

#### Constructor

```typescript
new Tag(options: TagOptions)
```

**TagOptions Interface:**
```typescript
interface TagOptions {
  name: string;           // Tag name
  datatype: string;       // PLC data type (BOOL, DINT, REAL, etc.)
  description?: string;   // Optional description
  alias?: string;         // Optional alias reference
  safety?: boolean;       // Safety tag flag
  dimension?: number;     // Array dimension
}
```

**Examples:**
```typescript
// Basic tag
const tag = new Tag({
  name: 'Motor1_Run',
  datatype: 'BOOL'
});

// Tag with all options
const tag = new Tag({
  name: 'Temperature',
  datatype: 'REAL',
  description: 'Reactor temperature in °C',
  safety: false,
  dimension: 10
});

// Alias tag
const alias = new Tag({
  name: 'START_BTN',
  datatype: 'BOOL',
  alias: 'Local:1:I.Data.0'
});
```

#### Properties

##### `name: string` (readonly)
Gets the tag name.

##### `datatype: string` (readonly)
Gets the tag data type.

##### `description: string | undefined` (readonly)
Gets the tag description.

#### Static Methods

##### `Tag.isTag(obj: unknown): boolean`
Type guard to check if object is a Tag instance.

```typescript
if (Tag.isTag(someObject)) {
  console.log(someObject.name); // TypeScript knows it's a Tag
}
```

### Member Class

Represents PLC tag members for structured data types.

#### Constructor

```typescript
new Member(options: MemberOptions)
```

**MemberOptions Interface:**
```typescript
interface MemberOptions {
  name: string;           // Member name
  datatype: string;       // PLC data type (BOOL, DINT, REAL, etc.)
  description?: string;   // Optional description
  hidden?: boolean;       // Hidden member flag
  target?: string;        // Target reference for BOOL/BIT types
  bitNumber?: number;     // Bit number for BOOL/BIT types
}
```

**Examples:**
```typescript
// Basic member
const member = new Member({
  name: 'Status',
  datatype: 'DINT'
});

// Boolean member with target
const boolMember = new Member({
  name: 'Running',
  datatype: 'BOOL',
  target: 'StatusWord',
  bitNumber: 0
});

// Member with description
const member = new Member({
  name: 'Temperature',
  datatype: 'REAL',
  description: 'Current temperature value',
  hidden: false
});
```

#### Static Methods

##### `Member.isMember(obj: unknown): boolean`
Type guard to check if object is a Member instance.

```typescript
if (Member.isMember(someObject)) {
  console.log(someObject.name); // TypeScript knows it's a Member
}
```

### Element Class

Base class for all L5X elements with XML manipulation capabilities.

#### Methods

##### `findOne(type: string, attributes?: object, ignore?: string[], searchTree?: XmlElement): XmlElement | null`

Finds first matching element.

**Parameters:**
- `type`: Element type to search for
- `attributes`: Optional attribute filters
- `ignore`: Array of element names to ignore
- `searchTree`: Optional subtree to search in

##### `findAll(type: string, attributes?: object, ignore?: string[], searchTree?: XmlElement): XmlElement[]`

Finds all matching elements.

##### `toString(): string`

Converts element to XML string.

### Utility Functions

```typescript
import { Util } from 'l5x-js';

// Generate hash
const id = Util.hash('some-string');

// Validation helpers
Util.validateString(value, 'parameterName');
Util.validateObject(value, 'parameterName');
```

## Type Definitions

The library includes comprehensive TypeScript definitions:

```typescript
interface XmlElement {
  type?: string;
  name?: string;
  attributes?: Record<string, string | number | boolean>;
  elements?: XmlElement[];
  text?: string;
}

interface XmlDocument {
  declaration?: {
    attributes: {
      version: string;
      encoding: string;
      standalone?: string;
    };
  };
  elements: XmlElement[];
}
```

## Common PLC Data Types

| Type | Description | Example |
|------|-------------|---------|
| `BOOL` | Boolean | `true`/`false` |
| `SINT` | Short Integer | `-128` to `127` |
| `INT` | Integer | `-32,768` to `32,767` |
| `DINT` | Double Integer | `-2,147,483,648` to `2,147,483,647` |
| `REAL` | Floating Point | `3.14159` |
| `STRING` | Text String | `"Hello World"` |

## Error Handling

The library provides descriptive error messages with type information:

```typescript
try {
  const tag = new Tag({
    name: 123, // Invalid type
    datatype: 'BOOL'
  });
} catch (error) {
  console.log(error.message); // "Tag name expected type <string> but got <number>"
}
```

## Migration from v1.x

### Breaking Changes

1. **Constructor Changes**: Tag constructor now uses options object
   ```typescript
   // v1.x
   new Tag('MyTag', 'BOOL', 'Description');
   
   // v2.x
   new Tag({ name: 'MyTag', datatype: 'BOOL', description: 'Description' });
   ```

2. **Import Changes**: Now uses ES6 imports
   ```typescript
   // v1.x
   const { Document, Tag } = require('l5x-js');
   
   // v2.x
   import { Document, Tag, Member } from 'l5x-js';
   ```

3. **TypeScript**: Full type safety - invalid usage caught at compile time

## Development

```bash
# Install dependencies
npm install

# Run tests
npm test

# Build for production
npm run build

# Lint code
npm run lint
```

## Built With

* [TypeScript](https://www.typescriptlang.org/) - Language & Type Safety
* [Node.js](https://nodejs.org/en/) - Runtime Environment
* [xml-js](https://www.npmjs.com/package/xml-js) - XML Processing
* [Jest](https://jestjs.io/) - Testing Framework

## Contributors

* **Canaan Seaton** - *Original Author* - [GitHub](https://github.com/cmseaton42) - [Website](http://www.canaanseaton.com/)

Want to contribute? Check out our [Contributing Guide](https://github.com/cmseaton42/L5XJS/blob/master/CONTRIBUTING.md)!

## License

This project is licensed under the MIT License - see the [LICENSE](https://github.com/cmseaton42/L5XJS/blob/master/LICENSE) file for details.

L5XJS

L5XJS Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

L5XJS

L5XJS Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README