Midlib Module Reference

Owned by Stella Lau
Last updated: Feb 09, 2013Version comment
11 min read

See also the MIDLIB API Document, MIDLib API Development Guide.pdf.

Camera Class

The Camera class represents the whole demo board or emulator board. It wraps mi_camera_t from the midlib API.

Constructor

Camera(index)

The parameter is which physical camera, and must be from 0 to midlib.num_cameras - 1.
Under DevWare camera 0 is always the camera that is currently selected in DevWare. Other cameras are accessible with indices from 1 to midlib.num_cameras - 1

Camera(filename)

Create an in-memory midlib camera object from the filename. The file can be an image or video, or a sensor data file. If it's an image or video, grab_frame() will retrieve the pixel data. This provides a convenient way to load an image file into Python. If it's a sensor data file, the Camera object is populated with the sensor and register information from the file, but no I/O is possible.


Attributes

sensor

RO

The Sensor object for the camera. None if there is no sensor.

name
product_name

RO

pCamera->productName. Ex: 'Aptina Imaging DEMO2'.

num_chips

RO

Number of additional chips, defined by chip data files from board_data directory. Normally at least one for the FPGA on the camera board.

version
product_version

RO

pCamera->productVersion. Normally the FPGA version. Ex: 0xB5

firmware_version

RO

pCamera->firmwareVersion. Normally the product_id in the upper 16 bits and the firmware version in the lower 16 bits. Ex: 0x10070025.

product_id

RO

pCamera->product_id. Normally the USB product ID (PID), one of the mi_product_ids constants. For a thrid party board it could be anything.

All mi_modes

RW

All midlib camera modes are exposed as attributes. Getting the attribute calls mi_getMode() and setting the attribute calls mi_setMode(). Always an integer value. Example:
camera.MI_SHIP_SPEED = 100



Methods

chip(index)
chip(name)

Returns a Chip object for the specified chip. Parameter can be an integer index or a string name.
Index must be from 0 to camera.num_chips – 1.
Name must match the name of a defined chip.
Ex: hssa = camera.chip('HSSA Deserializer')

update_frame_size(width, height, bitsperclock, clocksperpixel)

Forces new image width and height, and new bits-per-clock and clocks-per-pixel values for the camera. If any parameter is 0 or omitted the current value is kept. In DevWare, values inconsistent with the current image type can cause a crash; prefer devware.image() instead.

grab_frame()

Attempts to grab a single image from the camera (call mi_grabFrame()). Returns a tuple with the first member an integer return code, and the second member a bytearray object with the raw binary data. The return code is one of the mi_error_code constants. MI_GRAB_FRAME_ERROR is usually a timeout. Other errors are usually because of a mismatch between the current settings for the image dimensions or image type and what the sensor is really doing.
Example:
returncode, img = camera.grab_frame()

invalidate_reg_cache()

Discard all cached register values. DevWare normally does this automatically as needed, such as after a reset or SOC command that will change many registers and variables. However there may be circumstances where you need to call it explicitly, such as for a device that DevWare does not recognize.

getmode(mode)

Get the value of a midlib camera mode by mode ID number. Equivalent to mi_getMode().

setmode(mode, value)

Set the value of a midlib camera mode by mode ID number. Equivalent to mi_setMode().

probe_far_bus()

Calls mi_ProbeFarBus(). For ICP-HD call this at the appropriate point in the startup sequence.

load_prom(ship_addr, type, label=label, dest=address)

Load sensor settings from the headboard EEPROM. Ship_addr is the base address of the EEPROM. Type is one of 'PGA', 'CCM', or 'SCRATCHPAD'. Label is an optional label to load a specific setting. Dest is memory address, only used for SCRATCHPAD.
Example:
midlib.Camera(0).load_prom(0xA8, 'PGA', label='FACTORY')

refresh_sensor_file(filename)

Reload the register list from a sensor data file. This is intended to be used after loading a firmware patch that added new variables.



Sensor Class

The Sensor class represents the sensor or SOC chip. In the case of Rainbow2 or similar, it represents the Rainbow2 and the attached sensors as a group. Other chips on the same I2C bus as the sensor are represented by Chip objects. The data comes from the sensor data file. It wraps mi_sensor_t from the midlib API.

Constructor

Normally you would construct a Sensor object using the sensor attribute of a Camera object. However the Sensor constructor can be called directly.

Sensor(camera=cam)

Returns a Sensor object given the parent Camera object. Same as cam.sensor.

Sensor(cameranum=index)

Returns a Sensor object given the index of a camera device. Same as Camera(index).sensor.


