The JUCE cross-platform C++ framework, with DISTRHO/KXStudio specific changes
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

594 lines
18KB

  1. /*
  2. ==============================================================================
  3. This file is part of the JUCE library.
  4. Copyright (c) 2017 - ROLI Ltd.
  5. JUCE is an open source library subject to commercial or open-source
  6. licensing.
  7. The code included in this file is provided under the terms of the ISC license
  8. http://www.isc.org/downloads/software-support-policy/isc-license. Permission
  9. To use, copy, modify, and/or distribute this software for any purpose with or
  10. without fee is hereby granted provided that the above copyright notice and
  11. this permission notice appear in all copies.
  12. JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  13. EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  14. DISCLAIMED.
  15. ==============================================================================
  16. */
  17. namespace juce
  18. {
  19. namespace BlocksProtocol
  20. {
  21. /** This value is incremented when the format of the API changes in a way which
  22. breaks compatibility.
  23. */
  24. static constexpr uint32 currentProtocolVersion = 1;
  25. using ProtocolVersion = IntegerWithBitSize<8>;
  26. //==============================================================================
  27. /** A timestamp for a packet, in milliseconds since device boot-up */
  28. using PacketTimestamp = IntegerWithBitSize<32>;
  29. /** This relative timestamp is for use inside a packet, and it represents a
  30. number of milliseconds that should be added to the packet's timestamp.
  31. */
  32. using PacketTimestampOffset = IntegerWithBitSize<5>;
  33. //==============================================================================
  34. /** Messages that a device may send to the host. */
  35. enum class MessageFromDevice
  36. {
  37. deviceTopology = 0x01,
  38. packetACK = 0x02,
  39. firmwareUpdateACK = 0x03,
  40. deviceTopologyExtend = 0x04,
  41. deviceTopologyEnd = 0x05,
  42. deviceVersion = 0x06,
  43. deviceName = 0x07,
  44. touchStart = 0x10,
  45. touchMove = 0x11,
  46. touchEnd = 0x12,
  47. touchStartWithVelocity = 0x13,
  48. touchMoveWithVelocity = 0x14,
  49. touchEndWithVelocity = 0x15,
  50. configMessage = 0x18,
  51. controlButtonDown = 0x20,
  52. controlButtonUp = 0x21,
  53. programEventMessage = 0x28,
  54. logMessage = 0x30
  55. };
  56. /** Messages that the host may send to a device. */
  57. enum class MessageFromHost
  58. {
  59. deviceCommandMessage = 0x01,
  60. sharedDataChange = 0x02,
  61. programEventMessage = 0x03,
  62. firmwareUpdatePacket = 0x04,
  63. configMessage = 0x10,
  64. factoryReset = 0x11,
  65. blockReset = 0x12,
  66. setName = 0x20
  67. };
  68. /** This is the first item in a BLOCKS message, identifying the message type. */
  69. using MessageType = IntegerWithBitSize<7>;
  70. //==============================================================================
  71. /** This is a type of index identifier used to refer to a block within a group.
  72. It refers to the index of a device in the list of devices that was most recently
  73. sent via a topology change message
  74. (It's not a global UID for a block unit).
  75. NB: to send a message to all devices, pass the getDeviceIndexForBroadcast() value.
  76. */
  77. using TopologyIndex = uint8;
  78. static constexpr int topologyIndexBits = 7;
  79. /** Use this value as the index if you want a message to be sent to all devices in
  80. the group.
  81. */
  82. static constexpr TopologyIndex topologyIndexForBroadcast = 63;
  83. using DeviceCount = IntegerWithBitSize<7>;
  84. using ConnectionCount = IntegerWithBitSize<8>;
  85. //==============================================================================
  86. /** Battery charge level. */
  87. using BatteryLevel = IntegerWithBitSize<5>;
  88. /** Battery charger connection flag. */
  89. using BatteryCharging = IntegerWithBitSize<1>;
  90. //==============================================================================
  91. /** ConnectorPort is an index, starting at 0 for the leftmost port on the
  92. top edge, and going clockwise.
  93. */
  94. using ConnectorPort = IntegerWithBitSize<5>;
  95. //==============================================================================
  96. /** Structure for generic block data
  97. @tags{Blocks}
  98. */
  99. template <size_t MaxSize>
  100. struct BlockStringData
  101. {
  102. uint8 data[MaxSize] = {};
  103. uint8 length = 0;
  104. static const size_t maxLength { MaxSize };
  105. bool isNotEmpty() const
  106. {
  107. return length > 0;
  108. }
  109. String asString() const
  110. {
  111. return String ((const char*) data, length);
  112. }
  113. bool operator== (const BlockStringData& other) const
  114. {
  115. if (length != other.length)
  116. return false;
  117. for (int i = 0; i < length; ++i)
  118. if (data[i] != other.data[i])
  119. return false;
  120. return true;
  121. }
  122. bool operator!= (const BlockStringData& other) const
  123. {
  124. return ! ( *this == other );
  125. }
  126. };
  127. using VersionNumber = BlockStringData<21>;
  128. using BlockName = BlockStringData<33>;
  129. //==============================================================================
  130. /** Structure describing a block's serial number
  131. @tags{Blocks}
  132. */
  133. struct BlockSerialNumber : public BlockStringData<16>
  134. {
  135. bool isValid() const noexcept
  136. {
  137. for (auto c : data)
  138. if (c == 0)
  139. return false;
  140. return isAnyControlBlock() || isPadBlock() || isSeaboardBlock();
  141. }
  142. bool isPadBlock() const noexcept { return hasPrefix ("LPB") || hasPrefix ("LPM"); }
  143. bool isLiveBlock() const noexcept { return hasPrefix ("LIC"); }
  144. bool isLoopBlock() const noexcept { return hasPrefix ("LOC"); }
  145. bool isDevCtrlBlock() const noexcept { return hasPrefix ("DCB"); }
  146. bool isTouchBlock() const noexcept { return hasPrefix ("TCB"); }
  147. bool isSeaboardBlock() const noexcept { return hasPrefix ("SBB"); }
  148. bool isAnyControlBlock() const noexcept { return isLiveBlock() || isLoopBlock() || isDevCtrlBlock() || isTouchBlock(); }
  149. bool hasPrefix (const char* prefix) const noexcept { return memcmp (data, prefix, 3) == 0; }
  150. };
  151. //==============================================================================
  152. /** Structure for the device status
  153. @tags{Blocks}
  154. */
  155. struct DeviceStatus
  156. {
  157. BlockSerialNumber serialNumber;
  158. TopologyIndex index;
  159. BatteryLevel batteryLevel;
  160. BatteryCharging batteryCharging;
  161. };
  162. //==============================================================================
  163. /** Structure for the device connection
  164. @tags{Blocks}
  165. */
  166. struct DeviceConnection
  167. {
  168. TopologyIndex device1, device2;
  169. ConnectorPort port1, port2;
  170. bool operator== (const DeviceConnection& other) const
  171. {
  172. return isEqual (other);
  173. }
  174. bool operator!= (const DeviceConnection& other) const
  175. {
  176. return ! isEqual (other);
  177. }
  178. private:
  179. bool isEqual (const DeviceConnection& other) const
  180. {
  181. return device1 == other.device1
  182. && device2 == other.device2
  183. && port1 == other.port1
  184. && port2 == other.port2;
  185. }
  186. };
  187. //==============================================================================
  188. /** Structure for the device version
  189. @tags{Blocks}
  190. */
  191. struct DeviceVersion
  192. {
  193. TopologyIndex index;
  194. VersionNumber version;
  195. };
  196. //==============================================================================
  197. /** Structure used for the device name
  198. @tags{Blocks}
  199. */
  200. struct DeviceName
  201. {
  202. TopologyIndex index;
  203. BlockName name;
  204. };
  205. static constexpr uint8 maxBlocksInTopologyPacket = 6;
  206. static constexpr uint8 maxConnectionsInTopologyPacket = 24;
  207. //==============================================================================
  208. /** Configuration Item Identifiers. */
  209. enum ConfigItemId
  210. {
  211. // MIDI
  212. midiStartChannel = 0,
  213. midiEndChannel = 1,
  214. midiUseMPE = 2,
  215. pitchBendRange = 3,
  216. octave = 4,
  217. transpose = 5,
  218. slideCC = 6,
  219. slideMode = 7,
  220. octaveTopology = 8,
  221. midiChannelRange = 9,
  222. MPEZone = 40,
  223. // Touch
  224. velocitySensitivity = 10,
  225. glideSensitivity = 11,
  226. slideSensitivity = 12,
  227. pressureSensitivity = 13,
  228. liftSensitivity = 14,
  229. fixedVelocity = 15,
  230. fixedVelocityValue = 16,
  231. pianoMode = 17,
  232. glideLock = 18,
  233. glideLockEnable = 19,
  234. // Live
  235. mode = 20,
  236. volume = 21,
  237. scale = 22,
  238. hideMode = 23,
  239. chord = 24,
  240. arpPattern = 25,
  241. tempo = 26,
  242. // Tracking
  243. xTrackingMode = 30,
  244. yTrackingMode = 31,
  245. zTrackingMode = 32,
  246. // Graphics
  247. gammaCorrection = 33,
  248. // User
  249. user0 = 64,
  250. user1 = 65,
  251. user2 = 66,
  252. user3 = 67,
  253. user4 = 68,
  254. user5 = 69,
  255. user6 = 70,
  256. user7 = 71,
  257. user8 = 72,
  258. user9 = 73,
  259. user10 = 74,
  260. user11 = 75,
  261. user12 = 76,
  262. user13 = 77,
  263. user14 = 78,
  264. user15 = 79,
  265. user16 = 80,
  266. user17 = 81,
  267. user18 = 82,
  268. user19 = 83,
  269. user20 = 84,
  270. user21 = 85,
  271. user22 = 86,
  272. user23 = 87,
  273. user24 = 88,
  274. user25 = 89,
  275. user26 = 90,
  276. user27 = 91,
  277. user28 = 92,
  278. user29 = 93,
  279. user30 = 94,
  280. user31 = 95
  281. };
  282. static constexpr uint8 numberOfUserConfigs = 32;
  283. static constexpr uint8 maxConfigIndex = uint8 (ConfigItemId::user0) + numberOfUserConfigs;
  284. static constexpr uint8 configUserConfigNameLength = 32;
  285. static constexpr uint8 configMaxOptions = 8;
  286. static constexpr uint8 configOptionNameLength = 16;
  287. //==============================================================================
  288. /** The coordinates of a touch.
  289. @tags{Blocks}
  290. */
  291. struct TouchPosition
  292. {
  293. using Xcoord = IntegerWithBitSize<12>;
  294. using Ycoord = IntegerWithBitSize<12>;
  295. using Zcoord = IntegerWithBitSize<8>;
  296. Xcoord x;
  297. Ycoord y;
  298. Zcoord z;
  299. enum { bits = Xcoord::bits + Ycoord::bits + Zcoord::bits };
  300. };
  301. /** The velocities for each dimension of a touch.
  302. @tags{Blocks}
  303. */
  304. struct TouchVelocity
  305. {
  306. using VXcoord = IntegerWithBitSize<8>;
  307. using VYcoord = IntegerWithBitSize<8>;
  308. using VZcoord = IntegerWithBitSize<8>;
  309. VXcoord vx;
  310. VYcoord vy;
  311. VZcoord vz;
  312. enum { bits = VXcoord::bits + VYcoord::bits + VZcoord::bits };
  313. };
  314. /** The index of a touch, i.e. finger number. */
  315. using TouchIndex = IntegerWithBitSize<5>;
  316. using PacketCounter = IntegerWithBitSize<10>;
  317. //==============================================================================
  318. enum DeviceCommands
  319. {
  320. beginAPIMode = 0x00,
  321. requestTopologyMessage = 0x01,
  322. endAPIMode = 0x02,
  323. ping = 0x03,
  324. debugMode = 0x04,
  325. saveProgramAsDefault = 0x05
  326. };
  327. using DeviceCommand = IntegerWithBitSize<9>;
  328. //==============================================================================
  329. enum ConfigCommands
  330. {
  331. setConfig = 0x00,
  332. requestConfig = 0x01, // Request a config update
  333. requestFactorySync = 0x02, // Requests all active factory config data
  334. requestUserSync = 0x03, // Requests all active user config data
  335. updateConfig = 0x04, // Set value, min and max
  336. updateUserConfig = 0x05, // As above but contains user config metadata
  337. setConfigState = 0x06, // Set config activation state and whether it is saved in flash
  338. factorySyncEnd = 0x07,
  339. clusterConfigSync = 0x08,
  340. factorySyncReset = 0x09
  341. };
  342. using ConfigCommand = IntegerWithBitSize<4>;
  343. using ConfigItemIndex = IntegerWithBitSize<8>;
  344. using ConfigItemValue = IntegerWithBitSize<32>;
  345. //==============================================================================
  346. /** An ID for a control-block button type */
  347. using ControlButtonID = IntegerWithBitSize<12>;
  348. //==============================================================================
  349. using RotaryDialIndex = IntegerWithBitSize<7>;
  350. using RotaryDialAngle = IntegerWithBitSize<14>;
  351. using RotaryDialDelta = IntegerWithBitSize<14>;
  352. //==============================================================================
  353. enum DataChangeCommands
  354. {
  355. endOfPacket = 0,
  356. endOfChanges = 1,
  357. skipBytesFew = 2,
  358. skipBytesMany = 3,
  359. setSequenceOfBytes = 4,
  360. setFewBytesWithValue = 5,
  361. setFewBytesWithLastValue = 6,
  362. setManyBytesWithValue = 7
  363. };
  364. using PacketIndex = IntegerWithBitSize<16>;
  365. using DataChangeCommand = IntegerWithBitSize<3>;
  366. using ByteCountFew = IntegerWithBitSize<4>;
  367. using ByteCountMany = IntegerWithBitSize<8>;
  368. using ByteValue = IntegerWithBitSize<8>;
  369. using ByteSequenceContinues = IntegerWithBitSize<1>;
  370. using FirmwareUpdateACKCode = IntegerWithBitSize<7>;
  371. using FirmwareUpdateACKDetail = IntegerWithBitSize<32>;
  372. using FirmwareUpdatePacketSize = IntegerWithBitSize<7>;
  373. static constexpr uint32 numProgramMessageInts = 3;
  374. static constexpr uint32 apiModeHostPingTimeoutMs = 5000;
  375. static constexpr uint32 padBlockProgramAndHeapSize = 7200;
  376. static constexpr uint32 padBlockStackSize = 800;
  377. static constexpr uint32 controlBlockProgramAndHeapSize = 3000;
  378. static constexpr uint32 controlBlockStackSize = 800;
  379. //==============================================================================
  380. /** Contains the number of bits required to encode various items in the packets */
  381. enum BitSizes
  382. {
  383. topologyMessageHeader = MessageType::bits + ProtocolVersion::bits + DeviceCount::bits + ConnectionCount::bits,
  384. topologyDeviceInfo = BlockSerialNumber::maxLength * 7 + BatteryLevel::bits + BatteryCharging::bits,
  385. topologyConnectionInfo = topologyIndexBits + ConnectorPort::bits + topologyIndexBits + ConnectorPort::bits,
  386. typeDeviceAndTime = MessageType::bits + PacketTimestampOffset::bits,
  387. touchMessage = typeDeviceAndTime + TouchIndex::bits + TouchPosition::bits,
  388. touchMessageWithVelocity = touchMessage + TouchVelocity::bits,
  389. programEventMessage = MessageType::bits + 32 * numProgramMessageInts,
  390. packetACK = MessageType::bits + PacketCounter::bits,
  391. firmwareUpdateACK = MessageType::bits + FirmwareUpdateACKCode::bits + FirmwareUpdateACKDetail::bits,
  392. controlButtonMessage = typeDeviceAndTime + ControlButtonID::bits,
  393. configSetMessage = MessageType::bits + ConfigCommand::bits + ConfigItemIndex::bits + ConfigItemValue::bits,
  394. configRespMessage = MessageType::bits + ConfigCommand::bits + ConfigItemIndex::bits + (ConfigItemValue::bits * 3),
  395. configSyncEndMessage = MessageType::bits + ConfigCommand::bits,
  396. };
  397. //==============================================================================
  398. // These are the littlefoot functions provided for use in BLOCKS programs
  399. static constexpr const char* ledProgramLittleFootFunctions[] =
  400. {
  401. "min/iii",
  402. "min/fff",
  403. "max/iii",
  404. "max/fff",
  405. "clamp/iiii",
  406. "clamp/ffff",
  407. "abs/ii",
  408. "abs/ff",
  409. "map/ffffff",
  410. "map/ffff",
  411. "mod/iii",
  412. "getRandomFloat/f",
  413. "getRandomInt/ii",
  414. "log/vi",
  415. "logHex/vi",
  416. "getMillisecondCounter/i",
  417. "getFirmwareVersion/i",
  418. "getTimeInCurrentFunctionCall/i",
  419. "getBatteryLevel/f",
  420. "isBatteryCharging/b",
  421. "isMasterBlock/b",
  422. "isConnectedToHost/b",
  423. "setStatusOverlayActive/vb",
  424. "getNumBlocksInTopology/i",
  425. "getBlockIDForIndex/ii",
  426. "getBlockIDOnPort/ii",
  427. "getPortToMaster/i",
  428. "getBlockTypeForID/ii",
  429. "sendMessageToBlock/viiii",
  430. "sendMessageToHost/viii",
  431. "getHorizontalDistFromMaster/i",
  432. "getVerticalDistFromMaster/i",
  433. "getAngleFromMaster/i",
  434. "setAutoRotate/vb",
  435. "getClusterIndex/i",
  436. "getClusterWidth/i",
  437. "getClusterHeight/i",
  438. "getClusterXpos/i",
  439. "getClusterYpos/i",
  440. "getNumBlocksInCurrentCluster/i",
  441. "getBlockIdForBlockInCluster/ii",
  442. "isMasterInCurrentCluster/b",
  443. "setClusteringActive/vb",
  444. "makeARGB/iiiii",
  445. "blendARGB/iii",
  446. "fillPixel/viii",
  447. "blendPixel/viii",
  448. "fillRect/viiiii",
  449. "blendRect/viiiii",
  450. "blendGradientRect/viiiiiiii",
  451. "blendCircle/vifffb",
  452. "addPressurePoint/vifff",
  453. "drawPressureMap/v",
  454. "fadePressureMap/v",
  455. "drawNumber/viiii",
  456. "clearDisplay/v",
  457. "clearDisplay/vi",
  458. "displayBatteryLevel/v",
  459. "sendMIDI/vi",
  460. "sendMIDI/vii",
  461. "sendMIDI/viii",
  462. "sendNoteOn/viii",
  463. "sendNoteOff/viii",
  464. "sendAftertouch/viii",
  465. "sendCC/viii",
  466. "sendPitchBend/vii",
  467. "sendPitchBend/viii",
  468. "sendChannelPressure/vii",
  469. "addPitchCorrectionPad/viiffff",
  470. "setPitchCorrectionEnabled/vb",
  471. "getPitchCorrectionPitchBend/iii",
  472. "setChannelRange/vbii",
  473. "assignChannel/ii",
  474. "deassignChannel/vii",
  475. "getControlChannel/i",
  476. "useMPEDuplicateFilter/vb",
  477. "getSensorValue/iii",
  478. "handleTouchAsSeaboard/vi",
  479. "setPowerSavingEnabled/vb",
  480. "getLocalConfig/ii",
  481. "setLocalConfig/vii",
  482. "requestRemoteConfig/vii",
  483. "setRemoteConfig/viii",
  484. "setLocalConfigItemRange/viii",
  485. "setLocalConfigActiveState/vibb",
  486. "linkBlockIDtoController/vi",
  487. "repaintControl/v",
  488. "onControlPress/vi",
  489. "onControlRelease/vi",
  490. "initControl/viiiiiiiii",
  491. "setButtonMode/vii",
  492. "setButtonType/viii",
  493. "setButtonMinMaxDefault/viiii",
  494. "setButtonColours/viii",
  495. "setButtonTriState/vii",
  496. nullptr
  497. };
  498. } // namespace BlocksProtocol
  499. } // namespace juce