add i2c support for orthogonal devices ER-301

[nightmorph]

initial i2c command support for er301.

after seeing the forum thread, i read up on the er301 i2c implementation, took a quick look through teletype's ops for the 301, and came up with this first attempt at supporting that set of commands using crow's lua format.

i think i've got the correct signed/unsigned value types and ranges, but i'm not sure what the 301 uses/expects internally. some of the voltages or values might need to be float, for example, but i didn't see a way to set signed float values. 301's internals aren't entirely clear, here.

notes:

• all er301 params are also getters, with the exception of TOGGLE and PULSE. i omitted their get lines entirely, based on jf.lua. but that's the only device+op that doesn't have it. all the other devices' ops use get = false, so i'm not sure if the get line needs to be set at all if false.
• teletype uses SC.CV.foo format, with SC as the prefix for all er301 commands. i'm not sure if er301 expects to receive SC.foo exactly from crow, or if the prefix doesn't matter. for now, i've left the name/prefix as er301 at the top of the file; and simple command names like cv_slew and tr_pol.
• some er301 i2c params expect to use values from TO (telex-o) commands. i'm not sure if that requires TXo support in crow.
• there is no support for multiple er301 units; i'm not sure how to set this in crow's lua. second and third er301 units would have the addresses 0x32 and 0x33.

this support may not be complete; but at least it's a start. i don't have crow or TXo to test, and my er301 is from the first batch: its i2c pins are not the pre-bridged/fixed version on later units. so this crow+er301 support will need testing and updating by folks who have all the right hardware.

[csboling]

For documentation purposes it is maybe worth knowing that ER-301 does not interpret a CV.SLEW message the same way this is meant on Teletype, but instead sets the time to ramp from 0 to 1V, as indicated here.

[nightmorph]

For documentation purposes it is maybe worth knowing that ER-301 does not interpret a CV.SLEW message the same way this is meant on Teletype, but instead sets the time to ramp from 0 to 1V, as indicated here.

i pulled the docs text from the 301 wiki, which doesn't mention the 0-1V time. if needed, the patch can easily be adjusted to reflect this.

[nightmorph]

brian from O|D provided some helpful discussion on the er301 forum regarding expected data types and signed-ness, so there will be a revision to the .lua patch soon.

• may as well rename it sc.lua, in keeping with teletype's OP format, and to save some bytes when calling ops.
• it won't need so many mixed u16, s16, etc types.
• the er301 doesn't send any info back; there are no get responses. all crow ops should be set only.
• it seems er301 only receives s16 integers, and it converts that internally to the values it needs (e.g. voltage). so this should simplify what has to be coded on the crow side of things, if no matter what a param's value is, it's only ever sent as s16.

[tehn]

thankyou for jumping in on this!

i'm good with calling it sc for TT continuity.

[nightmorph]

here's the revised version, using the proper data type that er301 expects to receive: only signed 16bit integers. it does all the conversion it needs internally. also, it does not support get ops; it never transmits anything back.

i left the OP name as er301 in this update, as @trentgill made a good point regarding OP names, which is that sc could be confused with supercollider, given the crow and norns contexts. SC.foo was teletype opcode for the module's name, Sound Computer, but it with crow's relaxed space constraints, it makes sense to leave the opname in the longer er301 form.

i still haven't figured out how to address multiple er301 modules, which will require more skill at modifying crow's i2c framework than i have. but i'm partial toward ii.er301[1].cv(2,3), with [1-3] as the specific device, since there can only be three er301 addresses of 0x31, 0x32, 0x33. though this is where sc[1].cv(2,3) is a bit more readable than an alphanumeric OP name.

[tehn]

looking great!

[trentgill]

Looks great! Couple small things before merging:

• Missing 2 closing curly-braces } right before the end of the file.
• You can remove all of the get params. This is an optional param that should only be used if there is a matching getter.

Below is a refinement which can come later (though will be a breaking change if we don't do it now)
///

I read through the OD forum thread, and was a little confused about the data types being used.

The desired functionality is that ii.er301.cv(1, 3.0) should set port 1 to 3.0 volts. I don't believe that will work right now. For Just Friends I added the s16V datatype which means "the data is sent as a signed 16bit integer, but should be mapped using TT's V scaling". This means the following are equivalent: TT= JF.NOTE V 1 and crow= ii.jf.play_note(1.0).

What is the integer representation of 1 volt on er301? I'm super happy to add the handful of scaling lines to the crow system to enable this native handling of those values (and they will likely be useful for other ii modules!).

[trentgill]

Missing 2 closing curly braces right before this last one.

[trentgill]

here's a binary built with the file provided if you have the hardware! https://www.dropbox.com/s/hohjct1v87lkq9w/crow-v0.0.9-8-g2b017da.zip?dl=0

[nightmorph]

Looks great! Couple small things before merging:

• Missing 2 closing curly-braces } right before the end of the file.
• You can remove all of the get params. This is an optional param that should only be used if there is a matching getter.