Attributes

reg

Returns a RegisterSet object that can be used to conveniently access the sensor registers.

name
sensor_name

Sensor name. Midlib sensorName. Ex. 'A-3132SOC'.

version_name

Sensor version as a string. Midlib versionName. Ex: 'REV2'

version
sensor_version

Sensor version as an integer. Midlib sensorVersion. Ex: 2

part_number

Sensor part number as a string. Midlib partNumber. Ex: 'MT9T112'

file_name

Sensor data file name. Midlib sensorFileName. For a physical sensor, this is the .xsdat file. For bitmap or video file pseudo-sensor, it's the image or video file.

base_addr
ship_addr

Sensor SHiP base address. Midlib shipAddr. Ex: 0x78. Read/write.

num_regs

Number of registers.

addr_size
reg_addr_size

Width of a register address in bits. Usually 8 or 16.

data_size
reg_data_size

Width of a register in bits. Usually 8 or 16.

width

Current image width. To change use devware.image() for now.

height

Current image height. To change use devware.image() for now.

image_type

Current image type as a string. To change use devware.image() for now.

full_width

Nominal full image width of sensor. Midlib fullWidth.

full_height

Nominal full image width of sensor. Midlib fullHeight.

pixel_bits

Significant bits per pixel. Midlib pixelBits.

pixel_bytes

Bytes per pixel in memory. Midlib pixelBytes.

All Sensor attributes are read-only unless otherwise noted.

Methods

There are no methods.

Chip Class

The Chip class represents an addition chip on the I2C bus, defined by a chip data file (from the board_data directory). Wraps mi_chip_t.

Constructor

Normally you would construct a Chip using the chip() method of a Camera object. However the Chip constructor can be called directly.

Chip(camera=cam, index=i)

Construct a Chip from a given parent Camera object and a chip index. The index defaults to 0. Same as cam.chip(info).

Chip(cameranum=c, index=i)

Construct a Chip from a given parent camera index and chip index. Both cameranum and index default to 0. Same as Camera(c).chip(info).


Attributes

reg

Returns a RegisterSet object that can be used to conveniently access the chip registers.

name
chip_name

A chip name from the chip data file. Midlib chipName. Ex: 'DEMO2 B5'.

base_addr

SHiP base address. Ex: 0x64.

num_regs

Number of registers.

addr_size

Width of a register address in bits.

data_size

Width of a register in bits.

All Chip attributes are read-only.

Methods

There are no methods.

RegisterSet Class

The RegisterSet class is a convenience class for constructing Register objects. It has no real equivalent in midlib, but could be said to correspond to the regs array of a mi_sensor_t or mi_chip_t.
See the Tutorial chapter, and the Register Class section for more information and examples. The pre-existing variable reg is a RegisterSet object created by reg = midlib.Camera(0).sensor.reg.

Constructor

Normally you would construct a RegisterSet object with the reg attribute of a Sensor or Chip object, but the constructor can be called directly.

RegisterSet(parent=camera, chipnum=i)

Construct a RegisterSet with the given parent Camera and an index indicating which chip. Chipnum = -1 indicates the sensor. Under DevWare the parent is optional and defaults to the currently selected camera. The chipnum is optional and defaults to -1.

RegisterSet(parent=sensor)

Construct a RegisterSet corresponding to the given Sensor object.

RegisterSet(parent=chip)

Construct a RegisterSet corresponding to the given Chip object.


Attributes

num_regs

RO

The number of registers.

All register names

RW

The symbolic names of all the registers defined in the sensor data or chip data file become attributes of the RegisterSet object.
Getting the attribute constructs a Register object. To read the register get one of the value attributes of the Register object.
Ex: dp = reg.DATA_PEDESTAL.value
Setting the attribute constructs a Register object and sets the value or float_value attribute of the Register object depending on whether the value is a float or not.
Ex: reg.DATA_PEDESTAL = 42
(Similarly, the bitfields of a register are attributes of the Register, so for example set a bitfield like reg.READ_MODE.LOW_POWER = 1.)


Methods

exists(symbol)

Returns True or False depending on whether the named register exists.

exists(rsymbol, bsymbol)

Returns True or False depending on whether the named register/bitfield exists.

reg(symbol)

Construct a Register object by symbolic name lookup.

reg(addr, bitwidth)
reg(addr_space, addr, bitwidth)

Construct a Register object that corresponds to a hardware register address. If the device is a sensor that has multiple pages of registers, the addr_space parameter is required. The bitwidth parameter is optional and defaults to the natural register width of the device.

var(driver, offset, bitwidth)

