Components

Components in EDAsolver are best described conceptually as any component that would be found in a schematic. Unlike components in schematics, however, components in EDAsolver provide a machine-readable understanding of how such components operate within the context of a greater system.

There is a built-in library of components, but custom components can also be defined by users.

_images/4051.png

EDAsolver operates on the principle that components can both provide and consume resources in a design. Components also have attributes such as cost, onboard flash, and maximum CPU frequency. Different types of components will have different attributes, but attributes allow for powerful component filtering and selection during the design phase.

The 4051 is a popular analog multiplexer. It allows multiple analog inputs to be selected to a single pin, X. Three digital inputs select each of the 8 analog inputs. The 4051 also needs a 5 V power supply to operate correctly. To get an idea of how the 4051 is defined in EDAsolver, here is the full definition:

 1{
 2    "name": "4051",
 3    "links": ["http://playground.arduino.cc/Learning/4051"],
 4    "cost": 0.62,
 5    "popularity": 3,
 6
 7    "requires": {
 8        "power_supplies": [{
 9            "name": "vcc",
10            "voltage": 5,
11            "current": 16e-6
12        }],
13        "pins": [
14            {
15                "type": "analog",
16                "range": "X",
17                "direction": "out"
18            },
19            {
20                "type": "digital",
21                "range": "A,B,C",
22                "direction": "in",
23                "voltage": "vcc"
24            }
25        ]
26    },
27    "provides": {
28        "pins": [
29            {
30                "type": "analog",
31                "range": "X0-X7",
32                "direction": "in"
33            }
34        ]
35    }
36}

Components are, for now, independent of packaging. There should be no difference between an ATmega8 in a TQFP and one in a DIP. Also, there are a few components in schematics that do not belong as components in EDAsolver. Current-limiting resistors are good examples of this. While LED components in EDAsolver will need these, the resistors are not separate EDAsolver components. They are expected to be included within the LED component. Once EDAsolver has schematic generation, this will be handled automatically.

Note

The full collection of EDAsolver components can be found here: https://github.com/corywalker/eda_solver_parts

File structure

As a general overview, components are represented as JSON files in the following directory structure:

<type> / <class> / <model>.json

Type

A very general category of the component. Examples: processor, motor, line_sensor.

Class

A slightly more specific category of the component. Class names should be descriptive even without knowing the type. For example, two classes in the led type are simple_led and rgb_led.

Model

A model is the actual model name that one would see in a datasheet. These are typically lower-cased. Examples: arduino_uno_r3, rover_5_driver, qtr-1rc.

Basics

Every component should define the following keys:

name

This is the full name of the component. The model name is a shortened version, but this is a full-length and human-readable name.

links

This is a list of links to information on the component. It can be a main information page or it can be a link to the the component in some online store. If there are no relevant links, create an empty list.

cost

This is the rough cost of the component. It is used occasionally for sorting and selecting based on cost. Yes, component prices vary by package, supply and demand, and volume. These variations might be taken into account later, but not at this point. Right now, I am assuming ample supply and a purchase quantity of a single unit.

popularity

A good community is often an important factor in choosing a component. This ranking goes from 3 down to 1, with 3 being on par with the Arduino and Raspberry Pi, and 1 being a component that is fairly obscure. While some professionals may be less worried about this factor in their designs, it is certainly important for others

The rest of the component definition is usually divided into the requires and provides sections. These sections are outlined below.

Attributes section

The attributes section can contain anything related to the class of the component. Imagine you are on Digikey or Mouser looking for a part. The filters provided are crucial to finding the right part. These attributes allow for that filtering to take place in EDAsolver. If all processors have a flash attribute that specifies the amount of flash storage, in bytes, on the device, then this attribute can be easily filtered in the design file.

Attributes must be standardized to be useful. Check with similar devices before deciding on a name and value for an attribute.

Requires section

As mentioned above, components generally have some requirements of other resources in a design. Power is an obvious one. Most components also need some some pins to be connected in order for it to fully function. Because of this, the following keys might be included in the requires section:

power_supplies

This contains an array of power supplies that the device consumes. Components can often have multiple power supplies. For example, motor controllers usually require a logic power supply and also a higher-voltage and higher-current power supply for the motors. These power supply definitions will be covered in more detail below.

pins

