NEW serialosc - developer tools

  • hey everybody,

    here's a new developer tools patch i have recently created with @tehn. it covers basic device handling for communicating between app & device in max6.

    importantly it includes a main page describing best practices when grabbing / losing focus in serialosc. it is intended that older apps will be updated to take these ideas into account.

    please note, this patch requires:
    – serialosc 1.2a (
    – serialosc.maxpat installed per the setup guide (see point 4:

    also included are walkthroughs for:
    – device auto-connect techniques
    – patch auto-focus techniques
    – general use of the osc protocol for monome devices

    i'll continue to expand this patch to include general use cases & advanced led interaction techniques as time permits.

    feedback is most welcome!

  • hi trent,

    patch looks great! it's a very useful resource and has been needed for a while. glad you and tehn have done it justice. look forward to seeing it grow.

    few notes on the live_focus subpatch. instead of the 'loadbang' at the top try 'live.thisdevice'. ensures the live api has loaded fully before you use it.

    also for gaining focus when the device/plugin is selected it may be better to observe the 'selected_device' of the parent track's view. this way it would work with abletons internal device selecting e.g when scrolling through a tracks devices with an apc40 or similar.

  • thanks for the tips myr — would really appreciate if you could put that stuff into a patcher i could drop into the devtools patch. my experience with the live.api is extremely limited, and mostly borrowed from digging through stretta's old patches which were made with a much earlier iteration of said tools.

    glad you're digging it! also, i've been trying to rework stretta's m4l bundle using serialosc, but have had some issues with the bpatcher not responding. any thoughts?

  • no worries, i'll have a look after some sleep.

    had some issues in m4l using serialosc. needed to use a few deferlow objects in my serialosc patch to slow things down. nothing specific i can think of, but i'll try and rework a stretta app with the new serialosc.maxpat tomorrow as a test. or if you can post any of the patches i'll see if i have any problems using them.

  • here's the first modded patch i slapped together to see if the process would work. the interface is pretty shoddy, but it works. couldn't get the auto-focus command to function though as above.

  • Here's a question, the Windows setup instructions don't look different. Should the serialosc.maxpat be added to the patches folder in Windows as well? If so, can those instructions, or should they, be amended?

    I've finally got my mk going (yeah!) but it doesn't seem to work well with older apps when serialosc.maxpat is replaced with the new version, any ideas why this might be? (examples: polygome, press cafe)

  • This looks pretty good. Would have been super amazing when I was starting out!

    I don't see it explicitly mentioned anywhere, but does the latest serialosc(.maxpat) auto convert for older devices?

    The maxpat serial looks worlds/crazy different than what I'm using now (a simplified version of the old one) and I'm not super eager to risk breaking anything as what I have now "works".

    Will the older serialosc stop working with new serialosc versions?

  • @shimoda
    updating the windows setup instructions is on my 'to do' list though as i don't personally have a windows computer i'm hesitant to change it blindly from the working arrangement. as i understand it though, the new serialosc using UDP directly (not zeroconf) is a real boon for windows users, so would be good to update.

    can you help update it to use serialosc1.2a & the new serialosc.maxpat?

    apologies this didn't come round sooner — i certainly would have transitioned mlrv to serialosc at a much earlier stage if it had been!

    i'm not sure what you mean by 'convert for older devices' — as i understand, serialosc is compatible with all older devices and sends the same commands even from an old 40h. as such i would be pretty confident you can swap it out and everything will work directly. of course you can test it by moving your old version out of your patch's folder and putting the new one in the max folder?

    the older serialosc.maxpat should continue working for the foreseeable future (it's just OSC packets anyway).

    even if you don't want to try the new serialosc.maxpat, it would be a nice idea for you to have 1 copy of your serialosc.maxpat living in your max folder, then everything will be streamlined, and when people download your apps they'll just use the standardised one??

  • I mean that if I send varibrightness messages (/level vs /set) older monome devices completely ignore the messages, rather than interpreting the data. A few of us (2D10 and raja primarily) worked out a very robust workaround in which you pick the type of device you're using and it formats the messages appropriately.
    Until that I maintained two separate versions of the app, which was a pita for sure.

    I ask because there was some talk a while back where serialosc (the server/app) would handle that functionality. At the time it didn't.

  • ahhh i understand — i've been grappling with vari-bright messages myself and have resorted to a switching mechanism which turns the /level mesages on/off. however, due to the nature of how i was handling data, there's no consistent threshold where a non-varbright device should be on/off.

    do you have a link to the workaround you mentioned?

    totally understand the need for having this, but perhaps it better belongs inside the application as i'm sure there's situations where the one solution won't work without modification. perhaps we could include it in apps as an abstraction?

    as an example:
    in mlrv, with a var-bright device, disarming the reverb send uses a /level message to fade out the reverb toggle button linked to the reverb time. if i have a non-var-bright device i would prefer it to be off as soon as i toggle it off, rather than waiting til the end of the fade time.

  • The stuff is all in here:

    I don't remember if that's in there too, but raja made a monome protocol detector, so The Party Van detects what kind of device you have (to the best of it's ability) and then automatically sends binary or varibrightness messages accordingly.

    My implementation of it all is here (including the arc version handling):
    (ugh nevermind. new forum still has brutal character length limits!)

  • if there's a proposal for a serialosc modification i'm up for it.

  • Indeed. If what's in the patch that's linked there can be handled by the serialosc server, that would be amazing!!

    (it queries the device type then adjusts the data accordingly).

    i guess the code that's there can get wrapped into the serialosc.maxpat, same goes for the arc resolution tweaking. so that as a programmer you always deal with varibrightness and 1024, but old devices are compatible by default.

  • Wow, this is terrific and coming just in the right moment for me. Thank you very much!!!

  • agree with @l00p only been learning max since january and this is very useful. need to have a poke around the focus bit and understand how that works.

  • beware, the m4l auto-focus business is currently not perfect — @myr is doing some good work bringing it up to spec. the max specific focus stuff is all solid though.

  • Hey guys,
    I'm trying to get started with all of this. I've been looking over this app, and I'm confused about the "hint":

    simply copy and paste this patch into your application, and change the [yourpatch] to your apps name

    Does that mean that, if my patch were saved as "thumbs.maxpat" and I changed all the highlighted objects to put the word "thumbs" into it, it should register my arc?

    ex: r thumbsto-sosc

    or do I need a space, like:

    r thumbs to-sosc

    or the brackets as well?

    r [thumbs] to-sosc

    I've tried changing them all without brackets or spaces and I can't seem to get anything to happen. Any advice on where to go from here is very appreciated.

  • @yorke
    it's actually just a suggested naming convention. You could technically have a patch named something.maxpat and:

    [r a-big-pile-of-messages]

    and as long as your "s" object on the other end used the same name:

    "s a-big-pile-of-messages"

    you'd be fine.


    But you do want to remove the brackets and end up with something like "r thumbs-to-sosc"

    (just a space after the "s" or "r" and then dashes or underscores)

  • personally i'd leave the brackets and just change "yourpatch" to "the-real-name-of-your-patch". it's just a naming convention so that reading other people's patches is simplified.

  • A couple questions on this, as I finally got around to implementing.

    Do you still have two serialosc.maxpats? One for grid and one for arc?

    Using the dev tool patch I seem to get data from both devices coming out of the same serialosc.maxpat

    Also, when I try using two instances of it, they seem to cancel each other. I have to keep doing it and/or do it in a certain order before both light up/work.

    Lastly, the auto connect, I send my device ID (m00000004) to the device I want to connect and it doesn't work consistently.

    In other words, i can't seem to get two serialosc.maxpats auto loaded automatically.

    Oh yeah, lastly lastly, the change/connect button doesn't seem to follow the logic of the background/connection making it confusing to know if its actually connected or not, unless I'm misunderstanding what it is supposed to do.

  • Beuler?

    I can figure out workarounds by modding the serialosc, but I want to keep it 'compliant', so it's the same as all other serialosc.maxpats (apart from graphically).

  • I agree the connect button situation is a bit confusing in general and as it relates to multiple devices.

    - When nothing is connected it's a light grey button that reads 'connect'
    - When you click and are connected, the button becomes dark grey and reads 'change'

    I only have one device currently so I'm trying to understand:

    Say I have a monome currently connected, and I now plug an arc in, do I have to click the change button to select my arc? If so, this would disconnect my grid device...therefore one device at a time?

  • Although I can't check I'm fairly sure it's still one serialosc.maxpat per device. Have a look at the updated grain storm, I'm sure there is a maxpat for grid and arc

  • Yeah that has one for each, but none of the autoconnect stuff. It also didn't come with a serialosc.maxpat either

    Is part of the idea that apps don't have a local version of it and there's just one general one in the search path?

    Also in looking at it more, it looks like that sending anything into the right inlet doesn't actually pass that data along. Anything going into that inlet just fires of a [t b b b b] with nothing else passed on (ie device ID), so not sure how to auto connect on that front.

  • i probably shouldn't had waded in as i'm still new to the max stuff - better off waiting for tehn or galapagoose.

    The idea is that there are no local copies of the patch which i suppose is aimed at making future serialosc tweaks and updates easier / less hassle to implement.

    I've been looking (to help get my head around it myself) and i can't find autoconnect / focus implemented with the 1.2 .maxpat. You might be the first to pull it off Rodrigo ;-)

  • It's in the developer tools patch (bottom right).

    I had set up autoconnect for my patch (and my devices) as I don't like having to 'connect' in software, so it's good to see that's a consideration for general usage.

    It's just the balance of trying to do what works for me, but keep it standardized.

  • I just had success with autoconnect in maxforlive.

    I'm not sure what I was doing wrong before because it seems pretty straight forward. Anyway, attached is a screenshot of my patch.

    the message goes into the right inlet of serialosc into a route object that routes monitor messages one way and anything else (our device ID) another way.

    The device ID then goes through a pattr object that gives it a named data wrapper of deviceid. Next, the message is prepended with symbol so we now have something like

    symbol m0000724

    Next, it goes into a subpatcher called auto-connect-check but I stopped tracing there.

    262 x 427 - 23K
  • Unless I'm missing something or I have an old serialosc.maxpat, input 2 doesn't go to a route object. Nor is there an auto-connect subpatch!

  • Sounds like you may not have the proper version of serialosc.maxpat??

    From the first post of this thread:

    please note, this patch requires:
    – serialosc 1.2a (
    – serialosc.maxpat installed per the setup guide (see point 4:

  • Blah, I checked it recently too.

    Ok, now I need to change all my graphics for that version....

    So the autoconnect worked for you?

  • Yup, autoconnect and autofocus are working great.

  • Yup, I can confirm the same.

    I'll officially say, that it's confusing as fuck downloading all the needed files when they are spread across different forum posts and parts of the webpage.....

  • I assume this is the official repository for the serialosc bonjour server?

    However, I do not see anything resembling the installer that people are recommended to install within the setup instructions in the docs ( For example, It be great if stable installers were located in this repository because I could clone it, track it, and always be up to date.

    I see another repository for serialosc-installers but it looks like source code only.

    Can't find anything quickly for serialosc.maxpat.

    I think this may be the point Rodrigo is trying to convey: Even for developers it's a bit fragmented.

  • yes these are all issue for certain — i've been trying to help streamline the wiki, but after 6 years or so of edits it's become a bit of a sprawling mess. the main challenge is thinning all that down without breaking most of the links people have created in the past.

    if you are looking for links to the most updated versions of all of these things (installers and .maxpat) the best place to look is the setup page for 1st time users ( a little counter-intuitive perhaps? any suggestion as to how to present this info more logically would be appreciated

    how have you found using the right-inlet 'auto-connect' with two devices (and two instances of serialosc.maxpat)? personally i can't seem to get both devices to auto-connect from either direct messages or pattr recall — have you found a workaround?

  • Oops, I missed this comment a couple days ago.

    It's working fine for me just sending the serial numbers to each .maxpat.

    One thing I'm noticing now is that the focus outlet doesn't work. It sometimes spits out a 1, but never the 0.
    Looking more closely the 'connect' button has a [t i i], but only the first (order) i is connected to anything. Not sure if that's related.

    I'm torn because I can work around all of these problems, but I want to avoid having an especially 'custom' .maxpat. I pimped the look of it out to match my patch as I'm not into the courier thing, but the 'guts' are all the same...for now.

    As far as the files needed, having a single download or something like that. Or even doing a git thing, though I find git pages confusing as shit, personally. Or shit, some stickies in the forum with latest/current versions of files.

    And the 1.2a installer still says 1.1, which doesn't help the confusion either...

  • all of this sounds right on. i've just got back from an internet-less holiday so will be testing an updated version of the .maxpat for release asap.

    maybe you could send post the version you've made to work around these issues and i could see if it can all be integrated into the standard patch.

    would it be useful to you if there were some user interface options built in? you could for example send loadmess: "font helvetica" or "fontsize 12" into one of the inlets to change the text, or is that not sufficient? i don't want to make this too complex and would prefer the visual interface to stay cohesive across the different applications.

    you're thoughts here are much appreciated! i've got a few minor edits built in that stretta suggested, and would like to make the new version fix any underlying issues. also excited about adding a 'version' message that prints to the max window on instantiation -- such a simple thing to do, but makes it so much easier to troubleshoot!

  • Having more graphic options would be handy. For mass consumption it shouldn't default to courier either way, as tehn appears to be the only person who does courier apps anyways.

    For the most part I went to town on the colors, and largely the highlight/on colors for the background and buttons.

    I've not actually figured out any workarounds as I'm trying to make it work as is.

    A couple of things that would be real icing on the cake things are if it could automatically tell what era device you have, and alter the messages accordingly.

    I already do this in my patch, but it would super useful for everyone if that aspect of programming was completely transparent.

    Attached are the bits of my patch that do that.

    Essentially there's a bit that determines the era grid you have, then automatically sets the correct varibrightness option. Then there's a big section which converts varibrightness messages to binary, so you make all your interface things varibrightness, and the user can downsample that to binary if needed. This happens automatically.

    For the arc, as far as we (raja, myself, and others) couldn't figure out how to tell wether it was a 2011 or 2012+ version, so there's just a dropdown menu to pick the resolution. And to streamline things, if you pick a high resolution one, it automatically enables the "ZXCV = press" thing.
    There's a finite amount of 2011 arcs out there, so if the serial numbers are logical, it can just check against a coll or something, and then default to 2012 otherwise.

    All of that stuff should really be built into serialosc (server), but it isn't, so building it into the .maxpat would be the next best thing.
    Either way, I'll incorporate it into my patch as it's super handy/useful from both developer and user sides.

  • hey rodrigo - sorry for my delay but finally getting back round to this.

    i'm currently adding some extra interface options into the .maxpat so you can send colour and font data from your patch via a loadbang. hopefully this will allow aesthetically minded individuals to use the default patch and not need to include a forked version.

    regarding the different functionality of devices, i've specifically left the handling of these parameters for the programmer to handle so as to maintain the maximum flexibility of the device (and handling of those parameters).

    as a developer myself, i can imagine situations where your patch is really useful and a great way to make the interactions simply and quickly. conversely though, i've run into situations where the parameters you've suggested wouldn't be logical at all — eg. gradual fades only make sense with 16level.

    as such i think the best approach is to leave the serialosc.maxpat as simple and open, providing a direct, unfiltered connection to the OSC port and then add your code into the developers-patch with a suggestion to use it for developing new patches. i think this is the best approach, particularly for users that are coding but only have access to a monochrome device — it would seem very difficult to require them to code in the new /led/level messages if they're not able to see what they look like. i've had lots of "this would look great with vari-bright" moments, which when implemented are entirely useless — this approach will hopefully avoid those situations.

    should have the new version up today some time...

  • Simple and open is good, but backwards compatibility (hardware wise) is important. Just using serialosc means you are writing for 1 of 3 possible hardware types (depending on what 'native' in your patch is).

    I know varibrightness still hasn't permeated a ton of stuff, but it breaks compatibility when it does turn up. I use it quite a bit in my patch (for two levels of button presses, and all my record indicators throb instead of pulse).

    Will the 'one serialosc' in the search path thing get a bit mucked up with people having old/other max patches in their max folder?

    Either way, looking forward to the aesthetically tune-able version!