Construct a Register object that corresponds to a firmware variable address. The bitwidth parameter is optional and defaults 16 bits.

sfr(addr, bitwidth)
sfr(phy_region, addr, bitwidth)

Construct a Register object that corresponds to a physical RAM address. If the device is a sensor that has multiple physical memory regions, the phy_region parameter is required. The bitwidth parameter is optional and defaults to the natural register width of the device.


Looping Over All Registers

The RegisterSet object is iterable, and the iteration produces each of the registers defined for the parent device. In other words, if reg is a RegisterSet object, the following will loop over all registers of the device.
for rr in reg:
print(rr.symbol)

Register Class

The Register class represents a hardware register, firmware variable, sensor SFR, sensor memory location, or any other type of register that is supported by midlib. It wraps mi_reg_data_t from the midlib API.

Constructor

In most cases you would construct a Register object implicitly using a RegisterSet method or attribute. It's possible to call the constructor explicitly when needed, such as when specifying the SHiP base address to access any arbitrary device on the bus.
A register is specified by its symbolic name or address, and a parent object. The parent can be a Sensor or Chip object, possibly specified as a Camera object and chip index number.
You can specify any arbitrary device and register location accessible by I2C, even if the device is not defined by any Sensor or Chip objects. In this case you would not specify a parent object, but instead provide the SHiP base address, register address size and register data size.
If there is a parent object, but the register is not defined in the parent's sensor data or chip data file, then you can specify a span or bitwidth for it. Otherwise the values come from the file.

Register(parent=camera, chipnum=chip, ...)

Specify parent as camera and chip number. Under DevWare the parent defaults to the currently selected camera. The chipnum defaults to -1 indicating the sensor.

Register(parent=sensor, ...)

Specify the parent as the given Sensor object.

Register(parent=chip, ...)

Specify the parent as the given Chip object.

Register(..., index=i)

Select the i'th register in the parent's sensor data or chip data file.

Register(..., symbol=name)

Select a register in the parent's sensor data or chip data file by symbolic name.

Register(..., addr=addr, addr_space=space, addr_type=type, span=span)

Identify the register by its address, address space (optional, defaults to 0) and address type (optional, defaults to 'REG').
The address type can be 'REG', 'VAR', 'SFR', 'MEM', 'IND', 'FAR1' or 'FAR2'.
The span can also be specified to indicate the total width. For memory the span is in bytes. For registers it's in the natural register size of the device. If the register is defined in the parent's sensor data or chip data file then the width is taken from there and the span parameter is ignored.

Register(ship_addr=base, addr_size=asize, data_size=dsize, addr=addr)

No parent. Instead explicitly specify the SHiP base address, register address size and register data size. The addr_size defaults to 8 and the data_size defaults to 16. This can access any arbitrary device on the bus.

Register(far_ship_addr=base, addr_size=asize, data_size=dsize, addr=addr)

Like above, but access a device on the bus master of an ICP-HD, Rainbow2 or SOC with a bus master.


Attributes

value

RW

The value of the register as an unsigned int with no numerical conversion.
You can write a list of values, and it will do a burst write.

float_value

RW

The value of the register with numerical conversion according to the data type. For example if the data type is fixed8 (8 fraction bits) then 2.0 converts to 0x200.
You can write a list of values, and it will do a burst write.

uncached_value

RO

Do an uncached read, no numerical conversion.

uncached_float_value

RO

Uncached read with numerical conversion.

symbol
name
unique_desc

RW*

The unique symbolic name for the register.

span
addr_span

RO

For a hardware register, how many adjacent registers to span to make one larger logical register.

addr
reg_addr

RO

The address of the register, or offset of the variable.

addr_space

RO

The register page, or variable driver number.

addr_type

RO

The type of register. "REG", "MCU", "SFR", "IND", "FAR1", or "FAR2".

addr_space_id

RW*

The ID of the address space of this register, from the sensor data file. For example 'CORE', 'SYSCTL', etc.

addr_space_name

RW*

The descriptive name of the address space from the sensor data file. For example '0: Core Registers'.

addr_size

RO

The width in bits of the register address.

ship_addr

RO

The base address of the device this register is on.

far_ship_addr

RO

The base address of the device this register is on, if it is accessed though a bus master on the main device or SOC.

mask
bitmask

RW*

The valid bits.

default
default_val

RW*

The default value.

rw

RO

If rw is 0 this indicates the register is read-only. 1 indicates read-write. 2 indicates write-only.

datatype

RW

The data type of the register. See the INI File User's Guide.

minimum

RW