This contains an array of pins that the device consumes. Requirement pins are generally the pins that a higher-level controller will interact with. For example, a motor controller will usually accept some control signals as requirements. These control pins are usually PWM and digital pins that control the speed and direction of motors. The actual lines that go to the motors however, would be in the provides section, not the requires section. These pin definitions will be covered in more detail below.

Some components do not require anything. In this case, the requires section can be omitted.

Provides section

Similar to the requires section, this one also defines power supplies and pins, but instead they are being offered to other components in the design rather than being consumed.

power_supplies

Many components provide power to others. This key should contain an array of those power supplies. For switching power supplies and batteries, for example, this is their primary objective. Other components such as development boards provide power rails as convenience. These power supplies will usually have a voltage and a maximum current. If no power supplies are to be provided, an empty array should be specified.

pins

This contains an array of pins that the component provides to other devices. Microcontrollers generally have large pins sections, as this is usually one of their main functions.

Some components do not provide anything. In this case, the provides section can be omitted.

Power supply definitions

All power supply definitions must specify a voltage (or voltage range) and maximum current. Here are the possible keys that can be in a power supply definition:

voltage

This is a float that specifies the voltage. A voltage range can be specified using voltage_min and voltage_max instead of this key.

Warning

Specifying a voltage range for a definition in the provides section may not be supported yet.

current

For power sources, this is the maximum current that the supply can provide. EDAsolver will ensure that the devices depending on this source will not consume more than this amount. For power requirements, this current value is the maximum current that the component will consume at the specified voltage during operation.

Note

In the design file, the maximum current can be set to an average value with the power_percentage key.

name

If the power source is referenced anywhere else in the component, the power source will need to be named. The name is a simple string that should be unique to the component. Examples are “vcc” and “vbat”. A common use case for this is if the logic power requirement is a voltage range. If a device operates with either 3.3V or 5V, the pins need to be at this logic level, also. This way, EDAsolver will not assume 5V tolerant inputs with a 3.3V logic power supply.

Warning

Naming power supplies in the provides section is not supported yet.

Pin definitions

A pin definition is a grouping of traits spread across pins. It is very important to understand that pins can be included in multiple pin definitions. In other words, individual pins can have multiple functions and behaviors. For example, let us consider the first two pin definitions in the arduino_uno_r3 component:

 1[{
 2    "type": "digital",
 3    "range": "0-13,A0-A5",
 4    "direction": "inout",
 5    "voltage": "vcc"
 6},
 7{
 8    "type": "analog",
 9    "range": "A0-A5",
10    "direction": "in"
11}]

We can see here that the six pins A0-A5 are in two definitions. This is because, for Arduinos, analog pins can function as analog pins OR digital pins. EDAsolver will now take this into account. These pins also have many other functions, but they are not included in this simple example.

Pin type

This is the most important key in the pin definition. Here are some examples of pin types:

  • digital

  • analog

  • spi

  • pwm

  • i2c

  • serial

  • usb

  • pc_serial

  • motor

  • hdmi

  • stepper

  • pi_cam

  • composite

  • 3_5_mm_jack

  • interrupt

As you can see, the definition of a pin type is fairly liberal. USB is actually defined as a single pin. So is the 3.5 mm jack for audio. These pin types are fairly uncommon but they are useful in solving designs for the Raspberry Pi and other single board computers.

There are several pin types that are in boldface. This is because they are what is known as pin groups. These pin groups are associated with multiple physical pins on the device. I2C, for example, needs both an SDA pin and an SCL pin. I2C can also support multiple slaves on a single line. The full syntax of pin groups will be described later on.

Pin range

This key specifies the pins that the definition applies to. A range syntax is used for convenience, because often the definition can apply to dozens of pins. The range syntax will work with any alphabetic prefix and a numeric suffix. Commas separate terms in the range string.

Pin direction

Every pin definition must have a direction associated with it. The valid directions are:

  • in

  • out

  • inout

Directions are chosen logically and prevent misconnections. Here are a few examples:

  • A digital pin on an Arduino would be an inout pin because these pins can both function as logic outputs or inputs depending on the software.

  • A PWM pin on an Arduino would be an out pin because these pins are designed for outputting PWM, not sensing the duty cycle as an input.

  • A standard hobby servo would have a PWM in pin because the servo needs to be sent a PWM control signal as an input. It cannot output PWM on its own.

  • An I2C bus on a microcontroller would be an out because the microcontroller would function as an I2C master.

  • An I2C sensor would have an I2C in because it functions as an I2C slave.

  • An H-bridge motor driver would have a motor out and the actual motor would have a motor in.

  • A USB host would be an out, a USB device would be an in, and a USB OTG device would be an inout.

