microsoft / jacdac

Device and service catalogs for Jacdac.

Jacdac Specification, Device and Service Catalogs

Jacdac is a bus-based plug-and-play hardware/software stack for microcontrollers and their peripherals (sensors/actuators), with applications to rapid prototyping, making, and physical computing.

This repository contains the service specifications and device definitions.

• Read online documentation at https://aka.ms/jacdac
• Join the dicussions as https://github.com/microsoft/jacdac/discussions
• File an issue at https://github.com/microsoft/jacdac/issues

Contributing

The list of open source repositories related to Jacdac is at https://microsoft.github.io/jacdac-docs/github/ .

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Legal Notices

Microsoft and any contributors grant you a license to the Microsoft documentation and other content in this repository under the Creative Commons Attribution 4.0 International Public License, see the LICENSE file, and grant you a license to any code in the repository under the MIT License, see the LICENSE-CODE file.

Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.

Privacy information can be found at https://privacy.microsoft.com/en-us/

Microsoft and any contributors reserve all other rights, whether under their respective copyrights, patents, or trademarks, whether by implication, estoppel or otherwise.

jacdac's Issues

Extract jdspectool parser

Eventually we should have live editor for the spec language in the spec web site. Would be nice to move the parser into its own file so that I can slurp it in the web.

role manager

Refactor do "role" -> "device"

Emit constants in specdata

Would be nice to emit a "specconstants.ts" file with all numberical constants from the specification -- or just in specdata.ts.

JD_SERVICE_NUMBER_CRC_ACK breaks service abstraction.

JD_SERVICE_NUMBER_CRC_ACK is a command (sort of), but appears as a service number/index. Any reason this couldn't be a command in the control service?

Add reserved range on events

To match other commands/registers and it might be useful in the future.

makecode simulator integration

• samples...

range on registers

servo pulse spec should give a range hint to help users.

In general, any register with range can easily be used with scaled values too.

clean out JACDAC of CODAL

We still have the legacy JACDAC implementation in CODAL. How much of it do we still need?

Device error state

Is there a register to surface an error state in device?

_base has all sensor register?

There's a bunch of registers on base that are sensor specific, like cablirate and so forth. But sensor does not have calibrate.

sunset jacdac.org

If you search jacdac today, most of the hits land on jacdac.org. In order to send a consistent message, we need sunset the jacdac v1 web site and redirect to the new web site.

document blinking modes with gifs

• fast blink: panic
• slow blink: not connected

specify that a register does not change on its own

If we know that a register will not change on its own, we can do further opts.

deviceClass => firmwareIdentifier

Fix for #41

Barometer

A barometer sensor can be used to measure breathing if place on the exit vent of a mask.

temperature what does it mean?

The operating temperate of device may vary and we curerntly don't have enough info to raise an alarm or not.

My GPU runs at 84deg when playing CoD, it's normal. But this temparure might not be acceptable for other devices.

When does a device run hot? does it raise events?

spec revisions

• factor out frames and packets @jamesadevine
• reserve version bits in frame flags @mmoskal
• history section with dates and deltas -- not needed now
• sws, replace physical @jamesadevine
• frames/packets move into separate doc @jamesadevine
• remove requirements page @jamesadevine
• commands/actions/registers in specification/service layer @jamesadevine
• glossary @tballmsft
• Pipes and events in Service page @mmoskal
• copy content from current jacdac site to docs/pages/index.mdx @pelikhan
• hardware/power/electrical specification @sehodges @jamesadevine
• connect specification @sehodges
• html redirect and comment @jamesadevine
• cool images of connectors @sehodges @mgabrieledamone
• bus architecture image @tballmsft
• JACDAC favicon? @mgabrieledamone
• hardware connector repository @jamesadevine
• update color scheme for material ui @mgabrieledamone https://in-your-saas.github.io/material-ui-theme-editor/

naming rules

We need to specify rules for name:

• maximum length for all identifiers
• shortName / name: should we camelize always? can we move to "name", "displayName" like in DTDL

move specification to /spec folder

Move v0, v1 spec to markdown files under /spec folder.

I will slurp those files into jacdac-ts.

is streaming should automatically stop if no one is listening

