OpenLightingProject / OpenLightingProject/open-fixture-library

Add DMXIS Plugin

Open
#247 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

difficulty-easy good first issue hacktoberfest help wanted new-plugin
Dominant language
JSON
Stars
258
Forks
100
Avg merge
11h 52m
Merged PRs (30d)
53

Description

DMXIS and D-Pro are products by Enttec.

Both programs (or at least a demo version) are free downloadable. The Windows versions can be used with Wine quite well on Linux machines.

There's an online fixture editor and library (for which you need an account), but you can only download DMXIS fixtures from there. D-Pro fixtures are synchronized automatically with that library. See the help page.

The fixture editor doesn't allow some characters for free-text fields, so we should further investigate these (and also maximum length). There are also many fields (like default value, channel category, ...) that are only used by the D-Pro format.

DMXIS file format

They are saved as txt files. The format is very simple, this blog post explains it. They basically only have channel name and capabilities, each capability has the DMX range, a label and a symbol for variable (V), static (S), dimmer (D) or blackout (B).

The library zip is of the structure /DmxLibrary/<Manufacturer>/<Fixture-Mode>.dmx

Sample file: Martin-Mac Aura Extended.zip

D-Pro file format

The D-Pro fixture library, a Fixtures.dsf file, is actually a SQLite 3 database file (call me sherlock 🕵️‍♂️). One can download an empty fixture library or use the database from the installation directory. We could create such a database with the sqlite3 npm package.

One can only download fixtures of the before mentioned fixture library directly from the D-Pro software and then manually it extract it from the installation directory. This allows us to reverse-engineer how the database works.

SQLite3 table structure
sqlite> .tables
FdChannelModes   FdChannels       FdFixtures       FdModeTriggers 
FdChannelRange   FdFixtureModes   FdManufacturers
sqlite> .schema *
CREATE TABLE IF NOT EXISTS "FdManufacturers"(
  "ManufacturerID" INTEGER PRIMARY KEY NOT NULL,
  "Name" VARCHAR(100)
);
CREATE TABLE IF NOT EXISTS "FdFixtures"(
--   When user creates a new fixture, they are emailed a password, which allows them to edit it later. Don't think we want to allow free write access to fixtures!
--   
--   The user can choose to keep a fixture private (for editing purposes, or to create a personal variant e.g. with custom gobos)
  "FixtureID" INTEGER PRIMARY KEY NOT NULL,
  "ManufacturerID" INTEGER NOT NULL,
  "Name" VARCHAR(100),
  "Description" TEXT,
  "PasswordToEdit" VARCHAR(20),
  "IsPublic" BOOL,
  CONSTRAINT "fk_Fixtures_Manufacturers1"
    FOREIGN KEY("ManufacturerID")
    REFERENCES "FdManufacturers"("ManufacturerID")
);
CREATE TABLE IF NOT EXISTS "FdFixtureModes" (
  FixtureModeID  integer PRIMARY KEY,
  FixtureID      integer,
  Name           varchar(45),
  PublicMode     bool, HasRgb boolean NOT NULL DEFAULT 0, HasPanTilt boolean NOT NULL DEFAULT 0,
  /* Foreign keys */
  FOREIGN KEY (FixtureID)
    REFERENCES "FdFixtures"(FixtureID)
    ON DELETE NO ACTION
    ON UPDATE NO ACTION
);
CREATE TABLE IF NOT EXISTS "FdModeTriggers" (
  ModeTriggerID   integer PRIMARY KEY NOT NULL,
  ChannelRangeID  integer NOT NULL,
  ChannelModeID   integer,
  /* Foreign keys */
  FOREIGN KEY (ChannelRangeID)
    REFERENCES "FdChannelRange"(ChannelRangeID)
    ON DELETE CASCADE
    ON UPDATE NO ACTION
);
CREATE TABLE IF NOT EXISTS "FdChannelRange" (
  ChannelRangeID  integer PRIMARY KEY AUTOINCREMENT NOT NULL UNIQUE,
  ChannelModeID   integer NOT NULL,
  IsDimmer        bool,
  IsBlackout      bool,
  IsContinuous    bool,
  MinVal          integer,
  MaxVal          integer,
  Label           varchar(45),
  ShortLabel      varchar(20),
  /* Foreign keys */
  FOREIGN KEY (ChannelModeID)
    REFERENCES "FdChannelModes"(ChannelModeID)
    ON DELETE CASCADE
    ON UPDATE NO ACTION
);
CREATE TABLE sqlite_sequence(name,seq);
CREATE TABLE IF NOT EXISTS "FdChannelModes" (
  ChannelModeID  integer PRIMARY KEY NOT NULL,
  ChannelID      integer NOT NULL,
  /* Foreign keys */
  FOREIGN KEY (ChannelID)
    REFERENCES "FdChannels"(ChannelID)
    ON DELETE CASCADE
    ON UPDATE NO ACTION
);
CREATE TABLE FdChannels (
  ChannelID      integer PRIMARY KEY,
  FixtureModeID  integer,
  ChannelNumber  integer,
  Name           varchar(45),
  ShortName      varchar(20),
  DefaultValue   integer NOT NULL DEFAULT 0,
  Snap           integer NOT NULL DEFAULT 0,
  Category       integer NOT NULL DEFAULT 0,
  Subcategory    integer NOT NULL DEFAULT 0,
  Highlight      integer NOT NULL DEFAULT -1,
  /* Foreign keys */
  FOREIGN KEY (FixtureModeID)
    REFERENCES FdFixtureModes(FixtureModeID)
    ON DELETE NO ACTION
    ON UPDATE NO ACTION
);

So the D-Pro plugin would definitely be difficulty-medium.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked DMXIS format description and the sample Martin-Mac Aura Extended archive, then inspect the D-Pro Fixtures.dsf schema and empty database. Determine how both formats should map into the library's fixture definitions, including the noted free-text restrictions and D-Pro-only fields. Done means the project can import representative DMXIS and D-Pro fixtures with the relevant fixture, mode, channel, and capability data preserved.

Written by the indexing model from the issue text.

Assessment

Tech stack
nodejs, sqlite
Domain
data, databases
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.