Hosts will generally be of type out while slaves will be of type in.

Pin voltage

Often, pins will operate at certain logic levels. Common logic levels are 3.3V and 5V. If a logic level that is higher than the device’s logic level is applied, damage is very possible. In addition, logic levels that are too low run the risk of not being interpreted correctly. These points are important to consider in a design. The value to this key can either be set to an absolute voltage or a named voltage. For example, named voltages such as “vcc” allow the pin voltage to assume whatever the supply voltage happens to be, which can vary.

If a pin can operate at multiple logic levels, this can be specified by an array with the various logic levels.

Warning

Voltages are not required to be specified for pins, because there are some examples of pins where it does not matter. The vast majority of pins, however, should have voltages specified, so be sure to include them, otherwise incorrect designs might result.

Pin attributes

Pin attributes are any attributes that are specific to the pin that might matter in a design. A great example is the maximum stall current supported by motor controllers. Here are the pins provided by the TB6612FNG dual motor driver:

1[{
2    "type": "motor",
3    "range": "A,B",
4    "max_stall_current": 1.5,
5    "direction": "out"
6}]

This specifies that the A and B outputs are not rated for a stall current above 1.5A. While adding attributes has no effect on the base behavior of the pins, it allows powerful selections like the following example from the pin requirements of a simple hobby motor:

1[{
2    "type": "motor",
3    "range": "vcc",
4    "max_stall_current_$gt": 0.5,
5    "direction": "in"
6}]

Because of line 4, only motor drivers that can handle a stall current of at least 500mA will be considered. This means that the TB6612FNG driver described above will work with this motor.

Attributes are for provided pin definitions and selections are for required pin definitions.

Pin group syntax

Pin group definitions have the same syntax as normal definitions except that they have a groups key instead of a range key. Multiple groups can be specified in the groups array.

While certain pin groups have a standard set of pins, not all of these are required to be used by components, as is the case in practice. Often times, only a MOSI line will be used or one direction of a serial connection.

Components that require groups like these will by default seek out providers that supply pin groups like these. In practice, however, sometimes these protocols are implemented in software through bit banging. This can easily be specified in EDAsolver by overriding the components pin group and replacing it with simple digital pins.

Support for user-defined groups is not implemented at this time.

spi group

The SPI group has “ss”, “mosi”, “miso”, and “sck” pins.

 1{
 2    "type": "spi",
 3    "groups": [{
 4        "ss": "10",
 5        "mosi": "11",
 6        "miso": "12",
 7        "sck": "13"
 8    }],
 9    "direction": "out",
10    "voltage": "vcc"
11}

This example is an out because it is an SPI master.

i2c group

The I2C group has “sda” and “scl” pins.

1{
2    "type": "i2c",
3    "groups": [{
4        "sda": "A4",
5        "scl": "A5"
6    }],
7    "direction": "out",
8    "voltage": "vcc"
9}

This example is an out because it is an I2C master.

Warning

EDAsolver does not currently check for slave address collisions and these must be checked manually until support for this is added.

serial group

The serial group has “rx” and “tx” pins.

1{
2    "type": "serial",
3    "groups": [{
4        "rx": "0",
5        "tx": "1"
6    }],
7    "voltage": "vcc"
8}

Of course, when connected, TX lines will connect to RX lines and vice versa. Serial groups do not have a direction by the definition of the protocol.

pc_serial group

The pc_serial group has “rx” and “tx” pins.

1{
2    "type": "pc_serial",
3    "groups": [{
4        "rx": "0",
5        "tx": "1"
6    }],
7    "voltage": "vcc"
8}

Of course, when connected, TX lines will connect to RX lines and vice versa. Serial groups do not have a direction by the definition of the protocol.

stepper group

Note

Stepper support is still in development. There are of course many other ways to drive a stepper but this configuration works for basic cases.

The stepper group has “a1”, “a2”, “b1”, and “b2” pins.

 1{
 2    "type": "stepper",
 3    "groups": [{
 4        "a1": "a1",
 5        "a2": "a2",
 6        "b1": "b1",
 7        "b2": "b2"
 8    }],
 9    "direction": "in"
10}

This is example has an in direction because it is a stepper motor, not a controller.