Dogma

Introduction


Dogma is a declarative translation unit that describes all aspects of a node. It is written in a special json based schema that the node can interpret to set itself up with the correct configuration.

The configuration cover the following areas:
  • Triggers and Actions
  • Directives
  • Description of locations and areas in a map
  • Reference to other nodes by ID
  • Grouping tags and node selectors
  • References to web services by URL
  • Shared secrets
  • Hardware configuration
  • Lobe configuration
  • And much much more!

Structure


The file contains one root element with the following parts:
  • Zero or more detail sections describing different parts of the node such as references, lobes, secrets and poses
  • Exactly one directive section marked "main" that may reference the detail sections
  • Zero or more secondary directive sections that may reference the detail sections
The main directive section must contain the ID of the node which matches the key-pair in the key-store for the node. If this has not been specified correctly the robot will enter a vegetative safety state and will not respond to any commands.

References & inlining


Detail sections may be inlined directly where they are used or they may be referenced by a hashtag followed by their unique name.

Example of in-lining:

"directive": {
    "name":"A113",
    "description":"Dispose of the plant",
    "secret": {"text":"THIS IS THE SECRET DON'T TELL ANYONE!!"}
}

Example of reference:

"secret": {
    "name":"A113SECRET",
    "text":"THIS IS THE SECRET DON'T TELL ANYONE!!"
}

"directive": {
    "name":"A113",
    "description":"Dispose of the plant",
    "secret": "#A113SECRET"
}

The benefit of in-lining is obviously that it for simple cases saves a lot of lines. The benefit of references is that several sections may reference the same secondary section, making for less copy-pasting and sources of error. Also if many reference it there is a a possibility of considerable savings in number of lines.




Sections

Common section anatomy


The following fields are possible to put in any section
  • From - A reference to another "base" section from which this section will inherit its field values. If this is missing, the section will automatically inherit from the "default" section of this type which, contains the default values of such a section. Circular reference loops are not allowed.
  • Name - Optional name of the section. This is necessary if you want to reference the section. It is not necessary if you "inline" the section into another. Name must be unique for all sections regardless of type in the entire dogma translation unit.
  • Description - Optional description of the section. This is only for documentation purpose. Description will be propagated to UI so that it becomes visible either as a label or as a tool-tip for reference by the user.

Directive

  • Personality  - An integer index that is added to the personality PRNG seed to vary the personality. For a glimpse into personality, see this and this.
  • Name - The given name that this node will go by by her friends.
  • Gender - The gender identity of this node.

Controller

  • Type - The controller type. One in [ardumy, servotor32]
  • Controller specific fields - The rest of the section will be specific to the controller type that was selected

ArduMY Controller

  • Actuators - List of actuators

Servotor32 controller

  • Actuators - List of actuators

Actuator reference

  • Controller - The controller which contains the actuator
  • Actuator - The actuator
  • Flags - Active flags in [reverse]

Lobe

  • Type - The lobe type in [tracked, wheeled, hovering, legged]
  • Lobe  specific fields - The rest of the section will be specific to the lobe type that was selected. (Se lobe specific sections below)

Wheeled lobe

Explanation is here.
  • Throttle - Actuator reference to use for throttle
  • Steering - Actuator reference to use for steering

Leg lobe

Explanation is here.
  • Hip (Coxa) - Actuator reference to use for hip
  • Thigh (Femur) - Actuator reference to use for thigh 
  • Shin (Tibia) - Actuator reference to use for shin
  • Foot (Tarsus) - Optional actuator reference to use for foot

Secret

  • Text - The secret string in clear-text

Gear ratio

  • Gear-ratio-numerator - The gear numerator part of ratio of the actuator
  • Gear-ratio-denominator - The gear denominator part of ratio of the actuator

Actuator

  • Type -  in [RC-Servo, step-motor, brush-less-dc, brushed-dc]
  • Data-bits -  int number of bits
  • Data-type - in [float, fixed, int]
  • Range-lower - The lower value possible for this actuator
  • Range-higher - The lower value possible for this actuator
  • Limit-lower-enable - Enable for lower limit switch
  • Limit-higher-enable - Enable for higher limit switch
  • Limit-lower-pin - The pin for lower limit switch
  • Limit-higher-pin - The pin for higher limit switch
  • Position-feedback-enable - Enable for position feedback
  • Position-feedback-pin - The pin for position feedback
  • Tachometer-enable - Enable for tachometer
  • Tachometer-pin - The pin for tachometer pulse
  • Encode-enable - Enable for encoder
  • Encode-absolute-enable - Enable for absolute vs. relative encoder
  • Encode-a-pin - The A pin for encoder
  • Encode-b-pin - The B pin for encoder
  • Gear ratio - The gear ratio
  • Flags - Flags for the actuator in [continuous, linear, reversed] - 

Puppet

  • Actuators - List of puppet actuators

Pose

  • Puppet - Reference to the puppet
  • Values - List of puppet actuators by ID with:
    • Actuator mode in [limp, freeze, train, move]
    • Actuator value (only used if mode is move or train

Animation

  • Poses - List of poses, each with a nanosecond time stamp relative to animation start. Only poses for one puppet is allowed.

    Condition

    • Text - The condition statement in condition syntax

    Trigger

    • Conditions - List of references to conditions that need to evaluate to true for the trigger to activate
    • Actions - List of reference to directives to invoke in order when the trigger is activated
    The expression in the condition follows a simple syntax outlined here.

    Resource

    • URI - The location of the resource


    Subpages (2): Condition syntax Store
    Comments