It's easy to start streaming but stopping is much harder. When there are multiple listeners, a listener should not stop the streaming otherwise the other will loose data ... but ... that means never stopping the streaming once started. Or the listener might just go away without stopping streaming.

IMO, a device should stop streaming if it has not received a streaming command in x seconds.

shorten packet to fit into BLE large packets

Use BLE large packets and use 242bytes or something.

Document unit

Document the list of unit support in the specification tool.

data aggregator support for storage

Some data collection scenario are offline and we need a way to store data and retreive it.

packet identifier already used

Try this in https://microsoft.github.io/jacdac-ts/tools/service-editor

# Pressure Button

A button with pressure reading.

        identifier: 0x16e8c679
        extends: button

## Registers

    ro pressure2: u8 @ reading

Reads the current pressure of the button.

WebBLE layer

Define BLE service + WebBLE support

Analog sensor should have low, high events

Don't use map for enums

Would be best to start enums as an array to please my graphql representation.

Don't add _ to name

It's a bit of a weird convention to have the _ in base/sensor. I'd just use the name.

reserver version bits in frame flags

please add breadcrumbs at top of doc for page ancestors

Now that we are getting more hierarchy, it would be useful to have a single line at the top of a document showing the hierarchy, with links to parent pages. Example

Reference -> Protocol Specification -> Physical Layer

acceleraometer fields should be ax, ay, az

In general use naming convention that match the data.

Use SpecML units

https://www.iana.org/assignments/senml/senml.xhtml

rename service_number field everywhere

I suggest we rename service_number to service_index, which more accurately reflects that the value of the field is an index into a device's advertised list of services.

optional register

Specificy in the spec that registers can be optional.

import uf2 random number generator

@pelikhan can you import the uf2 random number generator as a react component so i can embed it in the spec page?

https://github.com/microsoft/uf2/blob/master/patcher/index.html

rename 'dummy' directory to 'hal'

the files in the "dummy" directory of "interfaces" really represent the hardware abstraction layer that JD relies on. Can we use a different name than "dummy"? Perhaps "hal"?

Document "repeat"

Can you add a section about repeat in the spec? not sure how to interpret it.

Clean up old repositories

The top hits on google are still garbage.

button should have a frac unit

device -> module

In IoT world, it's all device... but we build device out of JACDAC modules, so module would make more sense.

Otherwise everything is a device: JACDAC devices combined into another devices, which is also a JACDAC device and so on.

Internal smooth policy for sensor

It might make sense in particular scenario to control how a device processes sensor data internally. For example, one could decide to apply a first order filter, keep the max value or just keep the last value.

• default is probably filter based on the specs of the sensor
• specific case like looking for spikes would require keeping max

Fix polling strategy

Too much polling or too little

"Music" service should probably be renamed "buzzer"

Eventually, we should be able to open a pipe and send MIDI commands to a proper sound generator.

Batch mode for fast sensor

Fitbit supports a batched reading mode to reduce the frequency of packets and send multiple readings at once.
https://dev.fitbit.com/build/guides/sensors/accelerometer/#batched-readings

Specifically, the sensor might be able to poll the data at a faster rate internally but unable to stream fast enough.

Practical example: measure forces when an object falls and hits the ground. It will typically a very short large spike which will probably be missed by the sampling.

How many devices can we sample on the bus when we are streaming at 100Hz?

spectool does not generate BaseCmd.Event

crank extends not parsed properly

jacdac/dist/spec.json

Line 871 in 55bd414

"extends": [],

Specify preferred polling rate

It doesn't make sense to poll temperatue 10x per second, but acceleraomter data maybe. Can we have a hint in the spec?

Losing events

In the record page, when devices are streaming, button events are lost.

• connect accelerometer,
• enable collection on fields
• select button event to start/stop
• try click and event are not coming in

Add support for tags

Models are commonly tagged to enable search, grouping, etc...

I'm proposing to align to https://project-haystack.org/doc/TagModel as far as the syntax.

Status for services? stable/unstable

Should we have a formal flag for service specifiaction that indicate the level of maturity of the specification. Maybe something like

    status: dev <-- still under development
    status: stable <-- no more changes allowed