Recommended minimum value, as a floating point number (in other words, after datatype numeric conversion).

maximum

RW

Recommended maximum value, as a floating point number.

bitwidth

RO

The width of the register in bits. For a hardware register, taking into account the span. 8, 16, or 32 bits.

desc
reg_desc
display_name

RW*

The short description from the sensor data or chip data file.

detail

RO

The detailed description from the sensor data or chip data file.

long_desc

RO

Long description from the ldat file.

num_bitfields

RO

How many bitfields are defined for this register.

All bitfields

RW

All bitfields defined for this register in the sensor data or chip data file become attributes of the register. Getting the attribute returns a Bitfield object. To read the bitfield get the value or float_value attribute of the Bitfield.
Setting the attribute constructs a Bitfield object and sets the value or float_value attribute depending on whether the value is a float or not.
  • These attributes are only writable if the register is not defined in the parent's sensor data or chip data file.

    Methods

    bitfield(mask)

    Constructs a Bitfield object with this register as the parent and the given bitmask.

    bitfield(symbol)

    Constructs a Bitfield object with this register as the parent and the given symbolic name.

    burst_read(count)

    Read count successive registers starting from the address of this register object, normally using a single long I/O operation for best performance. Returns a list object with the result values. Burst read may not be supported for register types that are accessed indirectly.

    burst_read_float(count)

    Same as burst_read(), but translates the data according the data type of the register and creates a list of floating point values.

    Looping Over All Bitfields

    The Register object is iterable, and the iteration produces each of the bitfields defined for the parent register. In other words, if rr is a Register object, the following will loop over all bitfields of the register.
    for b in rr:
    print(' ', b.symbol)

    Bitfield Class

    The Bitfield class represents a subset of the bits in a hardware register, firmware variable, device SFR (memory-mapped register), or any other type of register that is supported by the Register class. It wraps mi_bitfield_t from the midlib API.

    Constructor

    In most cases you would construct a Bitfield object using the bitfield() method or a named bitfield attribute of a Register object.

    Bitfield(parent, index=i)

    Construct a Bitfield object from a parent Register object and an index into the array of defined bitfields for the register.

    Bitfield(parent, mask=m)

    Construct a Bitfield object from a parent Register object and a bitmask.

    Bitfield(parent, symbol=name)

    Construct a Bitfield object from a parent Register object and a bitfield symbolic name.

    Attributes

    value

    RW

    The value of the bitfield as an unsigned int with no numerical conversion. Writing to a bitfield always uses an uncached read in the read-modify-write cycle.

    float_value

    RW

    The value of the bitfield with numerical conversion according to the data type. Writing to a bitfield always uses an uncached read in the read-modify-write cycle.

    uncached_value

    RO

    Do an uncached read, no numerical conversion.

    uncached_float_value

    RO

    Uncached read with numerical conversion.

    parent

    RO

    The parent Register object.

    symbol
    name
    id

    RW*

    The symbolic name for the bitfield.

    mask
    bitmask

    RW*

    The bitmask of the bitfield.

    default

    RO

    The default value (derived from the default value of the parent).

    datatype

    RW

    The data type of the bitfield. See the INI File User's Guide.

    minimum

    RW

    Recommended minimum value, as a floating point number (in other words, after datatype numeric conversion).

    maximum

    RW

    Recommended maximum value, as a floating point number.

    rw

    RW*

    If 0 then this bitfield is defined as read-only. If 1 then it is read-write. 2 indicates write-only.

    desc
    display_name

    RW*

    The short description from the sensor data or chip data file.

    detail

    RO

    The detailed description from the sensor data or chip data file.

    long_desc

    RO

    Long description from the ldat file.
  • These attributes are only writable if the bitfield is not defined in the sensor data or chip data file.

    Methods

    There are no Bitfield methods.

    Midlib Methods

    delay(ms)

    Delay for the specified number of milliseconds.

    Midlib Constants

    home

    The Aptina Imaging installation directory.

    num_cameras

    How many cameras were detected.

    All mi_error_code

    All midlib API mi_error_code contants. Example: midlib.MI_CAMERA_SUCCESS.

    All mi_product_ids

    All midlib API mi_product_ids constants. Example: midlib.MI_DEMO2.

    All mi_reg_accessibility

    All midlib API mi_reg_accessibility constants. Example: midlib. MI_RW_READONLY.

    All mi_rx_types

    All midlib API mi_ rx_types constants. Example: midlib.MI_RX_HISPI.

    All mi_rx_modes

    All midlib API mi_rx_modes constants. Example: midlib.MI_RX_HISPI_S.