Device History Record (DHR) API

The following is a summary of the functions currently needed for the Device History Record API. The DHR is intended to be stored in the inventory system (currently Invent; possibly xTuple or an Invent/xTuple hybrid in 2010). The DHR client has to be able to do simple tasks like upload attachments and set comments, but also more complicated things like functioning as a test database.

The following changes need to be made before the invent system can be used for processing Beta diagnostic logs.

Comment

1. User can create comments on a serialized part. 1. All comments are uniquely identified by an id number 1. The content of a comment is unformatted text. 1. pseudo-code:

set_comment(
comment_text text,
serial_number int (default = None),
comment_id int (default = None),
type int (default = "General")
)

1. Replaces the content of the comment identified by "comment_id" with comment_text 1. If comment_id is not specified, creates a new comment for the serialized part 1. If neither comment_id nor serial_number is specified, returns an error 1. Returns the comment_id of the created or updated comment 1. If comment_id identifies a comment which does not belong to serial_number, returns an error. 1. Type is a valid type from the cmnttype table 1. User can delete a comment through the API 1. pseudo-code :

delete_comment(comment_id)

1. returns boolean, true for success, false for failure 1. User can retrieve comment through the API 1. pseudo-code:

get_comment(comment_id)

1. returns text of comment body 1. User can get list of comments for a serialized part 1. pseudo-code:

list_comments(serial_number)

1. returns list of comment_ids

Attachment

1. User can attach a document to a serialized part. 1. All documents are stored at external URLs, and the attachment of a document is really the association of a URL. 1. All documents are uniquely identified by an id number 1. User can add a document 1. pseudo-code:

set_attachment(
attachment_url text,
serial_number int (default = None),
attachment_id int (default = None),
type int (default = "General")
)

1. Replaces the content of the attachment url identified by "attachment_id" with attachment_url 1. If attachment_id is not specified, creates a new attachment for the serialized part 1. If neither attachment_id nor serial_number is specified, returns an error 1. Returns the attachment_id of the created or updated attachment 1. If attachment_id identifies a comment which does not belong to serial_number, returns an error. 1. Type is a valid type from the appropriate type table 1. User can delete a attachment through the API 1. pseudo-code :

delete_attachment(attachment_id)

1. returns boolean, true for success, false for failure 1. User can retrieve attachment through the API 1. pseudo-code:

get_attachment(attachment_id)

1. returns URL of attachment 1. User can get list of attachments for a serialized part 1. pseudo-code:

list_attachments(serial_number)

1. returns list of attachment_ids

Characteristics

1. User can set valid key values for a part 1. pseudo-code:

set_key(
key text,
part_id int
)

1. Creates a key with the name as the specified text 1. User can delete key values 1. pseudo-code:

delete_key(
key text,
part_id int
)

1. Deletes the key with the matching key value for the part 1. If any characteristics use this key, the function fails 1. If the key does not exist for the part, the function fails 1. Returns true if successful, or false if unsuccessful 1. User can list key values 1. pseudo-code:

list_keys(part_id int)

1. Returns a list of keys for the part 1. User can set key/value pairs for a serialized part 1. key/value pairs are called Characteristics 1. User can add a characteristic 1. pseudo-code:

set_characteristic(
key text,
value text,
serial_number int
)

1. Replaces the value identified by the combination of key and serial_number 1. If the key does not exist for the serialized part, creates a new key/value pair 1. Returns true if successful, or false if unsuccessful 1. User can delete a characteristic through the API 1. pseudo-code :

delete_characteristic(
key text,
serial_number int
)

1. deletes the specified characteristic if it exists 1. returns boolean, true for success, false for failure 1. User can retrieve characteristic through the API 1. pseudo-code:

get_characteristic(
key text,
serial_number int
)

1. returns value of characteristic, or empty string if not present 1. User can get list of characteristics for a serialized part 1. pseudo-code:

list_characteristics(serial_number)

1. returns list of keys

Assembly Associations

Each major component has different subcomponents. Users need to figure out what type of component it is and get the subcomponents. 1. User can get a description of an item. 1. pseudo-code:

get_item_description(serial_number)

1. returns a string containing the description (i.e., name) of the item. 1. User can get a list of all serialized components in a serialized assembly at a specified datetime. 1. pseudo-code:

get_children(serial_number,datetime)

1. Returns a python list of serial numbers. 1. Datetime is an optional parameter, and defaults to now. 1. Does this return the parts that are actually in the specific serialized assembly in question, or does it return the BOM of the part? 1. User can get the parent of a serialized part. 1. pseudo-code:

get_parent(serial_number,datetime)

1. Returns a serial number. 1. Datetime is an optional parameter, and defaults to now. 1. Does this return the parts that are actually in the specific serialized assembly in question, or does it return the BOM of the part?

1. When given a reference and a type name, it returns the serial of the component in that type 1. pseudo-code:

get_component(serial_number, description)

1. example:

shoulder_ref = get_component(68-04178-01001, 'PR2_SHOULDER')
# Return None if no shoulder listed in the full_arm

1. why is this necessary? can this be accomplished by checking the output of the previous command? 1. get_assembly(serial_number) Call it with parent's serial to get full tree. 1. Can we drop this and have the client walk the tree?

Device History

When processing diagnostic logs, it is important to be able to recall the history of moves of every part of the robot to compute use.

1. User can get a list of historical changes to the composition or membership of a serialized component. 1. pseudo-code:

get_history(serial_number)

1. returns a list of changes 1. Each change is a list comprising the datetime of the change followed by a string for the type of change, either Parent or Children

This will allow a precise record of move. The goal is to process .bag files of diagnostics by MCB serial numbers, and associate them with the correct assemblies, and other components (slip rings, etc).

Troubleshooting

Review Process