thanks; i’ll clean it up and send in the fixed version. 🐦

The desired functionality is that ii.er301.cv(1, 3.0) should set port 1 to 3.0 volts. I don't believe that will work right now. For Just Friends I added the s16V datatype which means "the data is sent as a signed 16bit integer, but should be mapped using TT's V scaling". This means the following are equivalent: TT= JF.NOTE V 1 and crow= ii.jf.play_note(1.0).

What is the integer representation of 1 volt on er301? I'm super happy to add the handful of scaling lines to the crow system to enable this native handling of those values (and they will likely be useful for other ii modules!).

i’m not sure crow needs to convert at all — from what upstream said on the O|D forum, er301 does the conversion internally with whatever TT sends. since crow doesn’t have to go through teletype, does it need to worry about scaling? for er301’s handling of voltages, there’s a bit in the wiki on using SC.CV from teletype:

http://wiki.orthogonaldevices.com/index.php/ER-301/Teletype_Integration#SC.CV_Unit

any of the following Teletype commands:

SC.CV 42 N 12
SC.CV 42 V 1
SC.CV 42 VV 100
SC.CV 42 1638
will cause all instances of SC.TR units with port equal to 42 to slew to the value of 0.1 (which corresponds to the external value of 1V).

Value conversions
The Teletype maps the integers -16383 to 16383 (note: 16383 = (2^14) − 1) to the output voltages -10V to 10V. Since the ER-301 maps the voltages -10V to 10V to the internal values of -1 to 1, ER-301 values are calculated from Teletype raw values like this:

Value in ER-301 = Value in Teletype / (divided by) 16383

[trentgill]

The quoted bit you added at the end suggests you want to use the s16V type which does that division automatically.

If you just use s16, users will have to write ii.er301.cv(42, 1638) to get 1 volt.

Instead if you use s16V, then it will be ii.er301.cv(42, 1.0), which seems preferable to me (even though it's different to Teletype). This would only be for the parameters that represent volts though (ie. cv, cv_set, and cv_off).

[nightmorph]

Instead if you use s16V, then it will be ii.er301.cv(42, 1.0), which seems preferable to me (even though it's different to Teletype). This would only be for the parameters that represent volts though (ie. cv, cv_set, and cv_off).

that does make sense, though yeah, only for volt params. script writers shouldn't have to convert 1638 in their heads just to set a specific voltage.

here's a quote from upstream:

It only receives s16. There is no sending implemented.

All of the values from SC.CV commands are converted to the ER-301’s internal representation for audio/CV which is 32-bit floats, and such that 1V becomes 0.1. In other words: (s16 from Teletype)/16384.

i've made the other requested changes; should i also change the type to s16v before sending in the updated patch? i can head over to O|D for any questions/ideas/answers.

[trentgill]

I think s16V makes most sense (and would align to crow's volts as native values).

Do you have an ER-301? I can send you the firmware binary so you can test it before we merge to master? If not, is there someone who can test this for us?

[nightmorph]

i do have an er301. unfortunately, mine is from the first batch, which doesn't have the revised cpu board that later versions do--it requires a (very easy, apparently) solder bridge and flip-flopped i2c cable pinouts, but i lack the tools and ability to perform the mod.

there's a thread on lines in which folks list their i2c modules. or maybe put it as a general test-request to that thread/lines.

edit: revised patch with all the above changes sent in; and a couple of testing requests are now posted to lines.

[trentgill]

Sounds good! I'm sure someone will be able to help out!

[trentgill]

ayeee - sorry for the nitpick but it needs to be s16V with a capital V.

[nightmorph]

no worries; not sure how i missed that. somethingsomething built-in lowercase macro? fixed in latest!

[trentgill]

@nightmorph I've pulled your changes into the #224 which adds support for txI, and fixes an off-by-one error on ansible too. If we merge that, I'll close this PR as your changes will be pulled in there.

[nightmorph]

rad! thank you so much! i was just alerted today on the O|D forum that ansible had the same off-by-one issue. i was hoping that it would be a general crow-level fix to benefit all supported modules, rather than doing it in an er301-specific lua file somewhere. thanks again!

[trentgill]

Closing in favour of #224